Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
load_map [2012/09/04 01:43] admin [Notes] |
load_map [2026/08/28 03:25] (current) hermann Sync from local documentation review |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Load Map ====== | + | ====== Load Map ====== |
| ===== Description ===== | ===== 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 ===== | ===== Inputs ===== | ||
| ^ Name ^ Type ^ Description ^ | ^ 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 ===== | ===== 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 worse 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 cells. 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. If the "step" input is unbound, this options is ignored. | 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 | |
| - | | 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 | |
| - | | Workdir | [[Workdir Type|Workdir]] | Workdir folder path. | 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 | | ||
| - | ===== Output ===== | + | ===== Outputs ===== |
| ^ Name ^ Type ^ Description ^ | ^ 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 ===== | ===== Group ===== | ||
| - | [[Functor List#Input/Output | Input/Output]] | + | [[Functor List#Input / Output | Input / Output]] |
| ===== Notes ===== | ===== 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. |
| - | For a list of file formats that Load Map can load, the supported [[wp>Map_projection|projections]] and [[wpDatum_(geodesy)|datums]], check the [[supported map formats]]. | + | 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. | ||
| ===== Internal Name ===== | ===== Internal Name ===== | ||
| LoadMap | LoadMap | ||
| + | |||
| + | ===== Usage examples ===== | ||
| + | |||
| + | See practical examples of this functor in [[lesson_4|Lesson 4: Opening and Saving maps]] | ||