OnWorks favicon

i.landsat.toargrass - Online in the Cloud

Run i.landsat.toargrass in OnWorks free hosting provider over Ubuntu Online, Fedora Online, Windows online emulator or MAC OS online emulator

This is the command i.landsat.toargrass that can be run in the OnWorks free hosting provider using one of our multiple free online workstations such as Ubuntu Online, Fedora Online, Windows online emulator or MAC OS online emulator



i.landsat.toar - Calculates top-of-atmosphere radiance or reflectance and temperature for


imagery, radiometric conversion, radiance, reflectance, brightness temperature, Landsat,
atmospheric correction


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]

Output at-sensor radiance instead of reflectance for all bands

Input raster maps use as extension the number of the band instead the code

Print output metadata info

Allow output files to overwrite existing files

Print usage summary

Verbose module output

Quiet module output

Force launching GUI dialog

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, ...

Name of Landsat metadata file (.met or MTL.txt)

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

Atmospheric correction method
Atmospheric correction method
Options: uncorrected, dos1, dos2, dos2b, dos3, dos4
Default: uncorrected

Image acquisition date (yyyy-mm-dd)
Required only if ’metfile’ not given

Sun elevation in degrees
Required only if ’metfile’ not given

Image creation date (yyyy-mm-dd)
Required only if ’metfile’ not given

Gain (H/L) of all Landsat ETM+ bands (1-5,61,62,7,8)
Required only if ’metfile’ not given

Percent of solar radiance in path radiance
Required only if ’method’ is any DOS
Default: 0.01

Minimum pixels to consider digital number as dark object
Required only if ’method’ is any DOS
Default: 1000

Rayleigh atmosphere (diffuse sky irradiance)
Required only if ’method’ is DOS3
Default: 0.0

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 factor for output
Default: 1.0


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:

· 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).

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 =

· 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 *
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.


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 results match with the values reported by the metada

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
RADIOMETRIC_RESCALING values and second divided by sin(sun_elevation).

This is a simple rescaling

· reflectance = radiance / sun_radiance = (DN * RADIANCE_MULT + RADIANCE_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


where d is the earth-sun distance provided by metadata file or computed inside the

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 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


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 \
i.landsat.toar input=L5121060_06020060714. \
output=L5121060_06020060714_toar \
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
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 names lsat7_2002_toar.1 .. lsat7_2002_toar.8.


· 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.

Use i.landsat.toargrass online using onworks.net services

Free Servers & Workstations

Download Windows & Linux apps

Linux commands