gbdxtools: Python tools for using GBDX

gbdxtools is a package for ordering imagery and launching workflows on DigitalGlobe's GBDX platform.

In order to use gbdxtools, you need GBDX credentials. Email [email protected] to get these.

Documentation is hosted here: http://gbdxtools.readthedocs.org/en/latest/. Example scripts can be found under the /examples directory of this repo.

Currently, the following Python versions are supported: 2.7, 3.3, 3.4, 3.5

See the license file for license rights and limitations (MIT).

Updates

There have been reports of authentication errors while creating a gbdx interface if the file ~/.gbdx-config is already populated with an access token. In this case, delete everything below and including the line [gbdx_token] within ~/.gbdx-config and create a new gbdx interface.

Installation

Conda is the recommended way to install gbdxtools:

conda install -c digitalglobe gbdxtools

Troubleshooting

These are various tips to follow if your installation fails.

Dependencies

As of gbdxtools version 0.11.3 libcurl and GDAL (>=2.1.0) are required. To install these packages use:

# Ubuntu users:
sudo add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable
sudo apt update
sudo apt-get install gdal-bin python-gdal python3-gdal libcurl4-openssl-dev

# Mac Users:
xcode-select --install # to install libcurl
brew install https://raw.githubusercontent.com/OSGeo/homebrew-osgeo4mac/master/Formula/gdal-20.rb

Windows Users

Conda installation should work fine on windows for python version 2.7. If you are using python 3, you can install with pip, first install some dependencies with conda:

conda install -c conda-forge scipy
conda install -c conda-forge scikit-image
pip install gbdxtools

pip

Make sure you have the latest pip version:

pip install pip --upgrade

Ubuntu users

If you run into trouble with the installation of cryptography, make sure that the following dependencies are installed:

sudo apt-get install build-essential libssl-dev libffi-dev python-dev libcurl4-openssl-dev

Mac OSX Users

If you run into trouble with the installation of cryptography and see a message that <ffi.h> could not be found, you can run:

xcode-select --install

Then run "pip install gbdxtools" again. See stackoverflow for discussion on what is going wrong and why this fixes it (http://stackoverflow.com/questions/27328049/missing-usr-include-after-yosemite-and-xcode-install)

If you are running in a virtualenv and run into issues you may need upgrade pip in the virtualenv:

cd <your_project_folder>
. venv/bin/activate
pip install --upgrade pip
pip install --upgrade gbdxtools
# you might also need to remove token from your .gbdx-config file
nano -w ~.gbdx-config
# then, remove the [gbdx_token] section and json= part

GDAL

Versions of gbdxtools >= 0.11.3 require the GDAL library (>= 2.1.0) to be installed.

conda

If your installation with pip keeps failing, try creating a conda environment and installing gbdxtools within this environment.

For Ubuntu, install conda with the following commands (choose default options at prompt):

wget https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh
bash Miniconda2-latest-Linux-x86_64.sh

For OS X, install conda with the following commands (choose default options at prompt):

wget https://repo.continuum.io/miniconda/Miniconda2-latest-MacOSX-x86_64.sh
bash Miniconda2-latest-MacOSX-x86_64.sh

Make sure that conda is in your path. Then create a conda environment:

conda create -n env python ipython

Activate the environment:

source activate env

Upgrade pip (if required):

pip install pip --upgrade

Install gbdxtools:

conda install -c digitalglobe  gbdxtools

Development

Clone the repo:

git clone https://github.com/digitalglobe/gbdxtools.git

cd gbdxtools

Start a virtual environment:

virtualenv venv

. venv/bin/activate

Install the requirements:

pip install -r requirements.txt

Please follow this python style guide: https://google.github.io/styleguide/pyguide.html. 80-90 columns is fine.

Tests

This package uses pytest http://pytest.org/latest/contents.html.

pytest allows for tests to be written using various frameworks, so unittest.TestCase, pytest, and nose style tests will be detected and run.

To run all of the tests:

py.test tests

If you want only the unit or integration tests do either of:

py.test tests/integration
py.test tests/unit

Note: you may have to issue the following in your virtualenv for the tests to find gbdxtools properly:

pip install -e .

Create a new version

To create a new version:

bumpversion ( major | minor | patch )
git push --tags

Don't forget to update the changelog and upload to pypi.

Contributing

Please contribute! Please make pull requests directly to master. Before making a pull request, please:

• Ensure that all new functionality is covered by unit tests.
• Verify that all unit tests are passing.
• Ensure that all functionality is properly documented.
• Ensure that all functions/classes have proper docstrings so sphinx can autogenerate documentation.
• Fix all versions in setup.py (and requirements.txt)