i.landsat.toar(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 NAME 💖

okay bestie, welcome to i.landsat.toar — yes that's the whole name, and yes it comes from the GRASS User's Manual (i.landsat.toar(1grass) if you're being formal about it 💅)

so what does it do?? it Calculates top-of-atmosphere radiance or reflectance and temperature for Landsat MSS/TM/ETM+/OLI. that's the whole vibe. it takes your raw satellite numbers and turns them into physics. slay 🌈

🔑 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. chaos mode but make it radiometric 🔥
  • -n — the input raster maps use the number of the band as the extension, not the band code. no cap, just numbers
  • -p — print out the output metadata info 🖨️
  • --overwrite — let the output files just. overwrite the existing ones. brutal but okay 💀
  • --help — print usage summary, the classic
  • --verbose — verbose module output, aka it tells you everything 👀
  • --quiet — quiet module output, aka it tells you nothing 🙈
  • --ui — force launching the GUI dialog 💻

🌸 Parameters 🌸

  • input=basename [required] — base name of the 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 💫

so. i.landsat.toar is the girl for transforming the calibrated digital number of Landsat imagery products into top-of-atmosphere radiance or top-of-atmosphere reflectance and temperature — that's band 6 of the TM and ETM+ sensors, iykyk. optionally, she can also calculate the at-surface radiance or reflectance with atmospheric correction (the DOS method). versatile queen 👑

usually, to do any of that, you need the production date, the acquisition date, and the solar elevation. and for Landsat-7 ETM+ you also need the gain (high or low) of the nine respective bands. like, all nine. don't skip 😌

optionally (and honestly, recommended), you can just read all that data from a metadata file (.met or MTL.txt) for all Landsat MSS, TM, ETM+ and OLI/TIRS. BUT — and this is the plot twist — if the solar elevation is given, the value from the metadata file gets overwritten. which is necessary when the data in the .met file is incorrect or not accurate. also, if the acquisition or production dates aren't found in the metadata file, then the command line values are the ones that get used. teamwork fr fr 🫶

Attention: any null value or anything smaller than QCALmin in the input raster gets set to null in the output raster, and it is not included in the equations. bye girl 💀
Attention: this module does not respect the current region settings, so it can have the largest possible sample of pixels from where to get the darkest one of the scene and perform the DOS correction. to limit the results to a custom region, bestie is advised to clip the results (with r.clip, for instance) or to define the region first, import the images with region cropping, and then run the module. plan ahead or perish ✨

🌈 Uncorrected at-sensor values (method=uncorrected, default) 🌈

the standard geometric and radiometric corrections result in 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. two-step glow-up 🔥

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, bestie, don't try it):

  • 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 remains untouched (i.e. no set to 0.0 when it is negative) so negative values are possible ✨. however, output reflectance is set to 0.0 when a negative value is obtained. double standards honestly 😭

📝 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). tiny numbers? not on her watch 💅

🛰️ 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 file in RADIOMETRIC_RESCALING group. consistency? we love to see it 👑

also, NASA reports the same values of reflectance for all bands in max-min values and in gain-bias values. this is strange — all bands having the same range of reflectance?? suspicious 😭. 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) / 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. going backwards to go forwards, iconic behaviour tbh 🌈

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). she's resourceful like that 💅

📅 Calibration constants 📅

in verbose mode (flag --verbose), the program write basic satellite data and the parameters used in the transformations. spill the tea, verbose mode ☕

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 🌈

💫 Metadata file examples 💫

ok so listen, you want to transform the digital numbers of Landsat-7 ETM+ sitting in band rasters 203_30.1, 203_30.2 [...] into uncorrected at-sensor reflectance in output files 203_30.1_toar, 203_30.2_toar [...] — and also at-sensor temperature in output files 293_39.61_toar and 293_39.62_toar. bestie, here's the move:

i.landsat.toar input=203_30. output=_toar \
  metfile=p203r030_7x20010620.met

orrr…

i.landsat.toar input=L5121060_06020060714. \
  output=L5121060_06020060714_toar \
  metfile=L5121060_06020060714_MTL.txt

or, and hear me out…

i.landsat.toar input=LC80160352013134LGN03_B output=toar \
  metfile=LC80160352013134LGN03_MTL.txt sensor=oli8 date=2013-05-14

🍓 DOS1 example 🍓

DN → reflectance using DOS1, no cap:

# 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

✨ yes we're literally renaming the channels first, that's the whole vibe. then the 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

and the resulting Landsat channels are named lsat7_2002_toar.1 .. lsat7_2002_toar.8. iconic, honestly. 💅

📚 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.
🫶 the receipts!! always cite your sources, bestie, that's academic main character energy.

👀 SEE ALSO 👀

  • i.atcorr
  • i.colors.enhance
  • r.mapcalc
  • r.in.gdal

also go peek at the Landsat Data Dictionary by USGS — iykyk. 🦋

👑 AUTHOR 👑

E. Jorge Tizado (ej.tizado unileon es), Dept. Biodiversity and Environmental Management, University of León, Spain 🇪🇸

💖 SOURCE CODE 💖

Available at: i.landsat.toar source code (history)

Latest change: Tuesday Dec 23 23:30:51 2025 in commit: 2550be39b3524cf105ce856cb27ac8efaeef1bfb

Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

okay and that's the whole page, bestie, we did it 🎀 this was the GRASS 8.5.0 reference manual version of i.landsat.toar(1grass), last touched Tuesday Dec 23 23:30:51 2025, © 2003-2026 GRASS Development Team — slay, go correct some atmospheres, mwah 💅✨🌸

📦 where this page comes from