====== Load Map ======

===== Description =====

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 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 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]]  | 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  |
| 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  |
| 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 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]]  | Loaded map, or, when the crop window is defined, only the cropped window of it.  |

===== Group =====

[[Functor List#Input / Output | Input / Output]]

===== Notes =====

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.

===== Internal Name =====

LoadMap

===== Usage examples =====

See practical examples of this functor in [[lesson_4|Lesson 4: Opening and Saving maps]]