Provided by: grass-doc_6.4.3-3_all 
NAME
i.landsat.toar - Calculates top-of-atmosphere radiance or reflectance and temperature for
Landsat MSS/TM/ETM+.
KEYWORDS
imagery, landsat, top-of-atmosphere reflectance, dos-type simple atmospheric correction
SYNOPSIS
i.landsat.toar
i.landsat.toar help
i.landsat.toar [-rn] input_prefix=string output_prefix=string [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] [--verbose] [--quiet]
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
--verbose
Verbose module output
--quiet
Quiet module output
Parameters:
input_prefix=string
Base name of input raster bands
Example: 'B.' for B.1, B.2, ...
output_prefix=string
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,ot8
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+
ot8: Landsat_8 OLI/TIRS
method=string
Atmospheric correction method
Atmospheric correction method
Options: uncorrected,corrected,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
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 are 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:
gain = (Lmax - Lmin) / (QCALmax - QCALmin)
bias = Lmin - gain * QCALmin
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:
sun_radiance = [Esun * sin(e)] / (PI * d^2)
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).
Corrected at-sensor values (method=corrected)
At-sensor reflectance values range from zero to one, whereas at-sensor radiance must be
greater or equal to zero. However, since Lmin can be a negative number then the at-sensor
values can also be negative. To avoid these possible negative values and set the minimum
possible values at-sensor to zero, this method corrects the radiance to output a corrected
at-sensor values using the equations (not for thermal bands):
radiance = (uncorrected_radiance - Lmin)
reflectance = radiance / sun_radiance
Note: Other possibility to avoid negative values is set to zero this values (radiance
and/or reflectance), but this option is ease with uncorrected method and r.mapcalc.
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):
sun_radiance = TAUv * [Esun * sin(e) * TAUz + Esky] / (PI * d^2)
radiance_path = radiance_dark - percent * sun_radiance
radiance = (at-sensor_radiance - radiance_path)
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,
DOS1: TAUv = 1.0, TAUz = 1.0 and Esky = 0.0
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
DOS3: TAUv = exp[-t/cos(sat_zenith)], TAUz = exp[-t/sin(e)], Esky = rayleigh
DOS4: TAUv = exp[-t/cos(sat_zenith)], TAUz = exp[-t/sin(e)], Esky = PI *
radiance_dark
Attention: Output radiance remain untouched (i.e. no set to 0. when it is negative) then
they are possible negative values. However, output reflectance is set to 0. when is
obtained a negative value.
NOTES
In verbose mode (flag --verbose), the program write basic satellite data and the
parameters used in the transformations.
Production date is not an exact value but it is necessary to apply correct calibration
constants, which were changed in the dates:
Landsat-1 MSS: never
Landsat-2 MSS: July 16, 1975
Landsat-3 MSS: June 1, 1978
Landsat-4 MSS: August 26, 1982 and April 1, 1983
Landsat-4 TM: August 1, 1983 and January 15, 1984
Landsat-5 MSS: April 6, 1984 and November 9, 1984
Landsat-5 TM: May 4, 2003 and April, 2 2007
Landsat-7 ETM+: July 1, 2000
Landsat-8 OLI/TIRS: launched in 2013
EXAMPLES
Transform digital numbers of Landsat-7 ETM+ in band rasters 203_30.1, 203_30.2 [...] to
uncorrected at-sensor reflectance in output files 203_30.1_toar, 203_30.2_toar [...] and
at-sensor temperature in output files 293_39.61_toar and 293_39.62_toar:
i.landsat.toar input_prefix=203_30. output_prefix=_toar \
metfile=p203r030_7x20010620.met
or
i.landsat.toar input_prefix=L5121060_06020060714. \
output_prefix=L5121060_06020060714_toar \
metfile=L5121060_06020060714_MTL.txt
or
i.landsat.toar input_prefix=203_30. output_prefix=_toar \
sensor=tm7 product_date=2004-06-07 date=2001-06-20 \
sun_elevation=64.3242970 gain="HHHLHLHHL"
REFERENCES
Chander G., B.L. Markham and D.L. Helder, 2009: Remote Sensing of
Environment, vol. 113
Chander G.H. and B. Markham, 2003.: IEEE Transactions On Geoscience And
Remote Sensing, vol. 41, no. 11.
Chavez P.S., jr. 1996. Image-based atmospheric corrections - Revisited and
Improved. Photogrammetric Engineering and Remote Sensing 62(9): 1025-1036.
Huang et al: At-Satellite Reflectance, 2002: A First Order Normalization Of
Landsat 7 ETM+ Images.
R. Irish: Landsat 7. Science Data Users Handbook. February 17, 2007; 15 May
2011.
Markham B.L. and J.L. Barker, 1986: Landsat MSS and TM Post-Calibration
Dynamic Ranges, Exoatmospheric Reflectances and At-Satellite Temperatures.
EOSAT Landsat Technical Notes, No. 1.
Moran M.S., R.D. Jackson, P.N. Slater and P.M. Teillet, 1992: Remote Sensing
of Environment, vol. 41.
Song et al, 2001: Classification and Change Detection Using Landsat TM Data,
When and How to Correct Atmospheric Effects? Remote Sensing of Environment,
vol. 75.
SEE ALSO
i.atcorr, r.mapcalc, r.in.gdal
AUTHOR
E. Jorge Tizado (ej.tizado unileon es), Dept. Biodiversity and Environmental Management,
University of León, Spain
Last changed: $Date: 2013-03-14 05:01:18 -0700 (Thu, 14 Mar 2013) $
Full index
© 2003-2013 GRASS Development Team