i.landsat.toar(1grass) GRASS GIS 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 tem-
perature, 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_eleva-
tion=float] [product_date=yyyy-mm-dd] [gain=string] [per-
cent=float] [pixel=integer] [rayleigh=float] [lsat-
met=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
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-atmos-
phere reflectance and temperature (band 6 of the sensors TM and ETM+).
Optionally, it can be used to calculate the at-surface radiance or re-
flectance 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 equa-
tions.
Uncorrected at-sensor values (method=uncorrected, default)
The standard geometric and radiometric corrections result in a cali-
brated 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 radio-
metric 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 so-
lar elevation angle, and Esun is the mean solar exoatmospheric irradi-
ance in W/(m² * µm).
Simplified at-surface values (method=dos[1-4])
Atmospheric correction and reflectance calibration remove the path ra-
diance, i.e. the stray light from the atmosphere, and the spectral ef-
fect 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 atmo-
spheric 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.0 when it
is negative) then they are possible negative values. However, output
reflectance is set to 0.0 when is obtained a negative value.
NOTES
The output raster cell values can be rescaled with the scale parameter
(e.g., with 100 in case of using reflectance output in i.gensigset).
On Landsat-8 metadata file
NASA reports a structure of the L1G Metadata file (LDCM-DFCB-004.pdf)
for Landsat Data Continuity Mission (i.e. Landsat-8).
NASA retains in MIN_MAX_RADIANCE group the necessary information to
transform Digital Numbers (DN) in radiance values. Then, i.landsat.toar
replaces the possible standard values with the metadata values. The re-
sults match with the values reported by the metada file in RADIOMET-
RIC_RESCALING group.
Also, NASA reports the same values of reflectance for all bands in
max-min values and in gain-bias values. This is strange that all bands
have the same range of reflectance. Also, they wrote in the web page as
to calculate reflectance directly from DN, first with RADIOMET-
RIC_RESCALING values and second divided by sin(sun_elevation).
This is a simple rescaling
• reflectance = radiance / sun_radiance = (DN * RADIANCE_MULT +
RADIANCE_ADD) / sun_radiance
• now reflectance = DN * REFLECTANCE_MULT + REFLECTANCE_ADD
• then REFLECTANCE_MULT = RADIANCE_MULT / sun_radiance
• and REFLECTANCE_ADD = RADIANCE_ADD / sun_radiance
The problem arises when we need ESUN values (not provided) to compute
sun_radiance and DOS. We assume that REFLECTANCE_MAXIMUM corresponds to
the RADIANCE_MAXIMUM, then
• REFLECTANCE_MAXIMUM / sin(e) = RADIANCE_MAXIMUM / sun_radiance
• Esun = (PI * d^2) * RADIANCE_MAXIMUM / REFLECTANCE_MAXIMUM
where d is the earth-sun distance provided by metadata file or computed
inside the program.
The i.landsat.toar reverts back the NASA rescaling to continue using
Lmax, Lmin, and Esun values to compute the constant to convert DN to
radiance and radiance to reflectance with the "traditional" equations
and simple atmospheric corrections. Attention: When MAXIMUM values are
not provided, i.landsat.toar tries to calculate Lmax, Lmin, and Esun
from RADIOMETRIC_RESCALING (in tests the results were the same).
Calibration constants
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 cor-
rect 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
Metadata file 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=203_30. output=_toar \
metfile=p203r030_7x20010620.met
or
i.landsat.toar input=L5121060_06020060714. \
output=L5121060_06020060714_toar \
metfile=L5121060_06020060714_MTL.txt
or
i.landsat.toar input=LC80160352013134LGN03_B output=toar \
metfile=LC80160352013134LGN03_MTL.txt sensor=oli8 date=2013-05-14
DOS1 example
DN to reflectance using DOS1:
# rename channels or make a copy to match i.landsat.toar’s input scheme:
g.copy raster=lsat7_2002_10,lsat7_2002.1
g.copy raster=lsat7_2002_20,lsat7_2002.2
g.copy raster=lsat7_2002_30,lsat7_2002.3
g.copy raster=lsat7_2002_40,lsat7_2002.4
g.copy raster=lsat7_2002_50,lsat7_2002.5
g.copy raster=lsat7_2002_61,lsat7_2002.61
g.copy raster=lsat7_2002_62,lsat7_2002.62
g.copy raster=lsat7_2002_70,lsat7_2002.7
g.copy raster=lsat7_2002_80,lsat7_2002.8
Calculation of reflectance values from DN using DOS1 (metadata obtained
from p016r035_7x20020524.met.gz):
i.landsat.toar input=lsat7_2002. output=lsat7_2002_toar. sensor=tm7 \
method=dos1 date=2002-05-24 sun_elevation=64.7730999 \
product_date=2004-02-12 gain=HHHLHLHHL
The resulting Landsat channels are named lsat7_2002_toar.1 ..
lsat7_2002_toar.8.
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 Geo-
science 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 Nor-
malization 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, i.colors.enhance, r.mapcalc, r.in.gdal
Landsat Data Dictionary by USGS
AUTHOR
E. Jorge Tizado (ej.tizado unileon es), Dept. Biodiversity and Envi-
ronmental Management, University of León, Spain
SOURCE CODE
Available at: i.landsat.toar source code (history)
Accessed: unknown
Main index | Imagery index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 i.landsat.toar(1grass)
Generated by dwww version 1.14 on Fri Jan 24 14:02:53 CET 2025.