TOPOSOLNORM

Description

TOPOSOLNORM is a method to correct pre-classified radiometric values based on variable incidence angles.

Parameters

toposolnorm(fili, dbic, filedem, dbec, filecls, dbclsc, clsarr, sazangl, fileang, filo)

Name	Type	Caption	Length	Value range
FILI *	str	Input file name	1 -
DBIC	List[int]	Input channels	0 -
FILEDEM *	str	Elevation file name	1 -
DBEC	List[int]	Elevation channel or layer	0 - 1
FILECLS *	str	Classification file name	1 -
DBCLSC	List[int]	Input classification channel	0 - 1
CLSARR	List[int]	Array of input classes	0 -
SAZANGL	List[float]	Solar zenith and azimuth angles (deg)	0 - 2	0.0 - 360
FILEANG	str	Solar angles file name	0 -
FILO *	str	Output file name for topographically corrected image.	1 -

* Required parameter

Parameter descriptions

FILI

Specifies the name of the input file that contains the satellite image. The image should have sufficient metadata to derive the sensor name, product type and quantity (radiance, reflectance etc) of each band. If the image data are not corrected to reflectance, TOPOSOLNORM will convert the image values to reflectance on-the-fly.

DBIC

Optionally specifies the list of channels in FILI that are to be topographically normalized. The default is to process all channels in FILI. In order to compute a shadow mask, the input file needs to include the blue and NIR bands.

FILEDEM

Specifies the file that contains the elevation (DEM) layer. The elevation file is mandatory. FILEDEM will be resampled if its projection or resolution differs from the input file.

DBEC

Specifies the elevation layer. The default is to take the first layer containing elevation data

FILECLS

Specifies the file that contains the classification layer. The layer must have the same georeferencing information as the input file. The classification layer can be created by the SPECLASS or the SPECL PPFs; other classification layers can be provided. The classification file is mandatory.

DBCLSC

Specifies the classification layer. If not specified it will take first layer that is available.

CLSARR

Specifies an array of input classes contained in the classification layer. The correction is applied separately to each class. If left blank all classes are used in the topographic normalization.

SAZANGL

Optionally specifies the Solar Zenith and Azimuth Angle. If these values are not provided, the values in the file metadata will be used.

FILEANG

Optionally specifies a file containing synthesized per-pixel solar zenith and azimuth angle layers. For Sentinal-2, Landsat-8 and pushbroom sensors, the FILEANG can be produced by running the SOLVIEWZAZ ppf prior to running TOPOSOLNORM. For Landsat-8 each band can have its own Solar zenith and Solar azimuth layer. TOPOSOLNORM will use the metadata contained within the FILEANG file to determine which channel contains the appropriate zenith and azimuth angles. If FILEANG is not defined and the input file does not contain metadata describing the angles, then the user needs to define the zenith and azimuth angles using the SAZANGL parameter.

FILO

Specifies the name of the output file to receive the topographically corrected scene. It will also store computed relative incidence angle layer and the flat area and topographic shadow masks.

The specified file must not already exist.

Details

TOPOSOLNORM is a method to correct pre-classified radiometrically calibrated data based on variable incidence angles and bidirectional reflectance distribution function (BRDF) characteristic surfaces. This implementation of topographic normalization accounts for surfaces with different BRDF properties but is less sensitive to lower quality DEMs while accounting for various levels of skylight that is not eliminated during atmospheric correction.

TOPOSOLNORM requires a classification layer that isolates spectral classes with different BRDF characteristics that are homogeneous within a class except for variable solar incidence angles. In order for this process to be effective, a class needs to have sufficient pixels on both north and south facing slopes. A TOPOSOLNORM correction should only be applied to classes that are effected by topography. Do not apply a correction to classes such as cloud, water or shadow because this may lead to artifacts in the corrected imagery.

Example

The following example shows how to use the topographic normolization for input Sentinel-2 image with provided DEM, classification file and per-pixel angles file created with SOLVIEWZAZ.

from pci.toposolnorm import toposolnorm

fili    =   'S2A_MSIL1C_20170728T105621_N0205_R094_T33WWS_20170728T105621_10M.pix'  # input file
dbic    =   []
filedem =   'DEM_REP.pix'   # dem file
dbec    =   [1]
filecls =   'S2A_MSIL1C_20170728T105621_N0205_R094_T33WWS_20170728T105621_10M_classes.pix'  # dem file
dbclsc  =   [1]
clsarr  =   list(range(50,100))
sazangl =   []
fileang =   "solviewzaz_10m.pix"
filo    =   'toposolnorm.pix'   # output file

toposolnorm(fili, dbic, filedem, dbec, filecls, dbclsc, clsarr, sazangl, fileang, filo)