Differences

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

--- rasterize_shape [2017/04/03 18:53]
hermann [Optional Inputs]
+++ rasterize_shape [2026/08/28 03:30] (current)
hermann Sync from local documentation review
@@ Line 1: / Line 1: @@
 ====== Rasterize Shape ======
 ===== Description =====
-This rasterizes a given shape file according to a set of parameters.
+Rasterizes a shapefile (or other OGR-supported vector source) into a map, using the given parameters. This functor wraps the GDAL library's ''gdal_rasterize'' utility.
 ===== Inputs =====
 ^ Name  ^ Type  ^ Description  ^
-| Input Shape Filename  | [[Map Filename Type]]  | The filename of the input shape that will be rasterized.  |
+| Input Shape Filename  | [[Generic Filename Type]]  | Filename of the input shape to rasterize.  |
-| Output Map Filename  | [[Map Filename Type]]  | The filename of the resulting map containing the rasterized shape.  |
+| Output Map Filename  | [[Map Filename Type]]  | Filename of the resulting rasterized map. Its format is selected from the file extension.  |
 ===== Optional Inputs =====
 ^ Name  ^ Type  ^ Description  ^ Default Value  ^
-| Default Output Value  | [[Real Value Type]]  | Default value used to represent all rasterized features from the input shape in the resulting map. Either this value or the "Shape Attribute Name" must be defined, but both can not be defined simultaneously.  |
+| Default Output Value  | [[Real Value Type]]  | Value assigned to every rasterized feature. Cannot be used together with Shape Attribute Name; exactly one of the two must be given.  | .none  |
-| Shape Attribute Name  | [[String Type]]  | Name of the shape attribute field used to define the values of the resulting map. Either the attribute name or the "Default Output Value" must be specified, but both can not be defined simultaneously.  |
+| Shape Attribute Name  | [[String Type]]  | Name of the shape's attribute field supplying the value assigned to each rasterized feature. Cannot be used together with Default Output Value; exactly one of the two must be given.  | .none  |
-| Output Map Cell Type  | [[Cell Type Type]]  | Data cell type of the resulting map. For this functor, the cell types Unsigned 1-Bit Integer and Signed 8-Bit Integer are just an alias for cell type Unsigned 8-Bit Integer.  | Signed 32-Bit Integer  |
+| Output Map Cell Type  | [[Cell Type Type]]  | Cell type of the resulting map. Unsigned 1-Bit Integer and Signed 8-Bit Integer are both treated as Unsigned 8-Bit Integer for this functor.  | Signed 32 Bit Integer  |
 | Output Map Null Value  | [[Null Value Type]]  | Null value of the resulting map.  | .default  |
-| Output Map Cell Width  | [[Real Value Type]]  | The cell width in the resulting re-projected map. Must be defined together with the cell height. However, the definition of expected cell height/width and number of lines/columns are mutually exclusive. The cell width must be expressed in unit compatible with the projection of the resulting re-projected map.  | null  |
+| Output Map Cell Width  | [[Real Value Type]]  | Cell width of the resulting map, in units compatible with its projection. Must be given together with Output Map Cell Height; mutually exclusive with Output Map Lines/Columns.  | .none  |
-| Output Map Cell Height  | [[Real Value Type]]  | The cell height in the resulting re-projected map. Must be defined together with the cell width. However, the definition of expected cell height/width and number of lines/columns are mutually exclusive. The cell height must be expressed in unit compatible with the projection of the resulting re-projected map.  | null  |
+| Output Map Cell Height  | [[Real Value Type]]  | Cell height of the resulting map, in units compatible with its projection. Must be given together with Output Map Cell Width; mutually exclusive with Output Map Lines/Columns.  | .none  |
-| Output Map Lines  | [[Positive Integer Value Type]]  | The number of lines expected in the resulting re-projected map. Must be defined together with the number of columns. However, the definition of expected number of lines/columns and cell height/width are mutually exclusive.  | null  |
+| Output Map Lines  | [[Positive Integer Value Type]]  | Number of lines of the resulting map. Must be given together with Output Map Columns; mutually exclusive with Output Map Cell Width/Height. This is an advanced port.  | .none  |
-| Output Map Columns  | [[Positive Integer Value Type]]  | The number of columns expected in the resulting re-projected map. Must be defined together with the number of lines. However, the definition of expected number of lines/columns and cell height/width are mutually exclusive.  | null  |
+| Output Map Columns  | [[Positive Integer Value Type]]  | Number of columns of the resulting map. Must be given together with Output Map Lines; mutually exclusive with Output Map Cell Width/Height. This is an advanced port.  | .none  |
-| Use Cell Center Only  | [[Boolean Value Type]]  | If true, the interception between lines/polygons and cells is calculated using the cell centers only. Otherwise, all parts of the cells are used. This flag must be set to true, if rasterizing shapes representing linear features (roads, rivers etc)  |
+| Use Cell Center Only  | [[Boolean Value Type]]  | If true, a cell is considered part of a feature based on its center only; if false, the whole cell area is considered. Must be true when rasterizing linear features (roads, rivers, and similar). This is an advanced port.  | Yes  |
-| Use Compression  | [[Boolean Value Type]]  | If true, the resulting re-projected map is compressed. The map compression option only works for GeoTiff (.tif) and HFA (.img) file formats. For other file formats this option is ignored. | true  |
+| Use Compression  | [[Boolean Value Type]]  | If true, the output map is compressed, for formats that support it (GeoTiff and HFA; ignored for other formats). This is an advanced port.  | Yes  |
-| Layer Name  | [[String Type]]  | Layer from the datasource containing the input features that will be rasterized. This definition and "Select Statement" are mutually exclusive. | null  |
+| Layer Name  | [[String Type]]  | Layer of the input data source containing the features to rasterize. Mutually exclusive with Select Statement. This is an advanced port.  | .none  |
-| Select Statement  | [[String Type]]  | SQL statement to be evaluated against the datasource to produce a virtual layer containing the input features that will be rasterized. This definition and "Layer Name" are mutually exclusive. | null  |
+| Select Statement  | [[String Type]]  | SQL statement evaluated against the data source to produce a virtual layer of the features to rasterize. Mutually exclusive with Layer Name. This is an advanced port.  | .none  |
-| Where Statement  | [[String Type]]  | SQL WHERE expression used to select features from the input layer that will be rasterized. | null  |
+| Where Statement  | [[String Type]]  | SQL WHERE expression selecting which features of the input layer are rasterized. This is an advanced port.  | .none  |
+| Additional GDAL Rasterize Arguments  | [[String Type]]  | Additional arguments passed to the underlying ''gdal_rasterize'' invocation, appended after every other argument. This is an advanced port.  | ""  |
 ===== Outputs =====
 ^ Name  ^ Type  ^ Description  ^
-| Output Map Filename  | [[Map Filename Type]]  | The filename of the resulting map. This is the same filename assigned to the corresponding input port.  |
+| Output Map Filename  | [[Map Filename Type]]  | Same filename given to the Output Map Filename input port.  |
 ===== Group =====
-[[Functor List#GDAL / OGR|GDAL / OGR]]
+[[Functor List#GDAL / OGR | GDAL / OGR]]
 ===== Notes =====
-This functor is basically a wrap around the [[http://gdal.org/|GDAL library]] utility [[http://www.gdal.org/gdal_rasterize.html|GDAL Rasterize]].
+This functor is essentially a wrapper around the [[https://gdal.org/|GDAL library]] utility [[https://gdal.org/programs/gdal_rasterize.html|GDAL Rasterize]].
-The resulting map will have the projection and the boundaries of the input shape. The projection and boundaries can be changed using the [[Transform Map]] functor.
+The resulting map takes its projection and boundaries from the input shape; use [[Transform Map]] to change them afterward.
-<note important>It is worth noting that, unlike most functors, this functor can not be bound to maps produced by other functors, unless they are saved to the disk first (by using [[Save Map]]). Unfortunately, the use of [[http://www.gdal.org|GDAL]] does not allow us to the use the maps produced by Dinamica EGO while they are still in memory, unless they are re-arranged in a way defined by their API, and such re-arrangement would heavily impact the execution performance and the amount of memory required to perform the re-projection of a map.</note>
+Only the GeoTiff (.tif) and HFA (.img) formats support Use Compression; it is ignored for other formats.
+Unlike most functors, this functor cannot be connected directly to a map produced by another functor while it is still in memory — that map must first be saved to disk with [[Save Map]] — because the underlying GDAL utility can only operate on maps already written to a file. Re-arranging an in-memory map into the form GDAL's API expects would heavily impact execution performance and the amount of memory required, which is why this restriction is not worked around internally.
 ===== Internal Name =====
-RasterizeMap
+RasterizeShape