Skip to main content

Command line tool and Python library for working with STAC

Project description

stactools

Build Status Documentation PyPI version Conda (channel only) License

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.

Table of Contents

Installation

To install the latest version via pip:

pip install stactools

To install the latest version with conda:

conda install -c conda-forge 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.

Optional dependencies

stactools includes one optional dependency:

  • s3: Enables s3 hrefs via fsspec and s3fs

To install the single optional dependency:

pip install stactools[s3]

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.

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.

Developing

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

Using docker

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

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

Documentation

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

Code owners and repository maintainer(s)

This repository uses a code owners file to automatically request reviews for new pull requests. The current primary maintainer(s) of this repository are listed under the * rule in the CODEOWNERS file.

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.

Releasing

See RELEASING.md for the steps to create a new release.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stactools-0.4.6.tar.gz (42.3 kB view details)

Uploaded Source

Built Distribution

stactools-0.4.6-py3-none-any.whl (52.9 kB view details)

Uploaded Python 3

File details

Details for the file stactools-0.4.6.tar.gz.

File metadata

  • Download URL: stactools-0.4.6.tar.gz
  • Upload date:
  • Size: 42.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.2

File hashes

Hashes for stactools-0.4.6.tar.gz
Algorithm Hash digest
SHA256 f305b78ce761649f563b2cdd6aabdbf34db613ff93fde5c4c5b8cc280abccb91
MD5 438806c8f3bd33f5c814a6c9eaae119f
BLAKE2b-256 8eb10934152c98d132806663109fe50e20c131f516bcae27d51524abbbb5d6d3

See more details on using hashes here.

Provenance

File details

Details for the file stactools-0.4.6-py3-none-any.whl.

File metadata

  • Download URL: stactools-0.4.6-py3-none-any.whl
  • Upload date:
  • Size: 52.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.2

File hashes

Hashes for stactools-0.4.6-py3-none-any.whl
Algorithm Hash digest
SHA256 081c464f3983a639f4a7dddf465064b2dadc7c49baa25845c57aad379d13377b
MD5 3462616a9c1fbee4580854a4c1d2449d
BLAKE2b-256 83fe1ff3eb973c88041bb29b2f006cdfb10db49a4a053e3784090b61c000ff43

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page