DN2RADIANCE

Description

DN2RADIANCE converts to radiance pixel values with radiometric calibration information. The supported input calibration types are radiance and reflectance. The input reflectance can be relative (still affected by the effects of the solar zenith angle) or absolute, with the solar elevation angle effects removed.

Parameters

dn2radiance(fili, dbic, fileang, filo, datatype, scaloffs, scalfact, ftype, foptions)

Name	Type	Caption	Length	Value range
FILI *	str	Input file name	1 -
DBIC	List[int]	List of channels to process.	0 - 16
FILEANG	str	Input angle file name	0 -
FILO *	str	Output file name	1 -
DATATYPE	str	Output raster type	0 - 3	8U| 16S| 16U| 32R Default: 16U
SCALOFFS	List[float]	Scaling offset	0 - 2
SCALFACT	List[float]	Scaling factor	0 - 2
FTYPE	str	Output file type	0 - 4	Default: PIX
FOPTIONS	str	Output file options	0 -

* Required parameter

Parameter descriptions

FILI

Specifies the name of the input image file. The file must contain pixel values with calibration information that allows them to be converted to radiance or reflectance.

DBIC

Specifies the list of input file channels to convert to radiance. If defaulted, all channels will be processed. The selected channels are converted if they have the required radiometric calibration information, provided by the RadiometricTrans metadata entries (Gain, Offset, Quantity and Units). Channels that are selected but do not have the required metadata tags are transferred to the output file as-is, but only if the output file type, specified by the FTYPE parameter, is PIX. For all other output file types only the radiometrically calibrated (spectral) channels are processed, and a warning is issued with the numbers of channels that are omitted from processing.

Note: an exception is made for the Landsat-8 Quality channel. It is transferred to the output file (with the data type conversion), except when the output channel data type (specified by the DATATYPE parameter) is 8U, or the output file format (specified by the FTYPE parameter) is JP2.

FILEANG

Specifies the name of the input raster file with the per-pixel solar view angles. The file is typically generated with the SOLVIEWZAZ module, using the file name in FILI as its input. FILEANG must have the same number of lines and pixels and georeferencing as FILI, and contain angles for all channels selected in DBIC. If the parameter is defaulted, the mean solar view angle is used for all pixels.

Note that the solar zenith angle is only required if FILI contains pixel values that represent absolute reflectance. For all other input data types (radiance and relative reflectance) this parameter should be defaulted, and is ignored if specified.

FILO

Specifies the name of the output file to receive the derived radiance values for all channels specified in the DBIC parameter. All radiance channels will be of the type specified by the DATATYPE parameter. The channels in DBIC that have no radiometric calibration information will be copied with their original data types, but only for PIX files.

The output file must not exist. It will be created with the type specified by the FTYPE parameter and with options specified by the FOPTIONS parameter. It will have the same geocoding information and file-level metadata as the input image file, except that the NO_DATA_VALUE tag will be removed.

DATATYPE

The data type of the output channel(s) to create.

When the number of output channels is greater than one, the specified data type is used for each output channel.

This parameter is optional.

The default value is 16U.

Note: the specified data type (except 8U) is used also for the Landsat-8 quality channel, if selected for processing. All other non-spectral channels selected for processing are transferred with their original data types, but only to the output files in PIX format.

SCALOFFS

Specifies scaling offset for converting the computed radiance values to Digital Numbers (DNs) to store in the output image.

A separate scaling offset for thermal bands may be provided as a comma-separated second value.

This parameter is optional.

If SCALOFFS is specified, the SCALFACT parameter must be specified as well, with the same number of values.

The SCALFACT and SCALOFFS parameters are used jointly to convert the computed radiance values to DNs as follows:

                            DN = Radiance * SCALFACT + SCALOFFS
                        

Note: the radiometric gain and bias values stored in channel metadata are mutually related to the SCALFACT and SCALOFFS values as follows:

                            Gain = 1 / SCALFACT
                            Bias = -SCALOFFS / SCALFACT

                            SCALFACT = 1 / Gain
                            SCALOFFS = -Bias / Gain
                        

SCALFACT

Specifies scaling factor for converting the computed radiance values to Digital Numbers (DNs) to store in the output image. The specified value(s) must be positive (greater than zero).

A separate scaling factor for thermal bands may be provided as a comma-separated second value.

If SCALFACT is specified, the SCALOFFS parameter must be specified as well, with the same number of values.

This parameter is optional. Please refer to the SCALOFFS parameter for more details, and for the list of data type-dependent default values.

FTYPE

The format of the output file. The format must be a GDB-recognized type.

The default value is PIX.

Note: only the PIX format supports the transfer of non-calibrated channels in their original data type. All other formats process only radiometrically calibrated channels, and write them out with the data type specified by the DATATYPE parameter.

FOPTIONS

The file-creation options to apply on creating the output file. These are specific to the format of the file; in each case, the default of no options is allowed. You can specify the compression schemes, file-format subtypes, and other information.

Different options are available for each type, as described for the FTYPE parameter.

For a complete list of GDB-recognized file types, including the available options for each, see GDB-supported file formats.

Details

The module DN2RADIANCE performs conversion from radiometrically calibrated input data to radiance. Input data in FILI can represent radiance (in which case they are copied as-is), or reflectance, relative or absolute. Relative reflectance values still contain the effects of the solar zenith angle, while absolute reflectance values have these effects already removed.

The input file channels to process are specified in the DBIC parameter. By default all input channels are processed. If a channel selected for processing has no radiometric calibration metadata, it is copied to the output file without any modifications, as long as the output channel data type (specified by the FTYPE parameter) is PIX. For all other file types only the radiometrically calibrated channels are processed, and a warning is issued with the numbers on non-calibrated channels omitted from processing.

Solar angles are not required if the input file contains radiances or relative reflectances. The conversion of absolute reflectances to radiances requires that the solar effects are restored, and therefore this input data type requires the knowledge of solar zenith angles. If the per-pixel angles are available, they can be used by specifying the name of the angle file in the FILEANG parameter. The angle channels to use are identified automatically for all input image channels in the DBIC parameter, based on the angle channel metadata tags Quantity (SolarZenithAngle) and BandDescription (AppliesToAllBands, or the standard image band description of individual bands). If an angle channel cannot be identified, the corresponding input image channel is copied to the output image as-is. The solar (and sensor) angle file is usually generated by the SOLVIEWZAZ module, with FILI used as its input. If the solar angle file is not provided, the nominal solar zenith angle at the scene center is used, if required.

The derived values are written to a new output file, with its name specified in the FILO parameter. The type of output channels is specified by the DATATYPE parameter, and all output radiometrically calibrated channels (and the Landsat-8 Quality channel, if selected for processing) will be of the same type. Some output channel types may require that the computed values are scaled and offset, and the parameters SCALFACT and SCALOFFS can be used to define the required linear transformation. There may be up two values provided for each of the two parameters, with the first value used for all non-thermal bands, and the second value used only for the thermal bands. The content of each processed channel is determined automatically from its metadata. The derived pixel values (DNs) are clipped to be within the value range in the output channel, as shown in the description of the DATATYPE parameter. Input image channels without the radiometric calibration metadata or the corresponding angle channel (if required) are transferred as-is. However, the non-calibrated channels are appended at the end of the file only for output files in the PIX format. For all other output file formats they are omitted from processing, and their numbers are shown in warning.

Example

The following example shows how to use the conversion for input Landsat-8 image. It contains relative reflectance data, so the angle file is not required. If the quality band is present in the input image, it will be transferred unmodified to the output file.

from pci.dn2radiance import dn2radiance

fili = 'landsat8.pix'
dbic = []
fileang = ''
filo = 'Rad_landsat8.pix'
datatype= '16S'
scaloffs = [0]
scalfact = [100]
ftype = ''
foptions =''

dn2radiance(fili, dbic, fileang, filo, datatype, scaloffs, scalfact, ftype, foptions)