ATRLUT

Description

ATRLUT transforms an at-sensor radiance data set into a surface reflectance data set, or transforms a surface reflectance data set into an at-sensor radiance data set. The computations use radiance values interpolated from an at-sensor radiance lookup table.

Parameters

atrlut(atran, rlutfili, dbsrl, clutfili, dbscl, fili, dbdem, dbaod, dbsmr, dbwvc, filo, rtlevel, nomvwvc, nomaod, nomsmr, nomelev, adjdim)

Name	Type	Caption	Length	Value range
ATRAN	str	Atmospheric transformation	0 - 6	RADREF | REFRAD Default: RADREF
RLUTFILI*	str	Input radiance LUT input file name	1 -
DBSRL*	List[int]	Input radiance LUT segment	1 - 1
CLUTFILI	str	Input CLUT file name	0 -
DBSCL	List[int]	Input CLUT segment	0 - 1
FILI*	str	Input file to be transformed	1 -
DBDEM	List[int]	Input scene elevation map	0 - 1
DBAOD	List[int]	Input aerosol optical depth map	0 - 1
DBSMR	List[int]	Input surface meteorological range map	0 - 1
DBWVC	List[int]	Input water-vapor content map	0 - 1
FILO*	str	Output transformed file name	1 -
RTLEVEL	List[int]	Radiometric transformation level	0 - 1
NOMVWVC	List[float]	Nominal atmospheric water vapor content	0 - 1
NOMAOD	List[float]	Nominal aerosol optical depth	0 - 1
NOMSMR	List[float]	Nominal surface meteorological range	0 - 1
NOMELEV	List[float]	Nominal scene elevation	0 - 1
ADJDIM	List[int]	Adjacency effect window dimension	0 - 1	Default: 1

* Required parameter

Parameter descriptions

ATRAN

Specifies the atmospheric transformation to apply.

RLUTFILI

Specifies the name of the PCIDSK file that contains the radiance lookup table (RLUT).

DBSRL

Specifies the segment that contains the input radiance lookup table (RLUT).

CLUTFILI

Specifies the name of the PCIDSK file that contains the input spectral line curvature lookup table (CLUT).

DBSCL

Specifies segment that contains the input spectral line curvature lookup table (CLUT).

If CLUTFILI is used, this parameter must be specified; otherwise, this parameter is ignored.

FILI

Specifies the name of the input file that contains the data to be transformed.

DBDEM

Specifies the input channel that contains a DEM map of the scene to be transformed.

If this parameter is not specified, a nominal elevation (NOMELEV) is used over the entire scene. Only one channel can be specified.

DBAOD

Specifies the input channel that contains an aerosol optical depth map of the scene to be transformed.

If this parameter is not specified, a nominal aerosol optical depth (NOMAOD) is used over the entire scene. Only one channel can be specified.

The aerosol optical depth map (DBAOD) can be used as an alternative to the surface meteorological range map (DBSMR) in evaluating a surface meteorological range map. Only one these two parameters can be specified.

DBSMR

Specifies the input channel that contains a surface meteorological range map of the scene to be transformed.

If this parameter is not specified, a nominal surface meteorological range (NOMSMR) is used over the entire scene. Only one channel can be specified.

The aerosol optical depth map (DBAOD) can be used as an alternative to the surface meteorological range map (DBSMR) in evaluating a surface meteorological range map. Only one these two parameters can be specified.

DBWVC

Specifies the input channel that contains an atmospheric water-vapor-content map of the scene to be transformed.

If this parameter is not specified, a nominal atmospheric water-vapor content (NOMVWVC) is used over the entire scene. Only one channel can be specified.

FILO

Specifies the name of the output file to receive the transformed image data. The specified file must not exist prior to running ATRLUT.

RTLEVEL

Specifies the radiometric transformations already associated with the data set that is applied to the stored pixel values before any atmospheric transformation computations are performed. By default, the full sequence of transformations is applied.

This parameter has no effect if the data set metadata contains no radiometric transformation parameter values.

NOMVWVC

Specifies the nominal atmospheric water-vapor-content value (in g/cm^2) used over the entire scene. If the atmospheric water-vapor content setting was not specified in GENTP5 and GENRLUT when the RLUT was created, this parameter should be left unspecified.

If an input water-vapor content map (DBWVC) is specified, the nominal value is ignored.

NOMAOD

Specifies the nominal aerosol-optical depth used over the entire scene. If either an input aerosol optical depth (DBAOD) or surface meteorological range (DBSMR) is specified, the nominal value is ignored.

If the meteorological range settings were not specified in GENTP5 and GENRLUT when the RLUT was created, this parameter should be left unspecified.

The nominal aerosol optical depth (NOMAOD) is used as an alternative to the surface meteorological range (NOMSMR) in evaluating a nominal surface meteorological range value. Only one of these two parameters can be specified.

NOMSMR

Specifies the nominal surface meteorological range value (in kilometers) used over the entire scene. If either an input aerosol optical depth (DBAOD) or surface meteorological range (DBSMR) is specified, the nominal value is ignored.

If the meteorological range settings were not specified in GENTP5 and GENRLUT when the RLUT was created, this parameter should be left unspecified.

The nominal aerosol optical depth (NOMAOD) is used as an alternative to the surface meteorological range (NOMSMR) in evaluating a nominal surface meteorological range value. Only one of these two parameters can be specified.

NOMELEV

Specifies the nominal elevation value (in meters, with respect to the WGS84 vertical datum) used for the entire scene. Either the nominal elevation (NOMELEV) or input scene elevation (DBDEM) must be specified. If an input scene (DBDEM) is specified, this parameter is ignored.

ADJDIM

Specifies the dimension of the neighborhood window used to compute adjacency radiance effects from heterogeneous terrain reflectance.

Details

ATRLUT performs automatic resampling of the input at-sensor radiance lookup table (RLUT) if the wavelength dimension sample does not match the data set band center wavelengths. Alternatively, you can use RESRLUT to resample the RLUT to match the response profile of the data set before running ATRLUT, which considerably reduces the ATRLUT execution time. The only exception is when an input spectral line curvature table is specified; in this case, the non-resampled RLUT should be used.

If a radiance-to-reflectance transformation is specified, the image data set at the specified radiometric transformation level and the RLUT must contain radiance values in the same units. Because the image data set band center wavelength values are always measured in nanometers, the radiance units must have a spectral component in nanometers.

If a reflectance-to-radiance transformation is specified, the image data set at the specified radiometric transformation level must contain reflectance values in fraction-of-one units (that is, in [0,1]). The computed radiance values are also in the same units as the RLUT radiance units. Because image data set band center wavelength values are always measured in nanometers, the radiance units must have a spectral component in nanometers.

ATRLUT reads elevation, aerosol-optical depth, surface meteorological range, and atmospheric water-vapor content from raster maps on a pixel-by-pixel basis. Atmospheric water-vapor content maps are generated using GENAWVC.

ATRLUT also allows the adjacency effect caused by non-homogeneous scenes to be taken into account by using the adjacency effect window dimension parameter.

If a CLUT is specified, the response profiles for each pixel are shifted according to the CLUT before performing the RLUT convolution and, subsequently, the atmospheric correction. When smile correction is desired, SLCCOR should follow ATRLUT, because each reflectance spectrum has its own response profile. See SLCCOR and GENCLUT for detailed information about smile correction and the suggested workflow.

If the selected atmospheric transformation is REFRAD, the generated data set is written to 32R channels with a single radiometric transformation with a gain of 1.0, an offset of 0.0, and a radiometric quantity of apparent radiance.

If the selected atmospheric transformation is RADREF, the generated data set is written to 16S channels with a single radiometric transformation with a gain of 0.0001, an offset of 0.0, and a radiometric quantity of surface reflectance.

Examples

This example is an extension of the one given in the example for GENTP5 and GENRLUT, which showed how to generate an RLUT for transforming the cuprad.pix radiance data set into a reflectance data set.

The following demonstrates the transformation of an RLUT using ATRLUT.

from pci.atrlut import *

atran	=	"RADREF"	# radiance to reflectance transformation
rlutfili	=	"rlut.pix"	# output file created by GENRLUT
dbsrl	=	[3]	# store resampled RLUT in segment 3 of rlut.pix
clutfili	=	''	# do not apply wavelength and bandwidth shifts
dbscl	=	[]
fili	=	"cuprad.pix"	# perform atmospheric transformation on "cuprad.pix"
dbdem	=	[]	# use default nominal elevation (NOMELEV)
dbaod	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
dbsmr	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
dbwvc	=	[]	# use default atmospheric water-vapor content (NOMVWVC)
filo	=	"cupref.pix"	# save retrieved reflectance image to "cupref.pix"
rtlevel	=	[]	# apply full radiometric transformation sequence
# stored in cuprad.pix before transforming
nomvwvc	=	[]	# no VWVC settings were specified for the GENTP5
# and GENRLUT runs
nomaod	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
nomsmr	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
nomelev	=	[1524]	# elevation sample used to generate the RLUT
adjdim	=	[1]	# ignore adjacency effects

atrlut( atran, rlutfili, dbsrl, clutfili, dbscl, fili, dbdem, dbaod,
        dbsmr, dbwvc, filo, rtlevel, nomvwvc, nomaod, nomsmr, nomelev,
        adjdim )

Each band of the data set in cuprad.pix has a radiometric transformation defined in its metadata (also stored in cuprad.pix) that converts the integer (16S) pixel values to radiance values in units of microwatts/cm^2/nm/sr. The radiance values in the RLUT are in the same units. The radiometric transformation for each band is applied before the data is involved in the radiance-to-reflectance transformation.

ATRLUT determines which bands can be atmospherically corrected based on the wavelength samples present in the RLUT. It then creates the output file as specified by FILO with 16S bands receiving the atmospherically transformed data.

The output file contains a single radiometric transformation with a gain of 0.0001, an offset of 0.0, and a radiometric quantity set to surface reflectance.

You can also use a water-vapor map for the entire scene. GENAWVC can extract the water-vapor map as described in the Example section of GENAWVC. The setup of ATRLUT is:

from pci.atrlut import atrlut

atran	=	"RADREF"	# radiance to reflectance transformation
rlutfili	=	"rlut.pix"	# output file created by GENRLUT
dbsrl	=	[3]	# store resampled RLUT in segment 3 of rlut.pix
clutfili	=	''	# do not apply wavelength and bandwidth shifts
dbscl	=	[]	# ignored because CLUTFILI was not specified
fili	=	"cuprad.pix"	# perform atmospheric transformation on "cuprad.pix"
dbdem	=	[]	# use default nominal elevation (NOMELEV)
dbaod	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
dbsmr	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
dbwvc	=	[226]	# use atmospheric water-vapor-content map
# as extracted by GENAWVC
filo	=	"cupref.pix"	# save retrieved reflectance image to "cupref.pix"
rtlevel	=	[]	# apply full radiometric transformation sequence
# stored in cuprad.pix before transforming
nomvwvc	=	[]	# ignored because a water-vapor map is specified
nomaod	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
nomsmr	=	[]	# surface meteorological range was not specified for
# the GENTP5 and GENRLUT runs
nomelev	=	[1524]	# elevation sample used to generate the RLUT
adjdim	=	[1]	# ignore adjacency effects

atrlut( atran, rlutfili, dbsrl, clutfili, dbscl, fili, dbdem, dbaod,
        dbsmr, dbwvc, filo, rtlevel, nomvwvc, nomaod, nomsmr, nomelev,
        adjdim )

The RLUT used in this modified example is created using 16 samples along the atmospheric water-vapor-content dimension.

The reflectance results may contain artifacts due to distortion in the original radiance data. An example of such distortion is spectral-line curvature, also known as spectral "smile." These artifacts can be subdued by smoothing with SMSPEC. You can also use GENCLUT for smile detection with ATRLUT and SLCCOR. For more information, see GENCLUT and SLCCOR.

The following example applies a Gaussian filter with a 30 nm standard deviation to the reflectance spectra in the atmospherically transformed data set.

from pci.smspec import smspec

file        =  "somefile.pix"
specfili	=	"cuprad.pix"	# file containing  new reflectance data set
specfilo	=	''
filotype	=	''
valonly	=	''
spfilt	=	"GAU"	# Gaussian filter
fwidth	=	[30]	# filter width (standard deviation of Gaussian filter)
wlen1	=	[]
wlen2	=	[]

smspec( file, specfili, specfilo, filotype, valonly, \
        spfilt, fwidth, wlen1, wlen2 )

Acknowledgements

PCI Geomatics received financial support from the Canadian Space Agency/L'Agence Spatiale Canadienne through the Earth Observation Application Development Program (EOADP) for the development of this software, under contract 9F028-0-4902/12.

References

Staenz, K. and D.J. Williams. "Retrieval of Surface Reflectance from Hyperspectral data: Using a Look-up Table Approach", Canadian Journal of Remote Sensing, 23 (1997): 354-368.