1i.landsat.toar(1) GRASS GIS User's Manual i.landsat.toar(1)
2
3
4
6 i.landsat.toar - Calculates top-of-atmosphere radiance or reflectance
7 and temperature for Landsat MSS/TM/ETM+/OLI
8
10 imagery, radiometric conversion, radiance, reflectance, brightness tem‐
11 perature, atmospheric correction, satellite, Landsat
12
14 i.landsat.toar
15 i.landsat.toar --help
16 i.landsat.toar [-rnp] input=basename output=basename [metfile=name]
17 [sensor=string] [method=string] [date=yyyy-mm-dd] [sun_eleva‐
18 tion=float] [product_date=yyyy-mm-dd] [gain=string] [per‐
19 cent=float] [pixel=integer] [rayleigh=float] [lsat‐
20 met=string[,string,...]] [scale=float] [--overwrite] [--help]
21 [--verbose] [--quiet] [--ui]
22
23 Flags:
24 -r
25 Output at-sensor radiance instead of reflectance for all bands
26
27 -n
28 Input raster maps use as extension the number of the band instead
29 the code
30
31 -p
32 Print output metadata info
33
34 --overwrite
35 Allow output files to overwrite existing files
36
37 --help
38 Print usage summary
39
40 --verbose
41 Verbose module output
42
43 --quiet
44 Quiet module output
45
46 --ui
47 Force launching GUI dialog
48
49 Parameters:
50 input=basename [required]
51 Base name of input raster bands
52 Example: ’B.’ for B.1, B.2, ...
53
54 output=basename [required]
55 Prefix for output raster maps
56 Example: ’B.toar.’ generates B.toar.1, B.toar.2, ...
57
58 metfile=name
59 Name of Landsat metadata file (.met or MTL.txt)
60
61 sensor=string
62 Spacecraft sensor
63 Required only if ’metfile’ not given (recommended for sanity)
64 Options: mss1, mss2, mss3, mss4, mss5, tm4, tm5, tm7, oli8
65 mss1: Landsat-1 MSS
66 mss2: Landsat-2 MSS
67 mss3: Landsat-3 MSS
68 mss4: Landsat-4 MSS
69 mss5: Landsat-5 MSS
70 tm4: Landsat-4 TM
71 tm5: Landsat-5 TM
72 tm7: Landsat-7 ETM+
73 oli8: Landsat_8 OLI/TIRS
74
75 method=string
76 Atmospheric correction method
77 Options: uncorrected, dos1, dos2, dos2b, dos3, dos4
78 Default: uncorrected
79
80 date=yyyy-mm-dd
81 Image acquisition date (yyyy-mm-dd)
82 Required only if ’metfile’ not given
83
84 sun_elevation=float
85 Sun elevation in degrees
86 Required only if ’metfile’ not given
87
88 product_date=yyyy-mm-dd
89 Image creation date (yyyy-mm-dd)
90 Required only if ’metfile’ not given
91
92 gain=string
93 Gain (H/L) of all Landsat ETM+ bands (1-5,61,62,7,8)
94 Required only if ’metfile’ not given
95
96 percent=float
97 Percent of solar radiance in path radiance
98 Required only if ’method’ is any DOS
99 Default: 0.01
100
101 pixel=integer
102 Minimum pixels to consider digital number as dark object
103 Required only if ’method’ is any DOS
104 Default: 1000
105
106 rayleigh=float
107 Rayleigh atmosphere (diffuse sky irradiance)
108 Required only if ’method’ is DOS3
109 Default: 0.0
110
111 lsatmet=string[,string,...]
112 return value stored for a given metadata
113 Required only if ’metfile’ and -p given
114 Options: number, creation, date, sun_elev, sensor, bands, sunaz,
115 time
116 number: Landsat Number
117 creation: Creation timestamp
118 date: Date
119 sun_elev: Sun Elevation
120 sensor: Sensor
121 bands: Bands count
122 sunaz: Sun Azimuth Angle
123 time: Time
124
125 scale=float
126 Scale factor for output
127 Default: 1.0
128
130 i.landsat.toar is used to transform the calibrated digital number of
131 Landsat imagery products to top-of-atmosphere radiance or top-of-atmos‐
132 phere reflectance and temperature (band 6 of the sensors TM and ETM+).
133 Optionally, it can be used to calculate the at-surface radiance or re‐
134 flectance with atmospheric correction (DOS method).
135
136 Usually, to do so the production date, the acquisition date, and the
137 solar elevation are needed. Moreover, for Landsat-7 ETM+ it is also
138 needed the gain (high or low) of the nine respective bands.
139
140 Optionally (recommended), the data can be read from metadata file (.met
141 or MTL.txt) for all Landsat MSS, TM, ETM+ and OLI/TIRS. However, if the
142 solar elevation is given the value of the metadata file is overwritten.
143 This is necessary when the data in the .met file is incorrect or not
144 accurate. Also, if acquisition or production dates are not found in the
145 metadata file then the command line values are used.
146
147 Attention: Any null value or smaller than QCALmin in the input raster
148 is set to null in the output raster and it is not included in the equa‐
149 tions.
150
151 Attention: This module does not respect the current region settings, in
152 order to have the largest possible sample of pixels from where to get
153 the darkest one of the scene and perform the DOS correction. To limit
154 the results to a custom region, the user is advised to clip the results
155 (with r.clip, for instance) or to define the region first, import the
156 images with region cropping, and then running the module.
157
159 The standard geometric and radiometric corrections result in a cali‐
160 brated digital number (QCAL = DN) images. To further standardize the
161 impact of illumination geometry, the QCAL images are first converted
162 first to at-sensor radiance and then to at-sensor reflectance. The
163 thermal band is first converted from QCAL to at-sensor radiance, and
164 then to effective at-sensor temperature in Kelvin degrees.
165
166 Radiometric calibration converts QCAL to at-sensor radiance, a radio‐
167 metric quantity measured in W/(m² * sr * µm) using the equations:
168
169 • gain = (Lmax - Lmin) / (QCALmax - QCALmin)
170
171 • bias = Lmin - gain * QCALmin
172
173 • radiance = gain * QCAL + bias
174 where, Lmax and Lmin are the calibration constants, and QCALmax and
175 QCALmin are the highest and the lowest points of the range of rescaled
176 radiance in QCAL.
177
178 Then, to calculate at-sensor reflectance the equations are:
179
180 • sun_radiance = [Esun * sin(e)] / (PI * d^2)
181
182 • reflectance = radiance / sun_radiance
183 where, d is the earth-sun distance in astronomical units, e is the so‐
184 lar elevation angle, and Esun is the mean solar exoatmospheric irradi‐
185 ance in W/(m² * µm).
186
188 Atmospheric correction and reflectance calibration remove the path ra‐
189 diance, i.e. the stray light from the atmosphere, and the spectral ef‐
190 fect of solar illumination. To output these simple at-surface radiance
191 and at-surface reflectance, the equations are (not for thermal bands):
192
193 • sun_radiance = TAUv * [Esun * sin(e) * TAUz + Esky] / (PI *
194 d^2)
195
196 • radiance_path = radiance_dark - percent * sun_radiance
197
198 • radiance = (at-sensor_radiance - radiance_path)
199
200 • reflectance = radiance / sun_radiance
201 where, percent is a value between 0.0 and 1.0 (usually 0.01), Esky is
202 the diffuse sky irradiance, TAUz is the atmospheric transmittance along
203 the path from the sun to the ground surface, and TAUv is the atmo‐
204 spheric transmittance along the path from the ground surface to the
205 sensor. radiance_dark is the at-sensor radiance calculated from the
206 darkest object, i.e. DN with a least ’dark_parameter’ (usually 1000)
207 pixels for the entire image. The values are,
208
209 • DOS1: TAUv = 1.0, TAUz = 1.0 and Esky = 0.0
210
211 • DOS2: TAUv = 1.0, Esky = 0.0, and TAUz = sin(e) for all bands
212 with maximum wave length less than 1. (i.e. bands 4-6 MSS, 1-4
213 TM, and 1-4 ETM+) other bands TAUz = 1.0
214
215 • DOS3: TAUv = exp[-t/cos(sat_zenith)], TAUz = exp[-t/sin(e)],
216 Esky = rayleigh
217
218 • DOS4: TAUv = exp[-t/cos(sat_zenith)], TAUz = exp[-t/sin(e)],
219 Esky = PI * radiance_dark
220 Attention: Output radiance remain untouched (i.e. no set to 0.0 when it
221 is negative) then they are possible negative values. However, output
222 reflectance is set to 0.0 when is obtained a negative value.
223
225 The output raster cell values can be rescaled with the scale parameter
226 (e.g., with 100 in case of using reflectance output in i.gensigset).
227
228 On Landsat-8 metadata file
229 NASA reports a structure of the L1G Metadata file (LDCM-DFCB-004.pdf)
230 for Landsat Data Continuity Mission (i.e. Landsat-8).
231
232 NASA retains in MIN_MAX_RADIANCE group the necessary information to
233 transform Digital Numbers (DN) in radiance values. Then, i.landsat.toar
234 replaces the possible standard values with the metadata values. The re‐
235 sults match with the values reported by the metada file in RADIOMET‐
236 RIC_RESCALING group.
237
238 Also, NASA reports the same values of reflectance for all bands in
239 max-min values and in gain-bias values. This is strange that all bands
240 have the same range of reflectance. Also, they wrote in the web page as
241 to calculate reflectance directly from DN, first with RADIOMET‐
242 RIC_RESCALING values and second divided by sin(sun_elevation).
243
244 This is a simple rescaling
245
246 • reflectance = radiance / sun_radiance = (DN * RADIANCE_MULT +
247 RADIANCE_ADD) / sun_radiance
248
249 • now reflectance = DN * REFLECTANCE_MULT + REFLECTANCE_ADD
250
251 • then REFLECTANCE_MULT = RADIANCE_MULT / sun_radiance
252
253 • and REFLECTANCE_ADD = RADIANCE_ADD / sun_radiance
254
255 The problem arises when we need ESUN values (not provided) to compute
256 sun_radiance and DOS. We assume that REFLECTANCE_MAXIMUM corresponds to
257 the RADIANCE_MAXIMUM, then
258
259 • REFLECTANCE_MAXIMUM / sin(e) = RADIANCE_MAXIMUM / sun_radiance
260
261 • Esun = (PI * d^2) * RADIANCE_MAXIMUM / REFLECTANCE_MAXIMUM
262 where d is the earth-sun distance provided by metadata file or computed
263 inside the program.
264
265 The i.landsat.toar reverts back the NASA rescaling to continue using
266 Lmax, Lmin, and Esun values to compute the constant to convert DN to
267 radiance and radiance to reflectance with the "traditional" equations
268 and simple atmospheric corrections. Attention: When MAXIMUM values are
269 not provided, i.landsat.toar tries to calculate Lmax, Lmin, and Esun
270 from RADIOMETRIC_RESCALING (in tests the results were the same).
271
272 Calibration constants
273 In verbose mode (flag --verbose), the program write basic satellite
274 data and the parameters used in the transformations.
275
276 Production date is not an exact value but it is necessary to apply cor‐
277 rect calibration constants, which were changed in the dates:
278
279 • Landsat-1 MSS: never
280
281 • Landsat-2 MSS: July 16, 1975
282
283 • Landsat-3 MSS: June 1, 1978
284
285 • Landsat-4 MSS: August 26, 1982 and April 1, 1983
286
287 • Landsat-4 TM: August 1, 1983 and January 15, 1984
288
289 • Landsat-5 MSS: April 6, 1984 and November 9, 1984
290
291 • Landsat-5 TM: May 4, 2003 and April, 2 2007
292
293 • Landsat-7 ETM+: July 1, 2000
294
295 • Landsat-8 OLI/TIRS: launched in 2013
296
298 Metadata file examples
299 Transform digital numbers of Landsat-7 ETM+ in band rasters 203_30.1,
300 203_30.2 [...] to uncorrected at-sensor reflectance in output files
301 203_30.1_toar, 203_30.2_toar [...] and at-sensor temperature in output
302 files 293_39.61_toar and 293_39.62_toar:
303 i.landsat.toar input=203_30. output=_toar \
304 metfile=p203r030_7x20010620.met
305 or
306 i.landsat.toar input=L5121060_06020060714. \
307 output=L5121060_06020060714_toar \
308 metfile=L5121060_06020060714_MTL.txt
309 or
310 i.landsat.toar input=LC80160352013134LGN03_B output=toar \
311 metfile=LC80160352013134LGN03_MTL.txt sensor=oli8 date=2013-05-14
312
313 DOS1 example
314 DN to reflectance using DOS1:
315 # rename channels or make a copy to match i.landsat.toar’s input scheme:
316 g.copy raster=lsat7_2002_10,lsat7_2002.1
317 g.copy raster=lsat7_2002_20,lsat7_2002.2
318 g.copy raster=lsat7_2002_30,lsat7_2002.3
319 g.copy raster=lsat7_2002_40,lsat7_2002.4
320 g.copy raster=lsat7_2002_50,lsat7_2002.5
321 g.copy raster=lsat7_2002_61,lsat7_2002.61
322 g.copy raster=lsat7_2002_62,lsat7_2002.62
323 g.copy raster=lsat7_2002_70,lsat7_2002.7
324 g.copy raster=lsat7_2002_80,lsat7_2002.8
325 Calculation of reflectance values from DN using DOS1 (metadata obtained
326 from p016r035_7x20020524.met.gz):
327 i.landsat.toar input=lsat7_2002. output=lsat7_2002_toar. sensor=tm7 \
328 method=dos1 date=2002-05-24 sun_elevation=64.7730999 \
329 product_date=2004-02-12 gain=HHHLHLHHL
330 The resulting Landsat channels are named lsat7_2002_toar.1 ..
331 lsat7_2002_toar.8.
332
334 • Chander G., B.L. Markham and D.L. Helder, 2009: Remote Sensing
335 of Environment, vol. 113
336
337 • Chander G.H. and B. Markham, 2003: IEEE Transactions On Geo‐
338 science And Remote Sensing, vol. 41, no. 11.
339
340 • Chavez P.S., jr. 1996: Image-based atmospheric corrections -
341 Revisited and Improved. Photogrammetric Engineering and Remote
342 Sensing 62(9): 1025-1036.
343
344 • Huang et al: At-Satellite Reflectance, 2002: A First Order Nor‐
345 malization Of Landsat 7 ETM+ Images.
346
347 • R. Irish: Landsat 7. Science Data Users Handbook. February 17,
348 2007; 15 May 2011.
349
350 • Markham B.L. and J.L. Barker, 1986: Landsat MSS and TM
351 Post-Calibration Dynamic Ranges, Exoatmospheric Reflectances
352 and At-Satellite Temperatures. EOSAT Landsat Technical Notes,
353 No. 1.
354
355 • Moran M.S., R.D. Jackson, P.N. Slater and P.M. Teillet, 1992:
356 Remote Sensing of Environment, vol. 41.
357
358 • Song et al, 2001: Classification and Change Detection Using
359 Landsat TM Data, When and How to Correct Atmospheric Effects?
360 Remote Sensing of Environment, vol. 75.
361
363 i.atcorr, i.colors.enhance, r.mapcalc, r.in.gdal
364
365 Landsat Data Dictionary by USGS
366
368 E. Jorge Tizado (ej.tizado unileon es), Dept. Biodiversity and Envi‐
369 ronmental Management, University of León, Spain
370
372 Available at: i.landsat.toar source code (history)
373
374 Accessed: Saturday Jan 21 21:16:41 2023
375
376 Main index | Imagery index | Topics index | Keywords index | Graphical
377 index | Full index
378
379 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
380
381
382
383GRASS 8.2.1 i.landsat.toar(1)