Debian Codegraph @

imagery/i.landsat.toar/i.landsat.toar.html

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