← Back to branch summary

~ubuntu-branches/ubuntu/vivid/grass/vivid-proposed

« back to all changes in this revision

Viewing changes to imagery/i.landsat.toar/i.landsat.toar.html

  • Committer: Package Import Robot
  • Author(s): Bas Couwenberg
  • Date: 2015-02-20 23:12:08 UTC
  • mfrom: (8.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20150220231208-1u6qvqm84v430b10
Tags: 7.0.0-1~exp1
* New upstream release.
* Update python-ctypes-ternary.patch to use if/else instead of and/or.
* Drop check4dev patch, rely on upstream check.
* Add build dependency on libpq-dev to grass-dev for libpq-fe.h.
* Drop patches applied upstream, refresh remaining patches.
* Update symlinks for images switched from jpg to png.

Show diffs side-by-side

added added

removed removed

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