xenial (1) i.landsat.toar.1grass.gz

Provided by: grass-doc_7.0.3-1build1_all bug

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  temperature,  Landsat,  atmospheric
       correction

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

       -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
           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-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 = 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
       results match with the values reported by the metada file in RADIOMETRIC_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  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.   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

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

       Landsat Data Dictionary by USGS

AUTHOR

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

       Last changed: $Date: 2015-12-30 14:01:52 +0100 (Wed, 30 Dec 2015) $

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

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual