https://github.com/mapbox/rio-toa
Top Of Atmosphere (TOA) calculations for Landsat 8
https://github.com/mapbox/rio-toa
imagery rasterio satellite
Last synced: 10 days ago
JSON representation
Top Of Atmosphere (TOA) calculations for Landsat 8
- Host: GitHub
- URL: https://github.com/mapbox/rio-toa
- Owner: mapbox
- Created: 2016-06-17T01:27:49.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2021-12-05T14:08:05.000Z (over 4 years ago)
- Last Synced: 2025-12-25T12:09:20.677Z (3 months ago)
- Topics: imagery, rasterio, satellite
- Language: Python
- Size: 129 MB
- Stars: 39
- Watchers: 120
- Forks: 21
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.txt
Awesome Lists containing this project
README
# rio-toa
[](https://travis-ci.org/mapbox/rio-toa)
[](https://coveralls.io/github/mapbox/rio-toa?branch=the-sunangle-also-rises)
Top Of Atmosphere (TOA) calculations for Landsat 8
## Before/After
##### Savissivik, Greenland 2016-02-29
###### Pre-TOA vs Post-TOA Histograms
##### Portland OR, USA 2016-06-25
###### Pre-TOA vs Post-TOA Histograms
##### Cape Horn, Argentina 2015-08-07
###### Pre-TOA vs Post-TOA Histograms
## Install
We highly recommend installing in a virtualenv. Once activated,
```
pip install -U pip
pip install rio-toa
```
Or install from source
```
git clone https://github.com/mapbox/rio-toa.git
cd rio-toa
pip install -U pip
pip install -r requirements-dev.txt
pip install -e .
```
## Python API
### `rio_toa.radiance`
The `radiance` module calculates top of atmosphere radiance of Landsat 8 as outlined here: http://landsat.usgs.gov/Landsat8_Using_Product.php.
#### 1. `radiance`
The `radiance.randiance` function accepts the following as inputs:
- numpy 2D array (single band)
- ML (multiplicative rescaling factor from scene mtl)
- AL (additive rescaling factor from scene mtl)
and outputs:
- numpy 2D array (single band)
```
>>> from rio_toa import radiance
>>> from rio_toa import toa_utils
...
>>> toa = radiance.radiance(tif, ML, AL, src_nodata=0)
>>> toa_rescaled = toa_utils.rescale(toa, rescale_factor, dst_dtype)
```
#### 2.`calculate_landsat_radiance`
```
>>> from rio_toa import reflectance
...
>>> radiance.calculate_landsat_radiance(src_path, src_mtl, dst_path,
creation_options, band_number, dst_dtype, processes)
```
======
### `rio_toa.reflectance`
The `reflectance` module calculates top of atmosphere reflectance of Landsat 8 as outlined here: http://landsat.usgs.gov/Landsat8_Using_Product.php.
#### 1. `reflectance`
The `reflectance.reflectance` function accepts the following as inputs:
- numpy ndarray
- MR (multiplicative rescaling factor from scene mtl), numpy ndarray
- AR (additive rescaling factor from scene mtl), numpy ndarray
- E (sun elevation angle from mtl or per pixel), numpy ndarray
and outputs:
- numpy ndarray
```
>>> from rio_toa import reflectance
>>> from rio_toa import toa_utils
...
>>> toa = reflectance.reflectance(img, MR, AR, E, src_nodata=0)
>>> toa_rescaled = toa_utils.rescale(toa, rescale_factor, dst_dtype)
```
#### 2. `calculate_landsat_reflectance`
```
>>> from rio_toa import reflectance
...
>>> reflectance.calculate_landsat_reflectance(list(src_paths), src_mtl, dst_path,
rescale_factor, creation_options, list(band_numbers),
dst_dtype, processes, pixel_sunangle)
```
- per pixel solar angles could be used instead of the scene center solar angle:
This option requires the additional ['DATE_ACQUIRED'] and ['SCENE_CENTER_TIME'] from mtl files.
```
>>> from rio_toa import reflectance
>>> from rio_toa import sun_utils
>>> import riomucho
>>> from rasterio import warp
>>> from rasterio.coords import BoundingBox
...
>>> date_collected = mtl['L1_METADATA_FILE']['PRODUCT_METADATA']['DATE_ACQUIRED']
>>> time_collected_utc = mtl['L1_METADATA_FILE']['PRODUCT_METADATA']['SCENE_CENTER_TIME']
>>> bboxes = [BoundingBox(
*warp.transform_bounds(
src_crs',
{'init': u'epsg:4326'},
*open_files[i].window_bounds(window)))
for i in range(data.shape[0])]
>>> E_stack = riomucho.utils.array_stack(
[sun_utils.sun_elevation(
bbox,
data.shape[1:],
'date_collected',
'time_collected_utc')[np.newaxis, :]
for bbox in bboxes])
...
>>> output = toa_utils.rescale(reflectance(
data,
M_stack,
A_stack,
E_stack,
'src_nodata'),
rescale_factor, dst_dtype)
```
### `rio_toa.brightness_temp`
The 'brightness_temp' module converts Landsat 8 TIRS band data from spectral radiance to brightness temperature as outlined here: http://landsat.usgs.gov/Landsat8_Using_Product.php.
#### 1. `brightness_temp`
The `brightness_temp.brightness_temp` function accepts the following as inputs:
- numpy 2D array (single band)
- ML (multiplicative rescaling factor from scene mtl)
- AL (additive rescaling factor from scene mtl)
- K1 (thermal conversion constant from the scene mtl)
- K2 (thermal conversion constant from the scene mtl)
and outputs:
- numpy 2D array (single band)
```
>>> from rio_toa import brightness_temp
>>> from rio_toa import toa_utils
...
>>> bt = radiance.radiance(tif, ML, AL, K1, K2, src_nodata=0)
>>> bt_rescaled= toa_utils.temp_rescale(toa, temp_scale)
```
#### 2.`calculate_landsat_brightness_temperature`
```
>>> from rio_toa import brightness_temp
...
>>> brightness_temp.calculate_landsat_brightness_temperature(src_path, src_mtl,
dst_path, temp_scale,
creation_options, thermal_bidx,
dst_dtype, processes)
```
## `CLI`
### `radiance`
```
Usage: rio toa radiance [OPTIONS] SRC_PATH SRC_MTL DST_PATH
Calculates Landsat8 Top of Atmosphere Radiance
Options:
--dst-dtype Output datatype. Default='float32'
['float32', 'float64', 'uint16', 'uint8']
-r, --rescale-factor Rescale post-TOA tifs to 55,000.
Default=float(55000.0/2**16).
Range: [float(55000.0/2**16), float(1.0)]
-t, --readtemplate File path template. Default='.*/LC8.*\_B{b}.TIF'
-j, --workers INTEGER
-t, --readtemplate File path template. Default='.*/LC8.*\_B{b}.TIF'
--l8-bidx INTEGER L8 Band that the src_path represents (Default is
parsed from file name)
-v, --verbose
--co NAME=VALUE Driver specific creation options.See the
documentation for the selected output driver for more
information.
--help Show this message and exit.
```
### `reflectance`
```
Usage: rio toa reflectance [OPTIONS] SRC_PATH SRC_MTL DST_PATH
Calculates Landsat8 Top of Atmosphere Reflectance
Options:
--dst-dtype Output datatype. Default='float32'
['float32', 'float64', 'uint16', 'uint8']
-r, --rescale-factor Rescale post-TOA tifs to 55,000.
Default=float(55000.0/2**16).
Range: [float(55000.0/2**16), float(1.0)]
-t, --readtemplate File path template. Default='.*/LC8.*\_B{b}.TIF'
-j, --workers INTEGER number of processes
--l8-bidx INTEGER L8 Band that the src_path represents (default is
parsed from file name)
-v, --verbose Debugging mode
-p, --pixel-sunangle Per pixel sun elevation
--co NAME=VALUE Driver specific creation options.See the
documentation for the selected output driver for more
information.
--help Show this message and exit.
```
### `brighttemp`
```
Usage: rio toa brighttemp [OPTIONS] SRC_PATH SRC_MTL DST_PATH
Calculates Landsat8 at-satellite brightness temperature TIRS band data can
be converted from spectral radiance to brightness temperature using the
thermal constants provided in the metadata file:
Options:
-d, --dst-dtype [float32|float64|uint16|uint8]
Output data type
-s, --temp_scale [K|F|C] Temperature scale [Default = K (Kelvin)]
-t, --readtemplate TEXT File path template [Default
='.*/LC8.*\_B{b}.TIF']
-j, --workers INTEGER
--thermal-bidx INTEGER L8 thermal band that the src_path
represents(Default is parsed from file name)
-v, --verbose
--co NAME=VALUE Driver specific creation options.See the
documentation for the selected output driver
for more information.
--help Show this message and exit.
```
### `parsemtl`
Takes a file or stdin MTL in txt format, and outputs a json-formatted MTL to stdout
```
Usage: rio toa parsemtl [OPTIONS] [MTL]
Converts a Landsat 8 text MTL to JSON
Options:
--help Show this message and exit.
```
From a local `*_MTL.txt`:
```
rio toa parsemtl tests/data/LC81060712016134LGN00_MTL.txt
```
From stdin:
```
cat tests/data/LC81060712016134LGN00_MTL.txt | rio toa parsemtl
```
From stdin on `s3`:
```
aws s3 cp s3://landsat-pds/L8/106/071/LC81060712016134LGN00/LC81060712016134LGN00_MTL.txt - | rio toa parsemtl
```