GBDXtools is a GBDX Python package that allows one to easily access GBDX APIs to search the DigitalGlobe catalog, and order and process imagery. If you’ve completed any of the GBDX Notebooks tutorials, then you’ve seen gbdxtools in action. An important thing to know is that once you’ve installed gbdxtools locally, you can write and run analysis code in your local Python environment exactly as you would in GBDX Notebooks.
The first required step is to install Anaconda, an open source Python distribution that simplifies package management, dependencies, and environments (we recommend this step even if you already have a Python installation). This distribution includes Conda, which you will need in order to install gbdxtools using the provided conda environment file.
1.1 Download and install the full version of Anaconda
Requirements:
We have provided a Conda environment file for easy installion of gbdxtools, along with its required dependencies, within a Conda virtual environment. Virtual environments keep the dependencies required by different projects in separate places, so that they don’t interfere with each other. Please use the following Conda commands to install gbdxtools.
Mac users:
2.1 Download the gbdxtools_env.yml file from this repo
2.2 Open a terminal window
2.3 Update conda
conda update conda
2.4 Create the conda environment
conda env create -f /full/path/to/gbdxtools_env.yml
2.5 Activate the environment
source activate gbdxtools
2.6 Try importing all the modules (if no errors are raised, everything is working right)
python -c 'import rasterio; import fiona; import shapely; import gbdxtools'
Windows users:
2.1 Download the gbdxtools_env.yml file from this repo
2.2 Start Anaconda Prompt
2.3 Update conda
conda update conda
2.4 Create the conda environment
conda env create -f C:\\full\path\to\gbdx_environment.yml
2.5 Activate the environment
activate gbdxtools
2.6 Try importing all the modules (if no errors are raised, everything is working right)
python -c "import rasterio; import fiona; import shapely; import gbdxtools"
3.1 Activate your account - once you’ve been assigned to your company’s GBDX account (we will do this for you, please coordinate with your company’s GBDX POC), you’ll be sent an email from DigitalGlobe with instructions on how to activate your account. Open the message and click on “ACTIVATE YOUR ACCOUNT”. This will pop up a window where you will prompted to set a password.
You can start Python from the gbdxtools environment, copy and paste the following code, and fill in your GBDX credentials. You will know that you’ve successfully installed gbdxtools if there’s no error and it prints your GBDX S3 information.
import gbdxtools
gbdx = gbdxtools.Interface(
username='',
password=''
)
gbdx.s3.info
From here, you can code against DigitalGlobe imagery using gbdxtools just as you did in the GBDX Notebooks tutorials, using the exact same gbdxtools commands.
When you are finished with this tutorial, shut down the Jupyter Notebook and kernel, and deactivate the Conda environment where you installed gbdxtools.
5.1 Stop the jupyter notebook by using the keyboard shortcut CONTROL + C, then 'Y' to confirm that you would like to shut down the notebook server.
Mac users:
5.2 Deactivate the virtual environment
source deactivate
5.3 (Optional) Remove the environment
conda remove --name gbdxtools --all
Windows users:
5.2 Deactivate the virtual environment
deactivate
5.3 (Optional) Remove the environment
conda remove --name gbdxtools --all
6. Optional .gbdx-config file:
It is recommended that you save your GBDX credentials in a config file, which is safer and more convenient than coding in your GBDX credentials.
6.1 Create a blank text file and copy and paste the following information:
[gbdx]
user_name = <your_user_name>
user_password = <your_password>
6.2 Replace <your_user_name> and <your_password> with the username (email) and password associated with your GBDX account.
6.3 Save this file in your user directory with the filename .gbdx-config
- be sure to include the . at the beginning of the filename
- the filename needs to be saved without an extension
Mac users:
Typing cd ~ in the terminal will take to your user directory, place your config file here.
Windows users:
Typing echo %USERPROFILE% will print out the user directory, place your config file here.
6.4 Test your gbdxtools installation and config file:
- Open a terminal/cmd window and type ipython
- Copy and paste the following code, which will result in an error if it can’t locate your config file or if the formatting is incorrect.
from gbdxtools import Interface
gbdx = Interface()
exit()
Config file troubleshooting:
Windows: select the filename and try to delete the ‘.txt’ extension. You may need to save it as .gbdx-config. (notice the trailing period). Also, deselect the ‘hide extensions’ setting on your computer so you can verify if you’ve successfully deleted the extension.
Mac: select the config file, right-click and select ‘Get Info’ to verify that you’ve saved the file without an extension.
We would love to hear your feedback. Feel free to email GBDX-support@digitalglobe.com with comments and suggestions.