ESPA Tools

Documentation Status PyPI Build Status Documentation Built by gendocs GitHub

An open-source Python package for simple loading of Landsat imagery as NumPy arrays. When downloading Landsat imagery from USGS Earth Explorer, the datasets contain many bands (.tif files) and a few metadata files (.txt and .xml files). espatools is built to parse the .xml metadata file to read all of the bands for that dataset and provide a convenient and intuitive means of accessing that metadata along side the raw data in a Python environment. espatools can be found on GitHub and PyPI.

Collage of RGB colors

Connections

  • The package heavily uses properties for the creation of strongly typed objects in a consistent, declarative way.
  • This package implements a way to convert these datasets to a PyVista dataset (vtkImageData).
  • PVGeo has implemented an interface for espatools to read Landsat imagery via XML metadata files. Check out PVGeo’s Landsat Reader for more details.

Getting Started

espatools is available from PyPI

$ pip install espatools

Usage

We think espatools is easy to use; give it a try and let us know what you think as this is just the alpha-release!

  1. First, checkout this Jupyter Notebook for a demonstration of some simple plotting after reading Landsat imagery in a Python environment.
  1. And take a look at the .to_pyvista() method on RasterSet objects to have a 3D dataset of the imagery in PyVista/VTK
  2. Then take a look at the Landsat Reader in PVGeo’s documentation where espatools has an interface for direct use in ParaView.

Example False Color

import espatools
import matplotlib.pyplot as plt

# Create the reader to manage I/O
reader = espatools.RasterSetReader(filename='metadata.xml')

# Perform the read and yield a raster set
raster = reader.read()

# Get an RGB color scheme
color = raster.get_rgb('false_a')

# Now plot the false color image
plt.imshow(color)

The results of the above code yield the following false color image:

RGB False Color

You can also view the dataset in 3D using PyVista:

mesh = raster.to_pyvista()
mesh.plot(scalars='false_a', rgb=True, cpos='xy')

About ESPA Tools

  • Author: Bane Sullivan
  • License: BSD-3-Clause
  • Copyright: 2018, Bane Sullivan
  • Version: 0.1.1

espatools: An open-source Python package for simple loading of Landsat imagery as NumPy arrays.

meta

This module holds classes that contian the metadata information for a raster data object.

BoundingCoordinates
class espatools.meta.BoundingCoordinates(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • east (Float): East line, a float
  • north (Float): North line, a float
  • south (Float): South line, a float
  • west (Float): West line, a float
east

east (Float) – East line, a float

north

north (Float) – North line, a float

south

south (Float) – South line, a float

west

west (Float) – West line, a float

Corner
class espatools.meta.Corner(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • latitude (Float): The latitude, a float in range [-90.0, 90.0]
  • location (String): The location, a unicode string
  • longitude (Float): The longitude, a float in range [-180.0, 180.0]
latitude

latitude (Float) – The latitude, a float in range [-90.0, 90.0]

location

location (String) – The location, a unicode string

longitude

longitude (Float) – The longitude, a float in range [-180.0, 180.0]

CornerPoint
class espatools.meta.CornerPoint(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • location (String): The location, a unicode string
  • x (Float): The X value, a float
  • y (Float): The Y value, a float
location

location (String) – The location, a unicode string

x

x (Float) – The X value, a float

y

y (Float) – The Y value, a float

Lum
class espatools.meta.Lum(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • bias (Float): The bias, a float
  • gain (Float): The gain, a float
bias

bias (Float) – The bias, a float

gain

gain (Float) – The gain, a float

PixelSize
class espatools.meta.PixelSize(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • units (String): The pixel size units, a unicode string
  • x (Float): The X size of the pixel, a float
  • y (Float): The Y size of the pixel, a float
units

units (String) – The pixel size units, a unicode string

x

x (Float) – The X size of the pixel, a float

y

y (Float) – The Y size of the pixel, a float

Projection
class espatools.meta.Projection(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • corner_point (a list of CornerPoint): The corner points, a list (each item is an instance of CornerPoint)
  • datum (String): The projection datum, a unicode string
  • grid_origin (String): The grid origin, a unicode string
  • projection (String): The coordinate projection, a unicode string
  • units (String): The projection units, a unicode string

Optional Properties:

  • albers_proj_params (Dictionary): The Albers projection parameters, a dictionary
  • ps_proj_params (Dictionary): The PS projection parameters, a dictionary
  • sin_proj_params (Dictionary): The Sin projection parameters, a dictionary
  • utm_proj_params (Dictionary): The UTM projection parameters, a dictionary
albers_proj_params

albers_proj_params (Dictionary) – The Albers projection parameters, a dictionary

corner_point

corner_point (a list of CornerPoint) – The corner points, a list (each item is an instance of CornerPoint)

datum

datum (String) – The projection datum, a unicode string

grid_origin

grid_origin (String) – The grid origin, a unicode string

projection

projection (String) – The coordinate projection, a unicode string

ps_proj_params

ps_proj_params (Dictionary) – The PS projection parameters, a dictionary

sin_proj_params

sin_proj_params (Dictionary) – The Sin projection parameters, a dictionary

units

units (String) – The projection units, a unicode string

utm_proj_params

utm_proj_params (Dictionary) – The UTM projection parameters, a dictionary

RasterMetaData
class espatools.meta.RasterMetaData(**kwargs)[source]

Bases: properties.base.base.HasProperties

An object to contain all the information for a single swath.

Required Properties:

  • bounding_coordinates (BoundingCoordinates): The bounding coordinates, an instance of BoundingCoordinates
  • corner (a list of Corner): The corner points, a list (each item is an instance of Corner)
  • data_provider (String): The data provider, a unicode string
  • instrument (String): The instrument on the satellite, a unicode string
  • orientation_angle (Float): The orientation angle, a float in range [-360.0, 360.0]
  • projection_information (Projection): The projection, an instance of Projection
  • satellite (String): The satellite from which data was aquired, a unicode string

Optional Properties:

  • acquisition_date (String): The date of acquisition, a unicode string
  • earth_sun_distance (Float): The earth-sun distance, a float
  • level1_production_date (String): Production date, a unicode string
  • lpgs_metadata_file (String): metadata file, a unicode string
  • product_id (String): Data product ID, a unicode string
  • scene_center_time (String): Center time, a unicode string
  • solar_angles (SolarAngle): The solar angles, an instance of SolarAngle
  • wrs (WRS): WRS, an instance of WRS
acquisition_date

acquisition_date (String) – The date of acquisition, a unicode string

bounding_coordinates

bounding_coordinates (BoundingCoordinates) – The bounding coordinates, an instance of BoundingCoordinates

corner

corner (a list of Corner) – The corner points, a list (each item is an instance of Corner)

data_provider

data_provider (String) – The data provider, a unicode string

earth_sun_distance

earth_sun_distance (Float) – The earth-sun distance, a float

instrument

instrument (String) – The instrument on the satellite, a unicode string

level1_production_date

level1_production_date (String) – Production date, a unicode string

lpgs_metadata_file

lpgs_metadata_file (String) – metadata file, a unicode string

orientation_angle

orientation_angle (Float) – The orientation angle, a float in range [-360.0, 360.0]

product_id

product_id (String) – Data product ID, a unicode string

projection_information

projection_information (Projection) – The projection, an instance of Projection

satellite

satellite (String) – The satellite from which data was aquired, a unicode string

scene_center_time

scene_center_time (String) – Center time, a unicode string

solar_angles

solar_angles (SolarAngle) – The solar angles, an instance of SolarAngle

wrs

wrs (WRS) – WRS, an instance of WRS

SolarAngle
class espatools.meta.SolarAngle(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • azimuth (Float): The azimuth, a float
  • units (String): The units, a unicode string
  • zenith (Float): The zenith, a float
azimuth

azimuth (Float) – The azimuth, a float

units

units (String) – The units, a unicode string

zenith

zenith (Float) – The zenith, a float

ThermalConst
class espatools.meta.ThermalConst(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

k1

k1 (Float) – K1, a float

k2

k2 (Float) – K2, a float

ValidRange
class espatools.meta.ValidRange(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • max (Float): Maximum of valid range, a float
  • min (Float): Minimum of valid range, a float
max

max (Float) – Maximum of valid range, a float

min

min (Float) – Minimum of valid range, a float

WRS
class espatools.meta.WRS(**kwargs)[source]

Bases: properties.base.base.HasProperties

Required Properties:

  • path (Integer): The WRS path, an integer
  • row (Integer): The WRS row, an integer
  • system (Integer): The system type, an integer
path

path (Integer) – The WRS path, an integer

row

row (Integer) – The WRS row, an integer

system

system (Integer) – The system type, an integer

raster
Band
class espatools.raster.Band(**kwargs)[source]

Bases: properties.base.base.HasProperties

Contains raster metadata and data for a single band.

Required Properties:

  • data_type (String): Band data type, a unicode string
  • file_name (String): Original file name, a unicode string
  • fill_value (Integer): fill value, an integer, Default: -9999
  • long_name (String): Long display name, a unicode string
  • name (String): Name of the band, a unicode string
  • nlines (Integer): number of lines, an integer
  • nsamps (Integer): number of samples, an integer
  • pixel_size (PixelSize): The pixel size, an instance of PixelSize
  • product (String): Data product, a unicode string
  • short_name (String): Short name, a unicode string

Optional Properties:

  • add_offset (Float): Add offset, a float
  • app_version (String): app version, a unicode string
  • bitmap_description (Dictionary): band bitmap description (not always present), a dictionary (keys: a unicode string; values: a unicode string)
  • category (String): Band category, a unicode string
  • data_units (String): Data units, a unicode string
  • percent_coverage (Float): percent coverage, a float
  • production_date (String): production date, a unicode string
  • qa_description (String): QA description, a unicode string
  • radiance (Lum): The radiance, an instance of Lum
  • reflectance (Lum): The reflectance, an instance of Lum
  • resample_method (String): resample method, a unicode string
  • saturate_value (Integer): Saturate value, an integer
  • scale_factor (Float): Scaling factor, a float
  • source (String): Band source, a unicode string
  • thermal_const (ThermalConst): The thermal const, an instance of ThermalConst
  • valid_range (ValidRange): The valid data range, an instance of ValidRange
add_offset

add_offset (Float) – Add offset, a float

app_version

app_version (String) – app version, a unicode string

bitmap_description

bitmap_description (Dictionary) – band bitmap description (not always present), a dictionary (keys – a unicode string; values: a unicode string)

category

category (String) – Band category, a unicode string

data = None
data_type

data_type (String) – Band data type, a unicode string

data_units

data_units (String) – Data units, a unicode string

file_name

file_name (String) – Original file name, a unicode string

fill_value

fill_value (Integer) – fill value, an integer, Default – -9999

long_name

long_name (String) – Long display name, a unicode string

name

name (String) – Name of the band, a unicode string

nlines

nlines (Integer) – number of lines, an integer

nsamps

nsamps (Integer) – number of samples, an integer

percent_coverage

percent_coverage (Float) – percent coverage, a float

pixel_size

pixel_size (PixelSize) – The pixel size, an instance of PixelSize

product

product (String) – Data product, a unicode string

production_date

production_date (String) – production date, a unicode string

qa_description

qa_description (String) – QA description, a unicode string

radiance

radiance (Lum) – The radiance, an instance of Lum

reflectance

reflectance (Lum) – The reflectance, an instance of Lum

resample_method

resample_method (String) – resample method, a unicode string

saturate_value

saturate_value (Integer) – Saturate value, an integer

scale_factor

scale_factor (Float) – Scaling factor, a float

short_name

short_name (String) – Short name, a unicode string

source

source (String) – Band source, a unicode string

thermal_const

thermal_const (ThermalConst) – The thermal const, an instance of ThermalConst

valid_range

valid_range (ValidRange) – The valid data range, an instance of ValidRange

ColorSchemes
class espatools.raster.ColorSchemes[source]

Bases: object

A class to hold various RGB color schemes fo reference. These color schemes are defined on the USGS website.

LOOKUP_FALSE_COLOR_A = {'LANDSAT_4': ['sr_band5', 'sr_band4', 'sr_band3'], 'LANDSAT_5': ['sr_band5', 'sr_band4', 'sr_band3'], 'LANDSAT_7': ['sr_band5', 'sr_band4', 'sr_band3'], 'LANDSAT_8': ['sr_band6', 'sr_band5', 'sr_band4']}
LOOKUP_FALSE_COLOR_B = {'LANDSAT_4': ['sr_band7', 'sr_band5', 'sr_band3'], 'LANDSAT_5': ['sr_band7', 'sr_band5', 'sr_band3'], 'LANDSAT_7': ['sr_band7', 'sr_band5', 'sr_band3'], 'LANDSAT_8': ['sr_band7', 'sr_band6', 'sr_band4']}
LOOKUP_FALSE_COLOR_C = {'LANDSAT_4': ['sr_band7', 'sr_band4', 'sr_band2'], 'LANDSAT_5': ['sr_band7', 'sr_band4', 'sr_band2'], 'LANDSAT_7': ['sr_band7', 'sr_band4', 'sr_band2'], 'LANDSAT_8': ['sr_band7', 'sr_band5', 'sr_band3']}
LOOKUP_INFRARED = {'LANDSAT_4': ['sr_band4', 'sr_band3', 'sr_band2'], 'LANDSAT_5': ['sr_band4', 'sr_band3', 'sr_band2'], 'LANDSAT_7': ['sr_band4', 'sr_band3', 'sr_band2'], 'LANDSAT_8': ['sr_band5', 'sr_band4', 'sr_band3']}
LOOKUP_TRUE_COLOR = {'LANDSAT_4': ['sr_band3', 'sr_band2', 'sr_band1'], 'LANDSAT_5': ['sr_band3', 'sr_band2', 'sr_band1'], 'LANDSAT_7': ['sr_band3', 'sr_band2', 'sr_band1'], 'LANDSAT_8': ['sr_band4', 'sr_band3', 'sr_band2']}
RasterSet
class espatools.raster.RasterSet(**kwargs)[source]

Bases: properties.base.base.HasProperties

The main class to hold a set of raster data. This contains all of the bands
for a given set of rasters. This is generated by the RasterSetReader.

Required Properties:

  • bands (Dictionary): A dictionary of bands for the swath, a dictionary (keys: a unicode string; values: an instance of Band)
  • global_metadata (RasterMetaData): Raster metadata, an instance of RasterMetaData
  • nlines (Integer): The number of lines, an integer
  • nsamps (Integer): The number of samples, an integer
  • pixel_size (PixelSize): The pixel size, an instance of PixelSize

Optional Properties:

  • version (String): version, a unicode string
GetRGB(*args, **kwargs)[source]
RGB_SCHEMES = {'false_a': {'LANDSAT_8': ['sr_band6', 'sr_band5', 'sr_band4'], 'LANDSAT_5': ['sr_band5', 'sr_band4', 'sr_band3'], 'LANDSAT_4': ['sr_band5', 'sr_band4', 'sr_band3'], 'LANDSAT_7': ['sr_band5', 'sr_band4', 'sr_band3']}, 'false_b': {'LANDSAT_8': ['sr_band7', 'sr_band6', 'sr_band4'], 'LANDSAT_5': ['sr_band7', 'sr_band5', 'sr_band3'], 'LANDSAT_4': ['sr_band7', 'sr_band5', 'sr_band3'], 'LANDSAT_7': ['sr_band7', 'sr_band5', 'sr_band3']}, 'false_c': {'LANDSAT_8': ['sr_band7', 'sr_band5', 'sr_band3'], 'LANDSAT_5': ['sr_band7', 'sr_band4', 'sr_band2'], 'LANDSAT_4': ['sr_band7', 'sr_band4', 'sr_band2'], 'LANDSAT_7': ['sr_band7', 'sr_band4', 'sr_band2']}, 'infrared': {'LANDSAT_8': ['sr_band5', 'sr_band4', 'sr_band3'], 'LANDSAT_5': ['sr_band4', 'sr_band3', 'sr_band2'], 'LANDSAT_4': ['sr_band4', 'sr_band3', 'sr_band2'], 'LANDSAT_7': ['sr_band4', 'sr_band3', 'sr_band2']}, 'true': {'LANDSAT_8': ['sr_band4', 'sr_band3', 'sr_band2'], 'LANDSAT_5': ['sr_band3', 'sr_band2', 'sr_band1'], 'LANDSAT_4': ['sr_band3', 'sr_band2', 'sr_band1'], 'LANDSAT_7': ['sr_band3', 'sr_band2', 'sr_band1']}}
bands

bands (Dictionary) – A dictionary of bands for the swath, a dictionary (keys – a unicode string; values: an instance of Band)

get_rgb(scheme='infrared', names=None)[source]

Get an RGB color scheme based on predefined presets or specify your own band names to use. A given set of names always overrides a scheme.

Note

Available schemes are defined in RGB_SCHEMES and include:

  • true
  • infrared
  • false_a
  • false_b
  • false_c
global_metadata

global_metadata (RasterMetaData) – Raster metadata, an instance of RasterMetaData

nlines

nlines (Integer) – The number of lines, an integer

nsamps

nsamps (Integer) – The number of samples, an integer

pixel_size

pixel_size (PixelSize) – The pixel size, an instance of PixelSize

to_pyvista(z=0.0)[source]

Create a pyvista.UniformGrid of this raster. Use the z argument to control the dataset’s Z spatial reference.

validate()[source]
version

version (String) – version, a unicode string

read

This module holds the file I/O methods for rasters and bands.

RasterSetReader
class espatools.read.RasterSetReader(**kwargs)[source]

Bases: object

Read a series of raster files via their XML metadata file in ESPA schema

Read(*args, **kwargs)[source]
SetFileName(filename)[source]
static clean_dict(d)[source]
generate_band(band, meta_only=False, cast=False)[source]

Genreate a Band object given band metadata

Parameters:band (dict) – dictionary containing metadata for a given band
Returns:the loaded Band onject
Return type:Band
read(meta_only=False, allowed=None, cast=False)[source]

Read the ESPA XML metadata file

static read_tif(tifFile)[source]

Reads a tif file to a 2D NumPy array

set_file_name(filename)[source]
set_properties
espatools.read.set_properties(has_props_cls, input_dict, include_immutable=True)[source]

A helper method to set an HasProperties object’s properties from a dictionary