Welcome to the COAL documentation!¶

Contents:

Introduction¶

COAL is a Python library for processing hyperspectral imagery from remote sensing devices such as the Airborne Visible/InfraRed Imaging Spectrometer (AVIRIS). COAL is being developed as a 2016 – 2017 senior capstone collaboration between scientists at the Jet Propulsion Laboratory (JPL) and computer science students at Oregon State University (OSU). COAL aims to provide a suite of algorithms for classifying land cover, identifying mines and other geographic features, and correlating them with environmental data sets. COAL is Free and Open Source Software under the terms of the GNU GENERAL PUBLIC LICENSE, Version 2.

What is COAL?¶

COAL provides a suite of algorithms and a command line interface (all written in Python) to identify, classify, characterize, and quantify (by reporting a number of key metrics) the direct and indirect impacts of MTM and related destructive surface mining activities across the continental U.S.A (and further afield).

Dependencies¶

Spectral Python: needed for the mineral classification and mining identification APIs.
NumPy: needed for the mineral classification and mining identification APIs.
GDAL: needed for the GIS processing API.

More information on COAL can be seen at the project Website as well as the docs directory.

Quickstart¶

The pycoal Command Line Interface¶

When you install pycoal via pip, conda, from source or via Docker, you will automatically have access to a number of CLI utlity tools made available on your system path. These tools are descrtibed below. All tools can be invoked with the -h flag to print help.

pycoal-mineral¶

$ pycoal-mineral -h

usage: pycoal-mineral [-h] [-i IMAGE] [-s SLIB] [-r RGB_FILENAME]
                   [-c CLASSIFIED_FILENAME]

pycoal-mineral -- a CLI for COAL mineral classification

pycoal-mineral provides a CLI which demonstrates how the COAL Mineral Classification
API provides methods for generating visible-light and mineral classified images.
Mineral classification can take hours to days depending on the size of the spectral
library and the available computing resources, so running a script in the background
is recommended. More reading an this example can be seen at
https://capstone-coal.github.io/docs#usage

@author:     COAL Developers

@copyright:  Copyright (C) 2018 COAL Developers

@license:    GNU General Public License version 2

@contact:    coal-capstone@googlegroups.com

optional arguments:
   -h, --help            show this help message and exit
   -i IMAGE, --image IMAGE
                     Input file to be processed
   -s SLIB, --slib SLIB  Spectral Library filename
   -r RGB_FILENAME, --rgb_filename RGB_FILENAME
                     RGB File Name
   -c CLASSIFIED_FILENAME, --classified_filename CLASSIFIED_FILENAME
                     Classified File Name

pycoal-mining¶

$ pycoal-mining -h

usage: pycoal-mining [-h] [-mi INPUT] [-mo OUTPUT]

pycoal-mining -- a CLI for COAL mining classification

pycoal-mining provides a CLI which demonstrates how the COAL Mining Classification
API provides methods for generating mining classified images.
Mining classification runtime depends largely on the size of the spectral
library and the available computing resources. More reading an this example can be seen at
https://capstone-coal.github.io/docs#usage

@author:     COAL Developers

@copyright:  Copyright (C) 2018 COAL Developers

@license:    GNU General Public License version 2

@contact:    coal-capstone@googlegroups.com

optional arguments:
   -h, --help            show this help message and exit
   -mi INPUT, --mineral_input INPUT
                     Input classified mineral file to be processed
   -mo OUTPUT, --mining_output OUTPUT
                     Output mining classified image filename

pycoal-environment¶

$ pycoal-environment -h

usage: pycoal-environment [-h] [-m MINING_FILENAME] [-hy VECTOR_FILENAME]
                       [-e CORRELATION_FILENAME]

pycoal-environment -- a CLI for COAL environment classification

pycoal-environment provides a CLI which demonstrates how the COAL Environment Classification
API provides methods for generating environment classified images.
Environment classification runtime depends largely on the size of the spectral
library and the available computing resources. More reading an this example can be seen at
https://capstone-coal.github.io/docs#usage

@author:     COAL Developers

@copyright:  Copyright (C) 2018 COAL Developers

@license:    GNU General Public License version 2

@contact:    coal-capstone@googlegroups.com

optional arguments:
   -h, --help            show this help message and exit
   -m MINING_FILENAME, --mining MINING_FILENAME
                     Input mining classified file to be processed
   -hy VECTOR_FILENAME, --hydrography VECTOR_FILENAME
                     Path to hydrography data
   -e CORRELATION_FILENAME, --environment CORRELATION_FILENAME
                     Output environmental correlation image

pycoal Examples¶

In the examples directory you can find several python scripts with specific applications of COAL. The README provides all of the information you need to get going. If you find an issue with the examples, please report it at our issue tracker.

Mineral Classification API¶

class pycoal.mineral.MineralClassification(library_file_name, class_names=None, threshold=0.0, in_memory=False)[source]¶

__init__(library_file_name, class_names=None, threshold=0.0, in_memory=False)[source]¶

Construct a new MineralClassification object with a spectral library in ENVI format such as the USGS Digital Spectral Library 06 or the `ASTER Spectral Library Version 2.0 <https://asterweb.jpl.nasa.gov/`_ converted with pycoal.mineral.AsterConversion.convert().

If provided, the optional class name parameter will initialize the classifier with a subset of the spectral library, otherwise the full spectral library will be used.

The optional threshold parameter defines a confidence value between zero and one below which classifications will be discarded, otherwise all classifications will be included.

In order to improve performance on systems with sufficient memory, enable the optional parameter to load entire images.

Parameters:	library_file_name (str) – filename of the spectral library class_names (str[], optional) – list of names of classes to include threshold (float, optional) – classification threshold in_memory (boolean, optional) – enable loading entire image

classify_image(image_file_name, classified_file_name)[source]¶

Classify minerals in an AVIRIS image using spectral angle mapper classification and save the results to a file.

Parameters:	image_file_name (str) – filename of the image to be classified classified_file_name (str) – filename of the classified image
Returns:	None

static filter_classes(classified_file_name)[source]¶

Modify a classified image to remove unused classes.

Parameters:	classified_file_name (str) – file of the classified image
Returns:	None

static subset_spectral_library(spectral_library, class_names)[source]¶

Create a copy of the spectral library containing only the named classes.

Parameters:	spectral_library (SpectralLibrary) – ENVI spectral library class_names (str[]) – list of names of classes to include
Returns:	subset of ENVI spectral library
Return type:	SpectralLibrary

static to_rgb(image_file_name, rgb_image_file_name, red=680.0, green=532.5, blue=472.5)[source]¶

Generate a three-band RGB image from an AVIRIS image and save it to a file.

Parameters:	image_file_name (str) – filename of the source image rgb_image_file_name (str) – filename of the three-band RGB image red (float, optional) – wavelength in nanometers of the red band green (float, optional) – wavelength in nanometers of the green band blue (float, optional) – wavelength in nanometers of the blue band
Returns:	None

class pycoal.mineral.AsterConversion[source]¶

__init__()[source]¶

This class provides a method for converting the ASTER Spectral Library Version 2.0 into ENVI format.

Parameters:	None –

classmethod convert(data_dir='', db_file='', hdr_file='')[source]¶

This class method generates an ENVI format spectral library file. data_dir is optional as long as db_file is provided. Note that generating an SQLite database takes upwards of 10 minutes and creating an ENVI format file takes up to 5 minutes. Note: This feature is still experimental.

Parameters:	data_dir (str, optional) – path to directory containing ASCII data files db_file (str) – name of the SQLite file that either already exists if `data_dir` isn’t provided, or will be generated if `data_dir` is provided hdr_file (str) – name of the ENVI spectral library to generate (without the `.hdr` or `.sli` extension)

Mining Identification API¶

class pycoal.mining.MiningClassification(class_names=[u'Schwertmannite BZ93-1 s06av95a=b', u'Renyolds_TnlSldgWet SM93-15w s06av95a=a', u'Renyolds_Tnl_Sludge SM93-15 s06av95a=a'])[source]¶

__init__(class_names=[u'Schwertmannite BZ93-1 s06av95a=b', u'Renyolds_TnlSldgWet SM93-15w s06av95a=a', u'Renyolds_Tnl_Sludge SM93-15 s06av95a=a'])[source]¶

Construct a new MiningClassification object given an optional list of spectral class names which defaults to coal mining proxies.

Parameters:	class_names (str[]) – list of class names to identify.

classify_image(image_file_name, classified_file_name)[source]¶

Classify mines or other features in a COAL mineral classified image by copying relevant pixels and discarding the rest in a new file.

Parameters:	image_file_name (str) – filename of the image to be classified classified_file_name (str) – filename of the classified image
Returns:	None

Environmental Correlation API¶

class pycoal.environment.EnvironmentalCorrelation[source]¶

__init__()[source]¶: Construct a new EnvironmentalCorrelation object.

create_empty_copy(source_filename, destination_filename)[source]¶

Create an empty copy of a COAL classified image with the same size.

Parameters:	source_filename (str) – filename of the source image destination_filename (str) – filename of the destination image

intersect_proximity(mining_filename, vector_filename, proximity, correlated_filename)[source]¶

Generate an environmental correlation image containing pixels from the mining classified image detected within a given distance of features within a vector layer.

Parameters:	mining_filename (str) – filename of the mining classified image vector_filename (str) – filename of vector layer proximity (float) – distance in meters correlated_filename (str) – filename of the correlated image

proximity(feature_filename, proximity_filename)[source]¶

Generate a proximity map from the features.

Parameters:	feature_filename (str) – filename of the feature image proximity_filename (str) – filename of the proximity image

rasterize(vector_filename, feature_filename)[source]¶

Burn features from a vector image onto a raster image.

Parameters:	vector_filename (str) – filename of the vector image feature_filename (str) – filename of the raster image

Indices and tables¶

Index