ESPA Tools¶
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.
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!
- First, checkout this Jupyter Notebook for a demonstration of some simple plotting after reading Landsat imagery in a Python environment.
- And take a look at the
.to_pyvista()
method onRasterSet
objects to have a 3D dataset of the imagery in PyVista/VTK - 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:
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¶
Corner¶
CornerPoint¶
Lum¶
PixelSize¶
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)
-
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
-
utm_proj_params
¶ utm_proj_params (
Dictionary
) – The UTM projection parameters, a dictionary
- corner_point (a list of
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
-
bounding_coordinates
¶ bounding_coordinates (
BoundingCoordinates
) – The bounding coordinates, an instance of BoundingCoordinates
-
orientation_angle
¶ orientation_angle (
Float
) – The orientation angle, a float in range [-360.0, 360.0]
-
projection_information
¶ projection_information (
Projection
) – The projection, an instance of Projection
-
solar_angles
¶ solar_angles (
SolarAngle
) – The solar angles, an instance of SolarAngle
- bounding_coordinates (
SolarAngle¶
ThermalConst¶
ValidRange¶
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
-
bitmap_description
¶ bitmap_description (
Dictionary
) – band bitmap description (not always present), a dictionary (keys – a unicode string; values: a unicode string)
-
data
= None¶
-
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
- data_type (
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
-
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
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