i.landsat.toar (1)
NAME
i.landsat.toar - Calculates top-of-atmosphere radiance or reflectance and temperature for Landsat MSS/TM/ETM+/OLI
KEYWORDS
imagery, radiometric conversion, radiance, reflectance, brightness temperature, atmospheric correction, satellite, Landsat
SYNOPSIS
i.landsat.toar
i.landsat.toar --help
i.landsat.toar [-rnp] input=basename output=basename [metfile=name] [sensor=string] [method=string] [date=yyyy-mm-dd] [sun_elevation=float] [product_date=yyyy-mm-dd] [gain=string] [percent=float] [pixel=integer] [rayleigh=float] [lsatmet=string[,string,...]] [scale=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
Flags:
-r
Output at-sensor radiance instead of reflectance for all bands
-n
Input raster maps use as extension the number of the band instead the code
-p
Print output metadata info
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
input=basename [required]
Base name of input raster bands
Example: 'B.' for B.1, B.2, ...
output=basename [required]
Prefix for output raster maps
Example: 'B.toar.' generates B.toar.1, B.toar.2, ...
metfile=name
Name of Landsat metadata file (.met or MTL.txt)
sensor=string
Spacecraft sensor
Required only if 'metfile' not given (recommended for sanity)
Options: mss1, mss2, mss3, mss4, mss5, tm4, tm5, tm7, oli8
mss1: Landsat-1 MSS
mss2: Landsat-2 MSS
mss3: Landsat-3 MSS
mss4: Landsat-4 MSS
mss5: Landsat-5 MSS
tm4: Landsat-4 TM
tm5: Landsat-5 TM
tm7: Landsat-7 ETM+
oli8: Landsat_8 OLI/TIRS
method=string
Atmospheric correction method
Atmospheric correction method
Options: uncorrected, dos1, dos2, dos2b, dos3, dos4
Default: uncorrected
date=yyyy-mm-dd
Image acquisition date (yyyy-mm-dd)
Required only if 'metfile' not given
sun_elevation=float
Sun elevation in degrees
Required only if 'metfile' not given
product_date=yyyy-mm-dd
Image creation date (yyyy-mm-dd)
Required only if 'metfile' not given
gain=string
Gain (H/L) of all Landsat ETM+ bands (1-5,61,62,7,8)
Required only if 'metfile' not given
percent=float
Percent of solar radiance in path radiance
Required only if 'method' is any DOS
Default: 0.01
pixel=integer
Minimum pixels to consider digital number as dark object
Required only if 'method' is any DOS
Default: 1000
rayleigh=float
Rayleigh atmosphere (diffuse sky irradiance)
Required only if 'method' is DOS3
Default: 0.0
lsatmet=string[,string,...]
return value stored for a given metadata
Required only if 'metfile' and -p given
Options: number, creation, date, sun_elev, sensor, bands, sunaz, time
number: Landsat Number
creation: Creation timestamp
date: Date
sun_elev: Sun Elevation
sensor: Sensor
bands: Bands count
sunaz: Sun Azimuth Angle
time: Time
scale=float
Scale factor for output
Default: 1.0
DESCRIPTION
i.landsat.toar is used to transform the calibrated digital number of Landsat imagery products to top-of-atmosphere radiance or top-of-atmosphere reflectance and temperature (band 6 of the sensors TM and ETM+). Optionally, it can be used to calculate the at-surface radiance or reflectance with atmospheric correction (DOS method).
Usually, to do so the production date, the acquisition date, and the solar elevation are needed. Moreover, for Landsat-7 ETM+ it is also needed the gain (high or low) of the nine respective bands.
Optionally (recommended), the data can be read from metadata file (.met or MTL.txt) for all Landsat MSS, TM, ETM+ and OLI/TIRS. However, if the solar elevation is given the value of the metadata file is overwritten. This is necessary when the data in the .met file is incorrect or not accurate. Also, if acquisition or production dates are not found in the metadata file then the command line values are used.
Attention: Any null value or smaller than QCALmin in the input raster is set to null in the output raster and it is not included in the equations.
Uncorrected at-sensor values (method=uncorrected, default)
The standard geometric and radiometric corrections result in a calibrated digital number (QCAL = DN) images. To further standardize the impact of illumination geometry, the QCAL images are first converted first to at-sensor radiance and then to at-sensor reflectance. The thermal band is first converted from QCAL to at-sensor radiance, and then to effective at-sensor temperature in Kelvin degrees.
Radiometric calibration converts QCAL to at-sensor radiance, a radiometric quantity measured in W/(m * sr * m) using the equations:
o gain = (Lmax - Lmin) / (QCALmax - QCALmin)
o bias = Lmin - gain * QCALmin
o radiance = gain * QCAL + bias
where, Lmax and Lmin are the calibration constants, and QCALmax and QCALmin are the highest and the lowest points of the range of rescaled radiance in QCAL.
Then, to calculate at-sensor reflectance the equations are:
o sun_radiance = [Esun * sin(e)] / (PI * d^2)
o reflectance = radiance / sun_radiance
where, d is the earth-sun distance in astronomical units, e is the solar elevation angle, and Esun is the mean solar exoatmospheric irradiance in W/(m * m).
Simplified at-surface values (method=dos[1-4])
Atmospheric correction and reflectance calibration remove the path radiance, i.e. the stray light from the atmosphere, and the spectral effect of solar illumination. To output these simple at-surface radiance and at-surface reflectance, the equations are (not for thermal bands):
o sun_radiance = TAUv * [Esun * sin(e) * TAUz + Esky] / (PI * d^2)
o radiance_path = radiance_dark - percent * sun_radiance
o radiance = (at-sensor_radiance - radiance_path)
o reflectance = radiance / sun_radiance
where, percent is a value between 0.0 and 1.0 (usually 0.01), Esky is the diffuse sky irradiance, TAUz is the atmospheric transmittance along the path from the sun to the ground surface, and TAUv is the atmospheric transmittance along the path from the ground surface to the sensor. radiance_dark is the at-sensor radiance calculated from the darkest object, i.e. DN with a least 'dark_parameter' (usually 1000) pixels for the entire image. The values are,
o DOS1: TAUv = 1.0, TAUz = 1.0 and Esky = 0.0
o DOS2: TAUv = 1.0, Esky = 0.0, and TAUz = sin(e) for all bands with maximum wave length less than 1. (i.e. bands 4-6 MSS, 1-4 TM, and 1-4 ETM+) other bands TAUz = 1.0
o DOS3: TAUv = exp[-t/cos(sat_zenith)], TAUz = exp[-t/sin(e)], Esky = rayleigh
o DOS4: TAUv = exp[-t/cos(sat_zenith)], TAUz = exp[-t/sin(e)], Esky = PI * radiance_dark
Attention: Output radiance rema.lf 1 -
i.landsat.toar(1grass) Grass User's Manual i.landsat.toar(1grass)
NAME
i.landsat.toar - Calculates top-of-atmosphere radiance or reflectance and temperature for Landsat MSS/TM/ETM+/OLI
KEYWORDS
imagery, radiometric conversion, radiance, reflectance, brightness temperature, atmospheric correction, satellite, Landsat
SYNOPSIS
i.landsat.toar
i.landsat.toar --help
i.landsat.toar [-rnp] input=basename output=basename [metfile=name] [sensor=string] [method=string] [date=yyyy-mm-dd] [sun_elevation=float] [product_date=yyyy-mm-dd] [gain=string] [percent=float] [pixel=integer] [rayleigh=float] [lsatmet=string[,string,...]] [scale=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
Flags:
-r
Output at-sensor radiance instead of reflectance for all bands
-n
Input raster maps use as extension the number of the band instead the code
-p
Print output metadata info
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
input=basename [required]
Base name of input raster bands
Example: 'B.' for B.1, B.2, ...
output=basename [required]
Prefix for output raster maps
Example: 'B.toar.' generates B.toar.1, B.toar.2, ...
metfile=name
Name of Landsat metadata file (.met or MTL.txt)
sensor=string
Spacecraft sensor
Required only if 'metfile' not given (recommended for sanity)
Options: mss1, mss2, mss3, mss4, mss5, tm4, tm5, tm7, oli8
mss1: Landsat-1 MSS
mss2: Landsat-2 MSS
mss3: Landsat-3 MSS
mss4: Landsat-4 MSS
mss5: Landsat-5 MSS
tm4: Landsat-4 TM
tm5: Landsat-5 TM
tm7: Landsat-7 ETM+
oli8: Landsat_8 OLI/TIRS
method=string
Atmospheric correction method
Atmospheric correction method
Options: uncorrected, dos1, dos2, dos2b, dos3, dos4
Default: uncorrected
date=yyyy-mm-dd
Image acquisition date (yyyy-mm-dd)
Required only if 'metfile' not given
sun_elevation=float
Sun elevation in degrees
Required only if 'metfile' not given
product_date=yyyy-mm-dd
Image creation date (yyyy-mm-dd)
Required only if 'metfile' not given
gain=string
Gain (H/L) of all Landsat ETM+ bands (1-5,61,62,7,8)
Required only if 'metfile' not given
percent=float
Percent of solar radiance in path radiance
Required only if 'method' is any DOS
Default: 0.01
pixel=integer
Minimum pixels to consider digital number as dark object
Required only if 'method' is any DOS
Default: 1000
rayleigh=float
Rayleigh atmosphere (diffuse sky irradiance)
Required only if 'method' is DOS3
Default: 0.0
lsatmet=string[,string,...]
return value stored for a given metadata
Required only if 'metfile' and -p given
Options: number, creation, date, sun_elev, sensor, bands, sunaz, time
number: Landsat Number
creation: Creation timestamp
date: Date
sun_elev: Sun Elevation
sensor: Sensor
bands: Bands count
sunaz: Sun Azimuth Angle
time: Time
scale=float
Scale factor for output
Default: 1.0
DESCRIPTION
i.landsat.toar is used to transform the calibrated digital number of Landsat imagery products to top-of-atmosphere radiance or top-of-atmosphere reflectance and temperature (band 6 of the sensors TM and ETM+). Optionally, it can be used to calculate the at-surface radiance or reflectance with atmospheric correction (DOS method).
Usually, to do so the production date, the acquisition date, and the solar elevation are needed. Moreover, for Landsat-7 ETM+ it is also needed the gain (high or low) of the nine respective bands.
Optionally (recommended), the data can be read from metadata file (.met or MTL.txt) for all Landsat MSS, TM, ETM+ and OLI/TIRS. However, if the solar elevation is given the value of the metadata file is overwritten. This is necessary when the data in the .met file is incorrect or not accurate. Also, if acquisition or production dates are not found in the metadata file then the command line values are used.
Attention: Any null value or smaller than QCALmin in the input raster is set to null in the output raster and it is not included in the equations.
Uncorrected at-sensor values (method=uncorrected, default)
The standard geometric and radiometric corrections result in a calibrated digital number (QCAL = DN) images. To further standardize the impact of illumination geometry, the QCAL images are first converted first to at-sensor radiance and then to at-sensor reflectance. The thermal band is first converted from QCAL to at-sensor radiance, and then to effective at-sensor temperature in Kelvin degrees.
Radiometric calibration converts QCAL to at-sensor radiance, a radiometric quantity measured in W/(m * sr * m) using the equations:
o gain = (Lmax - Lmin) / (QCALmax - QCALmin)
o bias = Lmin - gain * QCALmin
o radiance = gain * QCAL + bias
where, Lmax and Lmin are the calibration constants, and QCALmax and QCALmin are the highest and the lowest points of the range of rescaled radiance in QCAL.
Then, to calculate at-sensor reflectance the equations are:
o sun_radiance = [Esun * sin(e)] / (PI * d^2)