Debian Codegraph @

imagery/i.landsat.toar/i.landsat.toar.md

raw
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