Differences

This shows you the differences between two versions of the page.

--- load_categorical_map [2011/07/31 15:57]
hermann created
+++ load_categorical_map [2026/08/28 03:25] (current)
hermann Sync from local documentation review
@@ Line 1: / Line 1: @@
 ====== Load Categorical Map ======
 ===== Description =====
-This functor loads a map from a file whose cell identifiers represent categories. The file name and its path must be specified. If the map found at this path does not have category identifiers, this functor will automatically determine its category identifiers.
+Loads a categorical map — a map whose cells represent classes or categories — from a file. The file format is determined automatically from the filename's extension. If the loaded file does not already carry a categorization, one is determined automatically from the map's cell values. See [[Load Map]] for loading maps whose cells do not represent categories.
 ===== Inputs =====
-^ Name ^ Type ^ Description ^
+^ Name  ^ Type  ^ Description  ^
-| Filename  | [[ Map Filename Type|Map Filename  ]]  | Name of the file that contains the map to be loaded. Dinamica automatically determines the file format from a selected file extension.  |
+| Filename  | [[Map Filename Type]]  | Name and path of the file to load. If no path is given, the file is located relative to the model script.  |
 ===== Optional Inputs =====
-^ Name ^ Type ^ Description ^ Default Value ^
+^ Name  ^ Type  ^ Description  ^ Default Value  ^
-| Load As Sparse  | [[ Bool Type|Bool  ]]  | If true, the map is loaded as a sparse image. Sparse images have the advantage of storing only the cells containing non-null values, but they have diminshed access time. | False  |
+| Null Value  | [[Null Value Type]]  | Additional value to treat as null, alongside the file's own null value if it has one. Useful for assigning a null value to files that do not define one.  | .none  |
-| Define Null Value  | [[Bool Type|Bool  ]]  | This flag forces the cells with the same value of the "Null Value" parameter to be treated as a null cell. This is particularly useful for assigning a missing null value to a GeoTiff data.  | False  |
+| Storage Mode  | [[Enum Type]]  | Hint for how the map should be handled: Default follows the memory allocation policy in the application settings; Prefer Memory suggests loading the whole map into memory; Prefer Disk suggests keeping it on disk and loading it on demand, piece by piece; Load As Sparse suggests storing only non-null cells, minimizing storage at the expense of access time. This is only a hint and may be ignored. This is an advanced port.  | Default  |
-| Null Value  | [[Int Type|Int  ]]  | Value used to represent null cell. The "Define Null Value" flag must be set in order to define a null value. This is particularly useful for assigning a missing null value to a GeoTiff data.  | 0  |
+| Suffix Digits  | [[Non Negative Integer Value Type]]  | Number of digits used to render Step as a filename suffix. If Step needs more digits than this, it is used unmodified. If zero, no suffix is added. This is an advanced port.  | 0  |
-| Suffix Digits  | [[Non Negative Int Type|Non Negative Int  ]]  | Number of digits used to represent the image file name suffix.  | 2  |
+| First Window Coordinate X  | [[Real Value Type]]  | X coordinate of one corner of a crop window, in the map's projection units. Must lie within the file's extent. This is an advanced port.  | .none  |
-| step  | [[Non Negative Int Type|Non Negative Int  ]]  | Current step or model iteration. Files with the same name and numbered suffixes will be loaded sequentially according to the model step.  | None  |
+| First Window Coordinate Y  | [[Real Value Type]]  | Y coordinate of one corner of a crop window, in the map's projection units. Must lie within the file's extent. This is an advanced port.  | .none  |
+| Second Window Coordinate X  | [[Real Value Type]]  | X coordinate of the opposite corner of the crop window, in the map's projection units. Must lie within the file's extent. This is an advanced port.  | .none  |
+| Second Window Coordinate Y  | [[Real Value Type]]  | Y coordinate of the opposite corner of the crop window, in the map's projection units. Must lie within the file's extent. This is an advanced port.  | .none  |
+| Recreate Categories  | [[Boolean Value Type]]  | If true, the categorization is recreated from the loaded image's values, while preserving any categories already stored in the file. This is an advanced port.  | No  |
+| Step  | [[Non Negative Integer Value Type]]  | Current step or model iteration, appended to Filename as a numeric suffix; automatically bound to the innermost compatible container. This is an advanced port.  | .none  |
+| Workdir  | [[Workdir Type]]  | Work directory Filename is relative to; may be a folder or a Zip archive. When not bound, the directory containing the script is used. This is an advanced port.  | .none  |
 ===== Outputs =====
-^ Name ^ Type ^ Description ^
+^ Name  ^ Type  ^ Description  ^
-| Map  | [[ Categorical Map Type| Categorical Map  ]]  | The map loaded by the functor.  |
+| Map  | [[Categorical Map Type]]  | Loaded categorical map.  |
 ===== Group =====
-[[Functor List#Input/Output | Input/Output]]
+[[Functor List#Input / Output | Input / Output]]
 ===== Notes =====
-Readable formats: ers (ERMapper raster) tiff, or tif (GeoTiff) and asc (ArcView ASCII).
+When Null Value is given, any cell already equal to the file's own null value (if it defines one) is converted to Null Value, and any non-null cell that happens to equal Null Value is likewise promoted to null — so a value that meant "no data" before loading still means "no data" after, regardless of how the null definition changed.
-Coordinate systems supported for translation in ERMapper format: Geodetic (WGS 84, SAD69, NAD27, Corrego Alegre) and UTM (WGS84, SAD 69, NAD27, Corrego Alegre).
+The crop window (First/Second Window Coordinate X/Y) must either be left entirely at .none, loading the map in full, or have all four coordinates defined together; a partially defined window is not accepted.
-When a coordinate system is not supported, LOCAL projection and datum WGS84 are assumed. For ASCII/ArcGIS, LOCAL projection and datum WGS84 are always assumed.
+If Step is .none, the loaded filename has no numeric suffix.
-All Geotiff coordinate systems are supported if translation is not needed.
+For a list of file formats that Load Categorical Map can load, the supported [[wp>Map_projection|projections]] and [[wp>Datum_(geodesy)|datums]], check the [[Supported Map Formats#map_formats_supported_for_reading|supported map formats]].
-When GeoTiff cell dimension is not found, a 100 meter resolution is assumed.
+It is possible to load maps from [[wp>zip_(file_format)|Zip]] archives; Workdir may point directly to a Zip archive rather than a folder. See [[Useful Tips#loading_files_from_zip_files|this useful tip]] to know how to do it.
 ===== Internal Name =====
 LoadCategoricalMap