| 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² * sr * µ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² * µ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ón, Spain |