Documentation

This page describes how to install, use, and contribute to COAL.

Dependencies

Numpy and Spectral Python
GDAL
QGIS

Installation
Downloading Data

USGS Digital Spectral Library 06 and 07
AVIRIS
The National Map

Usage

Mineral Classification
Mining Identification
Environmental Correlation

Development

Dependencies

COAL has been tested on x86_64 GNU/Linux and is expected to work without modification on any Unix-like system. COAL supports Python versions 2.6+ and 3.3+ Required dependencies include NumPy, Spectral Python, and GDAL version 2.2.0+. The recommended geographic information system is QGIS.

Numpy and Spectral Python

The easiest way to install both Numpy and Spectral Python is from the Python Package Index (PyPI) with pip:

$ sudo pip install spectral

GDAL

The command-line utilities from GDAL 2.2.0+ are required for correct processing of rotated ENVI files in the environmental correlation module. If necessary, GDAL can be installed from source following the instructions for Building on Unix.

You can get the latest version of GDAL from osgeo.org and follow the 'install from osgeo.org' instructions or install from source and follow the 'install from source' instructions.

Install from osgeo.org

Download the latest version from osgeo

cd into the gdal directory you just downloaded

$ cd gdal
$ ./configure --with-python
$ make
$ sudo make install

Confirm with

$ gdalwarp --version
GDAL 2.2.3, released 2017/11/20

Install from Source

Check out the source code:

$ git clone https://github.com/OSGeo/gdal.git
$ cd gdal/gdal
$ git checkout --track origin/2.2

Configure GDAL with the Python bindings. The default installation directory is /usr/local. Compile with make and install as root with either make install or checkinstall to create a package that can be easily installed and uninstalled. GDAL does not include a make uninstall target.

$ ./configure --with-python
$ make
$ sudo checkinstall

After installation, the correct version can be verified by calling the command-line interface or Python API.

$ gdalwarp --version
GDAL 2.2.0beta2, released 2017/04/23

>>> import osgeo.gdal
>>> print osgeo.gdal.__version__
2.2.0beta2
>>> print osgeo.gdal.VersionInfo()
2020000

Common errors with gdal Installation

You may need to update your $PATH and $PYTHONPATH variables to include gdal and osgeo if they are not found after installation and build

i.e. For gdal you may enter something like this depending on what your path to gdal is

$ export PATH=/Users/YOURUSERNAME/Desktop/gdal:$PATH
$ PYTHONPATH="/Users/YOURUSERNAME/Desktop/gdal:$PYTHONPATH"
$ export PYTHONPATH

On mac if you have GDAL Error 6

ERROR 6: Unable to load PROJ.4 library (libproj.dylib), creation of OGRCoordinateTransformation failed.

Then type this into your terminal

$ export LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib

QGIS

QGIS is the recommended geographic information system for viewing COAL data products. QGIS must be linked against GDAL 2.2.0+ to import rotated ENVI files correctly. You can either download from qgis.org or install QGIS from source to link to the correct version of GDAL.

Download from qgis.org

You can download the latest standalone version of QGIS from qgis.org.

*NOTE* For mac users QGIS will display all images vertically, North to South, they will not be rotated as they are in reality.

Windows users will use QGIS Browser contained withing the download to view the images generated by pycoal.

Install from source

See the INSTALL file in the root of the QGIS source tree for more details. The following steps can be used to install QGIS from a Debian source package. We can verify that Debian 8 was used to build QGIS however we encourage feedback and use of newer Debian versions.

Install the dependencies and download the Debian source package with apt-get or aptitude.

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get build-dep qgis
$ sudo apt-get install bison cmake doxygen flex git graphviz grass-dev libexpat1-dev libfcgi-dev libgdal-dev libgeos-dev libgsl0-dev libopenscenegraph-dev libosgearth-dev libpq-dev libproj-dev libqt4-dev libqt4-opengl-dev libqtwebkit-dev libqwt-dev libspatialindex-dev libspatialite-dev libsqlite3-dev pkg-config pyqt4-dev-tools python-all python-all-dev python-qt4 python-qt4-dev python-sip python-sip-dev txt2tags xauth xfonts-100dpi xfonts-75dpi xfonts-base xfonts-scalable xvfb devscripts pkg-kde-tools checkinstall
$ apt-get source qgis
$ cd qgis-2.4.0

Create a build directory and configure QGIS with cmake.

$ mkdir build-master
$ cd build-master
$ cmake -Wno-dev -DCMAKE_INSTALL_PREFIX=/usr/local ..

Verify that the line -- Found GDAL: /usr/local/lib/libgdal.so (2.2.0beta2) appears in the output. Then compile and install as root.

$ make
$ sudo make install

Installation

The COAL Python package pycoal can be installed from PyPI with pip.

$ sudo pip install pycoal

The latest development source may be obtained from GitHub.

Downloading Data

USGS Digital Spectral Library 06 and 07

COAL was developed using classifications from the USGS Digital Spectral Library 06. The ENVI spectral library files s06av95a_envi.hdr and s06av95a_envi.sli can be accessed via FTP or found in pycoal/tests. COAL also supports USGS Digital Spectral Library 07. The ENVI spectral library files s07_AV95_envi.hdr and s07_AV95_envi.sli for USGS Spectral Library 7 can be found in pycoal/tests

AVIRIS

Imaging spectrometer data from the Jet Propulsion Laboratory can be downloaded or requested via the AVIRIS and AVIRIS-NG websites.

The National Map

The National Map from the United States Geological Survey (USGS) provides detailed hydrography, transportation, and elevation datasets.

Usage

This section demonstrates basic usage of COAL. Refer to the API reference for detailed documentation. The following images display several COAL data products.

**Figure 4:** Environmental correlation image.

Mineral Classification

The Mineral Classification API provides methods for generating visible-light (Figure 1) and mineral classified (Figure 2) 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.

#!/usr/bin/env python
import pycoal

# path to spectral library
library_filename = "s06av95a_envi.hdr"

# path to orthocorrected, scaled-reflectance image
input_filename = "ang20150420t182050_corr_v1e_img.hdr"

# path to save RGB image
rgb_filename = "ang20150420t182050_corr_v1e_img_rgb.hdr"

# path to save mineral classified image
classified_filename = "ang20150420t182050_corr_v1e_img_class.hdr"

# create a new mineral classification instance
mineral_classification = pycoal.mineral.MineralClassification(input_filename)

# generate a georeferenced visible-light image
mineral_classification.to_rgb(input_filename, rgb_filename)

# generate a mineral classified image
mineral_classification.classify_image(input_filename, classified_filename)

Mining Identification

The Mining Identification API filters mineral classified images to identify specific classes of interest (Figure 3), by default proxies for coal mining in the USGS Digital Spectral Library 06.

#!/usr/bin/env python
import pycoal

# path to mineral classified image
mineral_filename = "ang20150420t182050_corr_v1e_img_class.hdr"

# path to save mining classified image
mining_filename = "ang20150420t182050_corr_v1e_img_class_mining.hdr"

# create a new mining classification instance
mining_classification = pycoal.mining.MiningClassification()

# generate a mining classified image
mining_classification.classify_image(mineral_filename, mining_filename)

Environmental Correlation

The Environmental Correlation API finds pixels in a mining classified image that are within a certain number of meters from features in a vector layer (Figure 4) such as flow lines in the National Hydrography Dataset (NHD).

#!/usr/bin/env python
import pycoal

# path to mining classified image
mining_filename = "ang20150420t182050_corr_v1e_img_class_mining.hdr"

# path to hydrography data
vector_filename = "NHDNM/Shape/NHDFlowline.shp"

# path to save environmental correlation image
correlation_filename = "ang20150420t182050_corr_v1e_img_class_mining_NHDFlowline_correlation.hdr"

# create a new environmental correlation instance
environmental_correlation = pycoal.environment.EnvironmentalCorrelation()

# generate an environmental correlation image of mining pixels within 10 meters of a stream
environmental_correlation.intersect_proximity(mining_filename, vector_filename, 10.0, correlation_filename)

Development

Contribute to the project through our GitHub Organization, refer to the COAL wiki for development documentation, and contact the team to get involved.