ILLUMCAST

Description

Computes the illumination map (raster) and cast shadow mask (bitmap) based on the input of corresponding elevation, slope, and aspect rasters and the correct setting of the solar geometry.

Parameters

illumcast(fili, dbic, filref, filo, sazangl, elevunit, elfactor, backelev)

Name	Type	Caption	Length	Value range
FILI *	str	Input derivatives file	1 -
DBIC	List[int]	Input elevation, slope and aspect channels	0 - 3
FILREF	str	Reference image georeferencing	0 -
FILO *	str	Output file name	1 -
SAZANGL	List[float]	Solar zenith and azimuth angles (deg)	0 - 2	0.0 - 360
ELEVUNIT	str	Unit of the elevation values	0 - 7	METER | FEET | US_FEET
ELFACTOR	List[float]	Elevation offset and scale	0 - 2
BACKELEV	List[float]	Background elevation value	0 - 1

* Required parameter

Parameter descriptions

FILI

Specifies the name of the input file that contains the elevation, slope, and aspect data used to compute the illumination map and cast shadow bitmap.

DBIC

Specifies the input channels that contain the elevation, slope, and aspect data, respectively.

If this parameter is not specified, the function checks for a TERRAIN_LAYER_NAME metadata tag at the channel level to properly associate each channel. If the metadata tag is missing for any of the channels, ILLUMCAST will error.

FILREF

Specifies the name of the input reference file that contains metadata information about the solar position (solar zenith and azimuth) at the time of image acquisition.

If this parameter is not specified, the solar zenith angle and solar azimuth angle (SAZANGL) must be specified; the output file will have the same geocoding as the input file.

The input reference file is usually satellite imagery that has properly ingested the metadata related to the solar zenith (or solar elevation) and azimuth angles. When specified, this parameter also defines the geocoding of the output file.

FILO

Specifies the name of the output file to receive the computed illumination map and cast shadow bitmap.

The specified file must not already exist; the function automatically creates a new file.

SAZANGL

Specifies, respecitvely, the solar zenith angle (0-90 degrees) and the solar azimuth angle (0-360 degrees) at the time of image acquisition.

SAZANGL = [<zenith>, <azimuth>]

If this parameter is not specified and none of the above three combinations of metadata tags is found in full, ILLUMCAST will fail.

ELEVUNIT

Specifies the units used to describe the elevation values of the input file (FILI).

This parameter is used to ensure that the vertical (elevation) unit matches the horizontal (projection) unit, which is required for the correct computation of the cast shadow. If a discrepancy exists, an on-the-fly conversion is applied so that the vertical and horizontal units match.

If this parameter is not specified, the program checks for an ELEVATION_UNITS metadata tag at the file level, and again at the channel level.

If this value is not specified or is not found in the metadata, ELEVUNIT defaults to METER.

ELFACTOR

Specifies the values used to shift and scale the DEM pixel values to values in the units indicated by the Elevation Units (ELEVUNIT) parameter.

Two values are specified using this parameter: the first number defines the offset, while the second optionally specifies the scale.

The conversion formula is:

elevation_value = scale * (DEM_pixel_value + offset)

If a single value is specified, that value is used to specify the offset; the scale value defaults to 1.0.

If this parameter is not specified, ILLUMCAST checks for an ELEVATION_SCALE and ELEVATION_OFFSET metadata tags at the file level, and again at the channel level.

If this value is not specified or found in the metadata, the offset defaults to 0.0 and the scale defaults to 1.0, indicating that there is no offset and that the scale is 1:1.

BACKELEV

Specifies a special value, in the input elevation channel, used to indicate which pixel value is to be handled as no data (no elevation).

If this parameter is not specified, the program checks for a NO_DATA_VALUE metadata tag at the channel level and again at the channel level.

If this value is not specified or found in the metadata, all pixels of the DEM are assumed to be valid.

Details

ILLUMCAST uses elevation, slope, and aspect rasters, as well as the solar zenith and azimuth angles to derive the illumination map and the terrain cast shadow mask.

The solar illumination map is defined as the cosine of the local illumination angle, which is defined as the cosine of the angle between the local normal of the pixel and the incoming solar beam.

The local normal of a pixel is described by the slope and aspect rasters, whereas the incoming solar beam is described by the solar zenith and azimuth angles at the time of image acquisition.

The cast shadow is a mask that covers pixels that do not receive any direct sun-to-ground transmittance. The means that a pixel in the cast shadow bitmap will be assigned a value of 1 (masked) if it is completely shaded from direct sunlight. A pixel may not receive direct sunlight because the sun is being blocked by an adjacent terrain feature or because the pixel is completely oriented away from the sun (that is, the slope faces away from the sun).

  Sun -  O    |		
          \   |
Solar Path \  |Normal 
            \^|
         ___ \|___
	 FLAT PIXEL (no slope)
^ Illumination angle

The illumination map is commonly used by ATCOR (Atmospheric and Terrain Correction) when computing the amount of direct solar sunlight received by a pixel at the time of image acquisition. The cast shadow bitmap is used by ATCOR to identify pixels that do not receive any direct sunlight, so that during atmospheric correction, only incoming diffuse sunlight is taken into consideration.

The input file (FILI) must contain all the required terrain rasters, including elevation, slope, and aspect. If any one of the terrain rasters is missing, ILLUMCAST will error.

The solar zenith angle and solar azimuth angle (ZAZANGL) specify the solar zenith and azimuth values when a reference file (FILEREF) is not specified is missing required metadata tags. The solar zenith angle represents the vertical angle of the sun relative to the normal of the scene. The solar azimuth angle represents the 360 degree horizontal orientation of the sun as it pivots around the center of the scene, where North is 0 degrees, East is 90 degrees, South is 180 degrees, and West is 270 degrees. The solar zenith angle is used with the solar azimuth angle to determine the path of incident radiation (incoming solar beam).

Accurate computation of the cast shadow map depends on the proper specification of the elevation unit (ELEVUNIT), as well as the elevation scale and offset (ELFACTOR). Specifying the elevation unit (ELEVUNIT) allows ILLUMCAST to perform a preprocessing check to ensure that the projection unit and elevation unit match and, if necessary, apply an appropriate conversion. If the input DEM has been scaled, the elevation scale and offset (ELFACTOR) parameters should be specified to define how to properly un-scale the elevation values prior to computing the cast shadow mask.

The background elevation value (BACKELEV) specifies which pixel value from the input elevation channel should be interpreted as background (No Data). If this parameter is not specified, the program searches for a NO_DATA_VALUE metadata tag for the elevation channel. If this value is not provided, all values in the elevation channel are assumed to be valid. The input No Data value is used as the output No Data value.

Similarly, ILLUMCAST searches for a NO_DATA_VALUE metadata tag for the slope channel and, separately, the aspect channel. If the tag is not found, the program assumes that all values that fall within the applicable range of slope (0-90) and aspect (0-360), respectively, are valid. Any value that falls outside of the accepted range will be set to No Data and not processed by ILLUMCAST.

A metadata record is created for the output illumination channel to identify No Data value.

Example

This example calculates the illumination map of 16-bit signed elevation data from channel 10 and slope channel 7 and aspect channel 8 the file irvine.pix and places the output in channel 9. Prior to running ILLUMCAST, run the function SLASP to create slope and aspect channels. Each pixel in the image represents a projected ground area of 30 m x 30 m, and each increment in the gray level of the elevation image corresponds to the default elevation change of 1 m.

from pci.slasp import slasp
from pci.illumcast import illumcast

filedem	=	'irvine.pix'	# input file
dbec	=	[10]	# input elevation, slope, aspect data
filo	=	'irvine.pix'	# output file
dboc	=	[13,14]	# output slope, aspect channels
elevunit	=	'METER'	# default elevation units
elfactor	=	[0.0,1.0]	# default scale, offset
backelev	=	[]
zeroslop	=	[510.0]	# default zero slope aspect

slasp( filedem, dbec, filo, dboc, elevunit, elfactor, backelev, zeroslop )

fili	=	'irvine.pix'	# input file
dbic	=	[10,13,14]	# input elevation, slope, aspect data
filref	=	''	# no reference file
filo	=	'irvine.pix'	# output file
sazangl	=	[32.0, 128.0]	# solar zenith/azimuth angles
elevunit	=	'METER'	# default elevation units
elfactor	=	[0.0,1.0]	# default scale, offset
backelev	=	[]

illumcast( fili, dbic, filref, filo, sazangl, elevunit, elfactor, backelev )

References

J. Dozier, J. Bruno, 1981. A fast solution to the horizon problem. Computers & Geosciences, Vol. 7, pp. 145-151.