Differences

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

--- load_map [2013/07/10 16:14]
admin [Optional Inputs]
+++ load_map [2026/08/28 03:25] (current)
hermann Sync from local documentation review
@@ Line 1: / Line 1: @@
 ====== Load Map ======
 ===== 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|Map Filename  ]] | 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|Null Value]]  | 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  |
-| 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 worse access time.  | 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  |
-| 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  |
+| 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  |
-| Workdir  | [[Workdir Type|Workdir]]  | Workdir folder path.  | None  |
+| 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  |
-===== Output =====
+| 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  |
+| 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  ^
-| Map  | [[Map Type|Map]]  | The map loaded by this functor.  |
+| 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.
+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.
+If Step is .none, the loaded filename has no numeric suffix.
+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]].
+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.
-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]].
 ===== Internal Name =====
 LoadMap
+===== Usage examples =====
+See practical examples of this functor in [[lesson_4|Lesson 4: Opening and Saving maps]]