GENERATE_SHADOWS

Calculates sun shadows on a surface based on terrain, 3D vector obstructions, and sun angle. The calculations can happen over a range of times and heights above ground. The outputs can include a grid of the count or percent of times that a particular cell is shaded, a point cloud of shadow count/percent at different heights, and a series of shadow mask layers showing the shadow at each given time/height.

Parameters:

ELEV_FILENAME - the filename or description of a loaded terrain layer(s) to use as input. You can include multiple FILENAME parameters to specify multiple input terrain layers. Wildcards are also supported. If no FILENAME is provided, all loaded terrain layers inside the specified bounds will be used as input.

Shadow from Vector Data:

USE_VECTOR_HEIGHTS - indicates whether or not loaded vector data with elevation values should be considered when performing the shadow calculations. This allows you to use things like buildings, trees, etc. to create shadows. The default is to not use vector data. Use USE_VECTOR_HEIGHTS="YES" to specify that you want to use heights from vector data.

VECTOR_FILENAME - specifies the filename/description of the vector layer(s) to get obstructions from. If not provided, all loaded vector layers will be considered. You can provide multiple VECTOR_FILENAME parameters to explicitly specify multiple layers.

VECTOR_HEIGHTS_ABOVE_SEA_LEVEL - specifies whether the elevation values stored with vector features are relative to the ground or relative to mean sea level. If any area features are included and their heights are relative to the ground, the obstruction heights within those areas will be increased by the specified amount. Any features that have an explicit altitude mode set for the feature or layer will obey that over this settings. The default is "YES" (heights are relative to sea level). To specify that vector heights should be relative to the terrain layer surface, use VECTOR_HEIGHTS_ABOVE_SEA_LEVEL="NO"

EXTRUDE_EDGES – specifies that any 3D area features should be extruded to the ground to create a shadow-casting volume. If the extrusion flag for any area is explicitly set, that setting will take precedence over this flag. Use EXTRUDE_EDGES=”YES” to enable extrusion.

MIN_TRI_HEIGHT – specifies the minimum height above ground that a 3D area or mesh triangle must be to be considered for shading. Use this to ignore triangles that are really part of the ground surface and shouldn’t be used for shadow calculations. You can include a unit in the string, like MIN_TRI_HEIGHT=”1 ft”, otherwise the units are assumed to be meters.

Time Interval

TIME_START – specifies the first UTC date / time to calculate shadows at

TIME_STOP – specifies the last UTC date/time to calculate shadows at, if you intend to calculate over a range of times. If not provided, shadows are calculated only at the TIME_START value.

TIME_INTERVAL – if both TIME_START and TIME_STOP are provided, this specifies the number of seconds between times to calculate shadows at. If not specified, the default interval is 5 minutes (TIME_INTERVAL=”300”).

Height(s) to Calculate Shadows

SHADOW_HEIGHT – specifies the minimum (or only) height above the ground surface to calculate the shadows at. By default this is 0.05m (5cm) above the ground. You can include a unit in the string, like SHADOW_HEIGHT="1 ft”, otherwise the units are assumed to be meters.

SHADOW_HEIGHT_MAX – specifies the maximum height above the ground surface to calculate the shadows at if you want to calculate shadows at multiple heights. Use the SHADOW_HEIGHT_INTERVAL value to specify the interval between spacings to calculate at.

SHADOW_HEIGHT_INTERVAL – if both SHADOW_HEIGHT and SHADOW_HEIGHT_MAX are provided, this specifies the height interval between the minimum and maximum shadow heights to calculate shadows at. The default is 0.25m if not provided.

Output Specification

SHADOW_UNITS – specifies where the count or percent of shadow at a given sample location should be saved in a shadow grid or point cloud. The following values are recognized:

COUNT – specifies that the count of times that a location is in shadow should be stored

PERCENT – specifies that the percent of time that a location is in shadow should be stored (default)

SAVE_SHADOW_GRID – specifies that a grid be created with the percent or count of shadow at each height in the specified height range. A separate grid layer will be created at each height.

SAVE_SHADOW_CLOUD – specifies that a point cloud should be created with the percent or count of shadow at each height in the specified height range. The percent or count will be saved in the Generic field of each point

LAYER_DESC – specifies the layer description that should be used for each generated shadow grid or cloud layer

SAVE_SHADOW_MASK – specifies that a mask layer should be created at each time / height pairing in the calculation indicating which cells are in or out of shadow

SHADOW_MASK_LAYER_DESC – specifies the base layer description to use for each generated shadow mask layer

SHADOW_MASK_ANIMATE – specifies whether or not an animated layer series should be created from the created shadow mask layers. Use SHADOW_MASK_ANIMATE=”YES” to enable automatic creation of the animated series.

SPATIAL_RES - specifies spacing at which to calculate the shadow coverage grid. A smaller grid spacing results in higher fidelity, but the calculation process will take longer. Typically you'll want to use the default value which is the minimum spatial resolution of the specified terrain data. Should be formatted as x_resolution,y_resolution. The units are the units of the current global projection. For example, if UTM was the current global projection and you wanted to use a grid with a 30 meter spacing, the parameter/value pair would look like SPATIAL_RES=30.0,30.0.

SPATIAL_RES_METERS - specifies spatial resolution to use in meters. The value in meters will automatically be converted to the current view/export projection units. For example, to do an export at 2.0 meter spacing (or as close as you can get to that in the current units), use SPATIAL_RES_METERS=2.0, or to do an export at 1.0 meters in X by 1.5 meters in Y, use SPATIAL_RES_METERS="1.0,1.5".

Specify Bounding Box for Operation