Command line tool and Python library for working with STAC
Project description
stactools
stactools
is a command line tool and library for working with STAC.
It is based on PySTAC.
This is the core stactools
repository, which provides a basic command line interface (CLI) and API for working with STAC catalogs.
There are a suite of packages available in other repositories for working with a variety of datasets and for doing more complicated oprations on STAC data.
See packages for more information.
Installation
To install the latest stable version:
> pip install stactools
From source repository:
> git clone https://github.com/stac-utils/stactools.git
> cd stactools
> pip install .
NOTE: In order to read and write Cloud Optimized Geotiffs, GDAL version 3.1 or greater is required. If your system GDAL is older than version 3.1, consider using Docker or Conda to get a modern GDAL.
Optional dependencies
stactools
includes some optional dependencies:
s3
: Enables s3 hrefs viafsspec
ands3fs
To install a single optional dependency:
> pip install stactools[s3]
To install all optional dependencies:
> pip install stactools[all]
Docker
To download the Docker image from the registry:
> docker pull ghcr.io/stac-utils/stactools:latest
Running
> stac --help
Docker
> docker run --rm ghcr.io/stac-utils/stactools:latest --help
Documentation
See the documentation page for the latest docs.
Packages
stactools
is comprised of many other sub-packages that provide library and CLI functionality.
Officially supported packages are hosted in the Github stactools-packages
organization, and other subpackages may be available from other sources.
Below is a list of officially supported packages and their current build status.
Each package can be installed via pip install stactools-{package}
, e.g. pip install stactools-landsat
.
Third-party packages can be installed in the same way, or, if they are not on PyPI, directly from the source repository, e.g. pip install /path/to/my/code/stactools-greatdata
.
Function packages
These extend the stac
command line utility to provide additional funcionality.
name | description | build status |
---|---|---|
stactools-browse | Launch stac-browser against a local catalog |
Dataset packages
These are designed to work with specific types of geospatial data.
name | data type | build status |
---|---|---|
stactools-aster | ASTER | |
stactools-cgls_lc100 | Copernicus Global Land Cover Layers | |
stactools-corine | CORINE Land Cover | |
stactools-landsat | USGS LANDSAT | |
stactools-naip | USDA National Agriculture Imagery Program | |
stactools-planet | Planet | |
stactools-sentinel2 | Sentinel-2 | |
stactools-threedep | USGS 3D Elevation Program (formerly the National Elevation Dataset or NED) |
Developing
Some packages require environments with more complex environments than can be set up just through pip.
For example, the stactools.aster
package uses rasterio functionality that required a GDAL enabled with the HDF4 format.
Because of this, it's recommended to utilize docker or conda to ensure a consistent environment.
Using docker
Build the container with:
> docker/build
Once the container is built, you can run the scripts/
scripts inside a docker console by running:
> docker/console
A complete build and test can be run with:
> docker/cibuild
It is recommended to do a Docker CI build before submitting a pull request to ensure your changes will (likely) pass Github's CI.
In scenarios where you want to run scripts in docker/
but don't want to run the build, images can be downloaded via the pull
script:
> docker/pull
Run a Juypter notebook:
> docker/notebook
Using conda
conda is a useful tool for managing dependencies, both binary and Python-based.
If you have conda installed, you can create a new environment for stactools
development by running the following command from the top-level directory in this repo:
> conda env create -f environment.yml
Then activate the stactools
environment:
> conda activate stactools
Finally, install stactools
in editable mode and all development requirements:
> pip install -e .
> pip install -r requirements-dev.txt
Using virtualenv
If not using docker or conda, it's recommended to use virtualenv to keep isolate the python environment used to develop stactools
.
See virtualenv documentation for more detailed information, but as a shortcut here's some quick steps:
- Make sure virtualenv is installed
- Run
virtualenv venv
- Activate the virtualenv with
source venv/bin/activate
Running the CLI against development code
You can run the CLI through docker by running
> docker/stac --help
or in the local environment with
> scripts/stac --help
Unit Tests
Unit tests are in the tests
folder. To run unit tests, use unittest
:
> python -m unittest discover tests
To run linters, code formatters, and test suites all together, use test
:
> ./docker/test
or
> ./scripts/test
The test script also runs lint and code quality checks.
Run a Juypter notebook:
> scripts/notebook
Documentation
To build and serve the docs, all of the requirements must be installed with scripts/update
.
Make sure Pandoc is installed.
Also make sure sphinx is available, which should be installed with requirements-dev.txt
.
You can also run the following in the docker container using
> docker/console
To build the docs, you can use make html
, and to build the docs and start a server that watches for changes, use make livehtml
:
> cd docs
> make html
> make livehtml
If using make livehtml
, once the server starts, navigate to http://localhost:8000 to see the docs.
Use 'make' without arguments to see a list of available commands.
Adding a new package
To create a new stactools
package, use the stactools
package template.
stactools
utilizes Python's namespace packages to provide a suite of tools all under the stactools
namespace.
If you would like your package to be considered for inclusion as a core stactools
package, please open an issue on this repository with a link to your package repository.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for stactools-0.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a2b0ec0bce0b292b43e16596f9c3edfbbf6851c34a2ee2c7f634c8b74990483e |
|
MD5 | 1e5928933d02c183a8ba0d04eca9f17e |
|
BLAKE2b-256 | d13d46077beadea6f005a814af7949ef73ba7d2547cbb31d46578e449a013bf1 |