Differences

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

--- load_map [2026/07/05 00:26]
hermann
+++ load_map [2026/08/28 03:25] (current)
hermann Sync from local documentation review
@@ Line 3: / Line 3: @@
 ===== Description =====
-This functor loads a map from a file. The filename and its path must be specified.
+Loads a map from a file. The file format is determined automatically from the filename's extension. See [[Load Categorical Map]] for loading maps whose cells represent categories.
 ===== Inputs =====
 ^ Name  ^ Type  ^ Description  ^
-| Filename | [[Map Filename Type]]  | Name and path of input map file. File format is automatically selected based on the filename extension. If path is not specified, file location is the same of model script.  |
+| 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  ^
-| Null Value  | [[Null Value Type]]  | Additional value used to represent null cells. Cells with such value are also treated as null cells. This is particularly useful for assigning a null value to image files that do not have this definition.  | None  |
+| 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  |
-| Storage Mode  | [[Enum Type]]  | Flag suggesting how the map should be loaded. It is possible that the value defined by this flag may be ignored and have no effect. This is an advanced port.  | Default  |
+| 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  |
-| Load As Sparse  | [[Boolean Value Type]]  | 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 worse access time.  | False  |
+| 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 Integer Value Type]]  | Number of digits in the suffix that will be used to represent the step to which the file corresponds. If a greater number of digits is needed than this value, the step itself is used without modifications. If the number of digits is zero, no suffix is added to the file name. This is an advanced port.  | 0  |
+| 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  |
-| First Window Coordinate X  | [[Real Value Type]]  | X coordinate of the upper-left corner of the clipping window, expressed in the map projection units. The value must be within the map extent, otherwise the operation will fail. If null, the clipping window will not be defined and the map must be loaded in its entirety. The defined clipping is applied to all layers of the map.  | 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  |
-| First Window Coordinate Y  | [[Real Value Type]]  | Y coordinate of the upper-left corner of the clipping window, expressed in the map projection units. The value must be within the map extent, otherwise the operation will fail. If null, the clipping window will not be defined and the map must be loaded in its entirety. The defined clipping is applied to all layers of the map.  | 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 X  | [[Real Value Type]]  | X coordinate of the lower-right corner of the clipping window, expressed in the map projection units. The value must be within the map extent, otherwise the operation will fail. If null, the clipping window will not be defined and the map must be loaded in its entirety. The defined clipping is applied to all layers of the map.  | 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  |
-| Second Window Coordinate Y  | [[Real Value Type]]  | Y coordinate of the lower-right corner of the clipping window, expressed in the map projection units. The value must be within the map extent, otherwise the operation will fail. If null, the clipping window will not be defined and the map must be loaded in its entirety. The defined clipping is applied to all layers of the map.  | None  |
+| 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  |
-| Step  | [[Non Negative Integer Value Type]]  | Current step or model iteration. Files with the same name and numbered suffixes will be loaded sequentially according to the model step. This port automatically associates with 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  |
-| Workdir  | [[Workdir Type]]  | Workdir folder path. Can be a folder or Zip file. If not associated, the working directory is considered to be the location where the script is saved. This is an advanced port.  | None  |
-===== Output =====
+===== Outputs =====
 ^ Name  ^ Type  ^ Description  ^
-| Map  | [[Map Type]]  | The map loaded by this functor, or if defined, only the window specified by the clipping window parameters.  |
+| Map  | [[Map Type]]  | Loaded map, or, when the crop window is defined, only the cropped window of it.  |
 ===== Group =====
-[[Functor List#Input/Output | Input/Output]]
+[[Functor List#Input / Output | Input / Output]]
 ===== Notes =====
-See also [[Load Categorical Map]] for loading maps whose cells represent categories.
+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.
-If the "Null Value" parameter is specified, any cell corresponding to the original null value of the map, if provided, is converted to the new null value. This ensures that values originally represented by null value still representing null values, even if the null value definition changes. Any non-null value corresponding to the newly defined null value is also promoted to new null value.
+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.
-For a list of file formats that Load 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]].
+If Step is .none, the loaded filename has no numeric suffix.
-It is possible to load maps from [[wp>zip_(file_format)|Zip]] archives. See [[useful_tips#loading_files_from_zip_files|this useful tip]] to know how to do it.
+For a list of file formats that Load 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]].
-The clipping window parameters allow loading only a specific rectangular region of the map instead of the entire map. When all four window coordinate parameters are null (default), the entire map is loaded. To use the clipping window feature, all four coordinates (First Window Coordinate X, First Window Coordinate Y, Second Window Coordinate X, and Second Window Coordinate Y) must be defined together. If the clipping window parameters are provided, only the area corresponding to the clipping window is loaded.
+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.
-If the value of "Step" is null, the file read will not have a suffix.
 ===== Internal Name =====
@@ Line 54: / Line 51: @@
 See practical examples of this functor in [[lesson_4|Lesson 4: Opening and Saving maps]]