stactools
is a high-level command line tool and Python 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 operations on STAC data.
See packages for more information.
To install the latest version:
pip install stactools
To install the latest development version from the 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.
stactools
includes one optional dependency:
s3
: Enables s3 hrefs viafsspec
ands3fs
To install the single optional dependency:
pip install stactools[s3]
If you are working in Python 3.10, you'll need to install a pre-release version of rasterio 1.3:
pip install --pre rasterio
pip install stactools
To download the Docker image from the registry:
docker pull ghcr.io/stac-utils/stactools:latest
stac --help
docker run --rm ghcr.io/stac-utils/stactools:latest --help
See the documentation page for the latest docs.
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.
There are over 25 packages that translate specific types of data into STAC, including imagery sources like aster, landsat, modis, naip, planet, sentinel1, sentinel1-grd, sentinel2, sentinel3, landuse/landcover data (corine, cgls_lc100, aafc-landuse), Digital Elevation Models (DEMs) (cop-dem, alos-dem), population data (gpw, worldpop), pointclouds and many more.
There are also cool tools like stactools-browse which makes it super easy to deploy a STAC Browser from the command line to browse any local data.
For the list of officially supported packages see the list of STAC packages
on the stactools-packages GitHub organization.
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
.
Basic development can be done with your system's default Python, though it it recommended to use a virtual environment. E.g.:
git clone https://github.com/stac-utils/stactools.git
cd stactools
python -m venv venv
pip install -e . # install stactools into the virtual environment in editable mode
pip install -r requirements-dev.txt # install development requirements
Linting and formatting are handled with pre-commit. You will need to install pre-commit before committing any changes:
pre-commit install
Tests are handled with pytest:
pytest
Run a Juypter notebook:
scripts/notebook
You can also develop in a Docker container. 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
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
You can run the CLI through docker by running:
docker/stac --help
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
To build and serve the docs, the development requirements must be installed with pip install -r requirements-dev.txt
.
To build the docs, you can use make html
from inside of the docs directory, 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.
You can also run the previous commands in the docker container using:
docker/console
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.
See RELEASING.md for the steps to create a new release.