Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
i.landsat.toar(1)	    GRASS GIS User's Manual	     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 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=basenameA [required]
	   Base	name of	input raster bands
	   Example: 'B.' for B.1, B.2, ...

       output=basenameA	[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/(mA^2 * sr * A<micro>m) using the equa-
       tions:

	   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  so-
       lar  elevation angle, and Esun is the mean solar	exoatmospheric irradi-
       ance in W/(mA^2 * A<micro>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):

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

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

	   o   reflectance = radiance /	sun_radiance = (DN *  RADIANCE_MULT  +
	       RADIANCE_ADD) / sun_radiance

	   o   now reflectance = DN * REFLECTANCE_MULT + REFLECTANCE_ADD

	   o   then REFLECTANCE_MULT = RADIANCE_MULT / sun_radiance

	   o   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

	   o   REFLECTANCE_MAXIMUM / sin(e) = RADIANCE_MAXIMUM / sun_radiance

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

	   o   Landsat-1 MSS: never

	   o   Landsat-2 MSS: July 16, 1975

	   o   Landsat-3 MSS: June 1, 1978

	   o   Landsat-4 MSS: August 26, 1982 and April	1, 1983

	   o   Landsat-4 TM:  August 1,	1983 and January 15, 1984

	   o   Landsat-5 MSS: April 6, 1984 and	November 9, 1984

	   o   Landsat-5 TM:  May 4, 2003 and April, 2 2007

	   o   Landsat-7 ETM+: July 1, 2000

	   o   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
	   o   Chander G., B.L.	Markham	and D.L. Helder, 2009: Remote  Sensing
	       of Environment, vol. 113

	   o   Chander	G.H.  and  B. Markham, 2003: IEEE Transactions On Geo-
	       science And Remote Sensing, vol.	41, no.	11.

	   o   Chavez P.S., jr.	1996: Image-based  atmospheric	corrections  -
	       Revisited  and Improved.	Photogrammetric	Engineering and	Remote
	       Sensing 62(9): 1025-1036.

	   o   Huang et	al: At-Satellite Reflectance, 2002: A First Order Nor-
	       malization Of Landsat 7 ETM+ Images.

	   o   R.  Irish: Landsat 7. Science Data Users	Handbook. February 17,
	       2007; 15	May 2011.

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

	   o   Moran  M.S.,  R.D. Jackson, P.N.	Slater and P.M.	Teillet, 1992:
	       Remote Sensing of Environment, vol. 41.

	   o   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 LeA^3n, Spain

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

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

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.4 Reference	Manual

GRASS 7.8.4						     i.landsat.toar(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | Uncorrected at-sensor values (method=uncorrected, default) | Simplified at-surface values (method=dos[1-4]) | NOTES | EXAMPLES | REFERENCES | SEE ALSO | AUTHOR | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=i.landsat.toar&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help