Awesome

rio-toa + Landsat 5

Top Of Atmosphere (TOA) calculations for Landsat 8 (and Landsat 5)

Note: This is a fork since the maintainers seem to have orphaned the original repository. The repository at hand has one modification in addition to enable Landsat 5.

Before/After

Savissivik, Greenland 2016-02-29

toa_greenland_gif

Pre-TOA vs Post-TOA Histograms

greenland_hist

Portland OR, USA 2016-06-25

toa_portland_gif

Pre-TOA vs Post-TOA Histograms

portland_hist

Cape Horn, Argentina 2015-08-07

toa_caphorn_gif

Pre-TOA vs Post-TOA Histograms

portland_hist

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

Awesome

rio-toa + Landsat 5

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

Python API

rio_toa.radiance

1. radiance

2.calculate_landsat_radiance

rio_toa.reflectance

1. reflectance

2. calculate_landsat_reflectance

rio_toa.brightness_temp

1. brightness_temp

2.calculate_landsat_brightness_temperature

CLI

radiance

reflectance

brighttemp

parsemtl

`rio_toa.radiance`

1. `radiance`

2.`calculate_landsat_radiance`

`rio_toa.reflectance`

1. `reflectance`

2. `calculate_landsat_reflectance`

`rio_toa.brightness_temp`

1. `brightness_temp`

2.`calculate_landsat_brightness_temperature`

`CLI`

`radiance`

`reflectance`

`brighttemp`

`parsemtl`