| 1 |
## DESCRIPTION |
| 2 |
|
| 3 |
*i.landsat.toar* is used to transform the calibrated digital number of |
| 4 |
Landsat imagery products to top-of-atmosphere radiance or |
| 5 |
top-of-atmosphere reflectance and temperature (band 6 of the sensors TM |
| 6 |
and ETM+). Optionally, it can be used to calculate the at-surface |
| 7 |
radiance or reflectance with atmospheric correction (DOS method). |
| 8 |
|
| 9 |
Usually, to do so the production date, the acquisition date, and the |
| 10 |
solar elevation are needed. Moreover, for Landsat-7 ETM+ it is also |
| 11 |
needed the gain (high or low) of the nine respective bands. |
| 12 |
|
| 13 |
Optionally (recommended), the data can be read from metadata file (.met |
| 14 |
or MTL.txt) for all Landsat MSS, TM, ETM+ and OLI/TIRS. However, if the |
| 15 |
solar elevation is given the value of the metadata file is overwritten. |
| 16 |
This is necessary when the data in the .met file is incorrect or not |
| 17 |
accurate. Also, if acquisition or production dates are not found in the |
| 18 |
metadata file then the command line values are used. |
| 19 |
|
| 20 |
**Attention**: Any null value or smaller than QCALmin in the input |
| 21 |
raster is set to null in the output raster and it is not included in the |
| 22 |
equations. |
| 23 |
|
| 24 |
**Attention**: This module does **not** respect the current region |
| 25 |
settings, in order to have the largest possible sample of pixels from |
| 26 |
where to get the darkest one of the scene and perform the DOS |
| 27 |
correction. To limit the results to a custom region, the user is advised |
| 28 |
to clip the results (with |
| 29 |
[r.clip](https://grass.osgeo.org/grass-stable/manuals/addons/r.clip.html), |
| 30 |
for instance) or to define the region first, import the images with |
| 31 |
region cropping, and then running the module. |
| 32 |
|
| 33 |
## Uncorrected at-sensor values (method=uncorrected, default) |
| 34 |
|
| 35 |
The standard geometric and radiometric corrections result in a |
| 36 |
calibrated digital number (QCAL = DN) images. To further standardize the |
| 37 |
impact of illumination geometry, the QCAL images are first converted |
| 38 |
first to at-sensor radiance and then to at-sensor reflectance. The |
| 39 |
thermal band is first converted from QCAL to at-sensor radiance, and |
| 40 |
then to effective at-sensor temperature in Kelvin degrees. |
| 41 |
|
| 42 |
Radiometric calibration converts QCAL to **at-sensor radiance**, a |
| 43 |
radiometric quantity measured in W/(m² \* sr \* µm) using the equations: |
| 44 |
|
| 45 |
- gain = (Lmax - Lmin) / (QCALmax - QCALmin) |
| 46 |
- bias = Lmin - gain \* QCALmin |
| 47 |
- radiance = gain \* QCAL + bias |
| 48 |
|
| 49 |
where, *Lmax* and *Lmin* are the calibration constants, and *QCALmax* |
| 50 |
and *QCALmin* are the highest and the lowest points of the range of |
| 51 |
rescaled radiance in QCAL. |
| 52 |
|
| 53 |
Then, to calculate **at-sensor reflectance** the equations are: |
| 54 |
|
| 55 |
- sun_radiance = \[Esun \* sin(e)\] / (PI \* d^2) |
| 56 |
- reflectance = radiance / sun_radiance |
| 57 |
|
| 58 |
where, *d* is the earth-sun distance in astronomical units, *e* is the |
| 59 |
solar elevation angle, and *Esun* is the mean solar exoatmospheric |
| 60 |
irradiance in W/(m² \* µm). |
| 61 |
|
| 62 |
## Simplified at-surface values (method=dos\[1-4\]) |
| 63 |
|
| 64 |
Atmospheric correction and reflectance calibration remove the path |
| 65 |
radiance, i.e. the stray light from the atmosphere, and the spectral |
| 66 |
effect of solar illumination. To output these simple **at-surface |
| 67 |
radiance** and **at-surface reflectance**, the equations are (not for |
| 68 |
thermal bands): |
| 69 |
|
| 70 |
- sun_radiance = TAUv \* \[Esun \* sin(e) \* TAUz + Esky\] / (PI \* d^2) |
| 71 |
- radiance_path = radiance_dark - percent \* sun_radiance |
| 72 |
- radiance = (at-sensor_radiance - radiance_path) |
| 73 |
- reflectance = radiance / sun_radiance |
| 74 |
|
| 75 |
where, *percent* is a value between 0.0 and 1.0 (usually 0.01), *Esky* |
| 76 |
is the diffuse sky irradiance, *TAUz* is the atmospheric transmittance |
| 77 |
along the path from the sun to the ground surface, and *TAUv* is the |
| 78 |
atmospheric transmittance along the path from the ground surface to the |
| 79 |
sensor. *radiance_dark* is the at-sensor radiance calculated from the |
| 80 |
darkest object, i.e. DN with a least 'dark_parameter' (usually 1000) |
| 81 |
pixels for the entire image. The values are, |
| 82 |
|
| 83 |
- DOS1: TAUv = 1.0, TAUz = 1.0 and Esky = 0.0 |
| 84 |
- DOS2: TAUv = 1.0, Esky = 0.0, and TAUz = sin(e) for all bands with |
| 85 |
maximum wave length less than 1. (i.e. bands 4-6 MSS, 1-4 TM, and 1-4 |
| 86 |
ETM+) other bands TAUz = 1.0 |
| 87 |
- DOS3: TAUv = exp\[-t/cos(sat_zenith)\], TAUz = exp\[-t/sin(e)\], Esky |
| 88 |
= rayleigh |
| 89 |
- DOS4: TAUv = exp\[-t/cos(sat_zenith)\], TAUz = exp\[-t/sin(e)\], Esky |
| 90 |
= PI \* radiance_dark |
| 91 |
|
| 92 |
**Attention**: Output radiance remain untouched (i.e. no set to 0.0 when |
| 93 |
it is negative) then they are possible negative values. However, output |
| 94 |
reflectance is set to 0.0 when is obtained a negative value. |
| 95 |
|
| 96 |
## NOTES |
| 97 |
|
| 98 |
The output raster cell values can be rescaled with the **scale** |
| 99 |
parameter (e.g., with 100 in case of using reflectance output in |
| 100 |
*i.gensigset*). |
| 101 |
|
| 102 |
### On Landsat-8 metadata file |
| 103 |
|
| 104 |
NASA reports a structure of the L1G Metadata file |
| 105 |
([LDCM-DFCB-004.pdf](http://landsat.usgs.gov/documents/LDCM-DFCB-004.pdf)) |
| 106 |
for Landsat Data Continuity Mission (i.e. Landsat-8). |
| 107 |
|
| 108 |
NASA retains in MIN_MAX_RADIANCE group the necessary information to |
| 109 |
transform Digital Numbers (DN) in radiance values. Then, |
| 110 |
*i.landsat.toar* replaces the possible standard values with the metadata |
| 111 |
values. The results match with the values reported by the metada file in |
| 112 |
RADIOMETRIC_RESCALING group. |
| 113 |
|
| 114 |
Also, NASA reports the same values of reflectance for all bands in |
| 115 |
max-min values and in gain-bias values. This is strange that all bands |
| 116 |
have the same range of reflectance. Also, they wrote in the web page as |
| 117 |
to calculate reflectance directly from DN, first with |
| 118 |
RADIOMETRIC_RESCALING values and second divided by sin(sun_elevation). |
| 119 |
|
| 120 |
This is a simple rescaling |
| 121 |
|
| 122 |
- reflectance = radiance / sun_radiance = (DN \* RADIANCE_MULT + |
| 123 |
RADIANCE_ADD) / sun_radiance |
| 124 |
- now reflectance = DN \* REFLECTANCE_MULT + REFLECTANCE_ADD |
| 125 |
- then REFLECTANCE_MULT = RADIANCE_MULT / sun_radiance |
| 126 |
- and REFLECTANCE_ADD = RADIANCE_ADD / sun_radiance |
| 127 |
|
| 128 |
The problem arises when we need ESUN values (not provided) to compute |
| 129 |
sun_radiance and DOS. We assume that REFLECTANCE_MAXIMUM corresponds to |
| 130 |
the RADIANCE_MAXIMUM, then |
| 131 |
|
| 132 |
- REFLECTANCE_MAXIMUM / sin(e) = RADIANCE_MAXIMUM / sun_radiance |
| 133 |
- Esun = (PI \* d^2) \* RADIANCE_MAXIMUM / REFLECTANCE_MAXIMUM |
| 134 |
|
| 135 |
where *d* is the earth-sun distance provided by metadata file or |
| 136 |
computed inside the program. |
| 137 |
|
| 138 |
The *i.landsat.toar* reverts back the NASA rescaling to continue using |
| 139 |
Lmax, Lmin, and Esun values to compute the constant to convert DN to |
| 140 |
radiance and radiance to reflectance with the "traditional" equations |
| 141 |
and simple atmospheric corrections. **Attention**: When MAXIMUM values |
| 142 |
are not provided, *i.landsat.toar* tries to calculate Lmax, Lmin, and |
| 143 |
Esun from RADIOMETRIC_RESCALING (in tests the results were the same). |
| 144 |
|
| 145 |
### Calibration constants |
| 146 |
|
| 147 |
In verbose mode (flag **--verbose**), the program write basic satellite |
| 148 |
data and the parameters used in the transformations. |
| 149 |
|
| 150 |
Production date is not an exact value but it is necessary to apply |
| 151 |
correct calibration constants, which were changed in the dates: |
| 152 |
|
| 153 |
- Landsat-1 MSS: never |
| 154 |
- Landsat-2 MSS: July 16, 1975 |
| 155 |
- Landsat-3 MSS: June 1, 1978 |
| 156 |
- Landsat-4 MSS: August 26, 1982 and April 1, 1983 |
| 157 |
- Landsat-4 TM: August 1, 1983 and January 15, 1984 |
| 158 |
- Landsat-5 MSS: April 6, 1984 and November 9, 1984 |
| 159 |
- Landsat-5 TM: May 4, 2003 and April, 2 2007 |
| 160 |
- Landsat-7 ETM+: July 1, 2000 |
| 161 |
- Landsat-8 OLI/TIRS: launched in 2013 |
| 162 |
|
| 163 |
## EXAMPLES |
| 164 |
|
| 165 |
### Metadata file examples |
| 166 |
|
| 167 |
Transform digital numbers of Landsat-7 ETM+ in band rasters 203_30.1, |
| 168 |
203_30.2 \[...\] to uncorrected at-sensor reflectance in output files |
| 169 |
203_30.1_toar, 203_30.2_toar \[...\] and at-sensor temperature in output |
| 170 |
files 293_39.61_toar and 293_39.62_toar: |
| 171 |
|
| 172 |
```sh |
| 173 |
i.landsat.toar input=203_30. output=_toar \ |
| 174 |
metfile=p203r030_7x20010620.met |
| 175 |
``` |
| 176 |
|
| 177 |
or |
| 178 |
|
| 179 |
```sh |
| 180 |
i.landsat.toar input=L5121060_06020060714. \ |
| 181 |
output=L5121060_06020060714_toar \ |
| 182 |
metfile=L5121060_06020060714_MTL.txt |
| 183 |
``` |
| 184 |
|
| 185 |
or |
| 186 |
|
| 187 |
```sh |
| 188 |
i.landsat.toar input=LC80160352013134LGN03_B output=toar \ |
| 189 |
metfile=LC80160352013134LGN03_MTL.txt sensor=oli8 date=2013-05-14 |
| 190 |
``` |
| 191 |
|
| 192 |
### DOS1 example |
| 193 |
|
| 194 |
DN to reflectance using DOS1: |
| 195 |
|
| 196 |
```sh |
| 197 |
# rename channels or make a copy to match i.landsat.toar's input scheme: |
| 198 |
g.copy raster=lsat7_2002_10,lsat7_2002.1 |
| 199 |
g.copy raster=lsat7_2002_20,lsat7_2002.2 |
| 200 |
g.copy raster=lsat7_2002_30,lsat7_2002.3 |
| 201 |
g.copy raster=lsat7_2002_40,lsat7_2002.4 |
| 202 |
g.copy raster=lsat7_2002_50,lsat7_2002.5 |
| 203 |
g.copy raster=lsat7_2002_61,lsat7_2002.61 |
| 204 |
g.copy raster=lsat7_2002_62,lsat7_2002.62 |
| 205 |
g.copy raster=lsat7_2002_70,lsat7_2002.7 |
| 206 |
g.copy raster=lsat7_2002_80,lsat7_2002.8 |
| 207 |
``` |
| 208 |
|
| 209 |
Calculation of reflectance values from DN using DOS1 (metadata obtained |
| 210 |
from |
| 211 |
[p016r035_7x20020524.met.gz](https://grassbook.org/wp-content/uploads/ncexternal/landsat/2002/p016r035_7x20020524.met.gz)): |
| 212 |
|
| 213 |
```sh |
| 214 |
i.landsat.toar input=lsat7_2002. output=lsat7_2002_toar. sensor=tm7 \ |
| 215 |
method=dos1 date=2002-05-24 sun_elevation=64.7730999 \ |
| 216 |
product_date=2004-02-12 gain=HHHLHLHHL |
| 217 |
``` |
| 218 |
|
| 219 |
The resulting Landsat channels are named |
| 220 |
`lsat7_2002_toar.1 .. lsat7_2002_toar.8`. |
| 221 |
|
| 222 |
## REFERENCES |
| 223 |
|
| 224 |
- Chander G., B.L. Markham and D.L. Helder, 2009: Remote Sensing of |
| 225 |
Environment, vol. 113 |
| 226 |
- Chander G.H. and B. Markham, 2003: IEEE Transactions On Geoscience And |
| 227 |
Remote Sensing, vol. 41, no. 11. |
| 228 |
- Chavez P.S., jr. 1996: Image-based atmospheric corrections - Revisited |
| 229 |
and Improved. Photogrammetric Engineering and Remote Sensing 62(9): |
| 230 |
1025-1036. |
| 231 |
- Huang et al: At-Satellite Reflectance, 2002: A First Order |
| 232 |
Normalization Of Landsat 7 ETM+ Images. |
| 233 |
- R. Irish: [Landsat 7. Science Data Users |
| 234 |
Handbook](http://landsathandbook.gsfc.nasa.gov/orbit_coverage/). |
| 235 |
February 17, 2007; 15 May 2011. |
| 236 |
- Markham B.L. and J.L. Barker, 1986: Landsat MSS and TM |
| 237 |
Post-Calibration Dynamic Ranges, Exoatmospheric Reflectances and |
| 238 |
At-Satellite Temperatures. EOSAT Landsat Technical Notes, No. 1. |
| 239 |
- Moran M.S., R.D. Jackson, P.N. Slater and P.M. Teillet, 1992: Remote |
| 240 |
Sensing of Environment, vol. 41. |
| 241 |
- Song et al, 2001: Classification and Change Detection Using Landsat TM |
| 242 |
Data, When and How to Correct Atmospheric Effects? Remote Sensing of |
| 243 |
Environment, vol. 75. |
| 244 |
|
| 245 |
## SEE ALSO |
| 246 |
|
| 247 |
*[i.atcorr](i.atcorr.md), [i.colors.enhance](i.colors.enhance.md), |
| 248 |
[r.mapcalc](r.mapcalc.md), [r.in.gdal](r.in.gdal.md)* |
| 249 |
|
| 250 |
[Landsat Data |
| 251 |
Dictionary](https://lta.cr.usgs.gov/DD/landsat_dictionary.html) by USGS |
| 252 |
|
| 253 |
## AUTHOR |
| 254 |
|
| 255 |
E. Jorge Tizado (ej.tizado unileon es), Dept. Biodiversity and |
| 256 |
Environmental Management, University of León, Spain |