• Stars
    star
    104
  • Rank 330,604 (Top 7 %)
  • Language
    Python
  • License
    Other
  • Created about 4 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Command line utility and Python library for STAC

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 two optional dependency:

  • s3: Enables s3 hrefs via fsspec and s3fs
  • validate: Enables stac validate and stac lint

To install optional dependencies:

pip install 'stactools[s3]'
pip install 'stactools[validate]'

Docker

To download the Docker image from the registry:

docker pull ghcr.io/stac-utils/stactools:latest

Running

stac --help

Running from 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

Clone the repository and install it in editable mode with the dev optional dependencies:

git clone https://github.com/stac-utils/stactools.git
cd stactools
pip install -e '.[dev]'

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 '.[dev]'

Developing the docs

To build and serve the docs, the development requirements must be installed with pip install -e '.[docs]'. 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.

More Repositories

1

pystac

Python library for working with any SpatioTemporal Asset Catalog (STAC)
Python
337
star
2

stac-fastapi

STAC API implementation with FastAPI.
Python
242
star
3

pystac-client

Python client for searching STAC APIs
Python
150
star
4

pgstac

Schema, functions and a python library for storing and accessing STAC collections and items in PostgreSQL
PLpgSQL
140
star
5

titiler-pgstac

TiTiler + PgSTAC
Python
77
star
6

stac-server

A Node-based STAC API, AWS Serverless, OpenSearch
JavaScript
71
star
7

stac-geoparquet

Convert STAC items between JSON, GeoParquet, pgstac, and Delta Lake.
Python
70
star
8

qgis-stac-plugin

QGIS plugin for reading STAC APIs
Python
69
star
9

stac-pydantic

Pydantic data models for the STAC spec
Python
61
star
10

xstac

STAC from xarray
Python
55
star
11

stac-fastapi-pgstac

PostgreSQL backend for stac-fastapi using pgstac (https://github.com/stac-utils/pgstac)
Python
49
star
12

stac-layer

Visualize a STAC Item or Collection on a Leaflet Map
HTML
47
star
13

stac-validator

Validator for the stac-spec
HTML
45
star
14

xpystac

For extending xarray.open_dataset to accept pystac objects
Python
30
star
15

stac-fastapi-elasticsearch-opensearch

Elasticsearch backend for stac-fastapi with Opensearch support.
Python
29
star
16

stac-asset

Read and download STAC Assets, using a variety of authentication schemes
Python
21
star
17

stac-vrt

Python
21
star
18

stac-check

Linting and validation tool for STAC assets
HTML
17
star
19

stac-api-validator

A STAC API validation client
Python
17
star
20

stac-terminal

Output info on STAC Items in the terminal
Python
16
star
21

stac4s

a scala library with primitives to build applications using the SpatioTemporal Asset Catalogs specification
Scala
15
star
22

stac-task

Provides a class interface for running custom algorithms on STAC ItemCollections
Python
14
star
23

stac-node-validator

Simple validator for STAC Items, Catalogs, and Collections. STAC 1.0.0 compliant!
JavaScript
13
star
24

stac-fastapi-sqlalchemy

PostgreSQL backend for stac-fastapi using SQLAlchemy
Python
9
star
25

stac-api-benchmark

STAC API Benchmark
Python
8
star
26

stac-index

A service that lists all available and registered STAC catalogs and APIs.
JavaScript
6
star
27

stac-migrate

A tool to migrate Items, Catalogs and Collections from old versions to the most recent one.
JavaScript
6
star
28

stac-crosswalks

Common metadata crosswalks to help people map from their existing data into STAC
6
star
29

stac-fields

A minimal STAC library that contains a list of STAC fields with some metadata and helper functions for styling as HTML.
JavaScript
6
star
30

stac-table

Python
5
star
31

stac-ecosystem

Collaboration space for the broader STAC software and data ecosystem
5
star
32

stac-sentinel

STAC Collections and Items for Sentinel data
Python
3
star
33

developer-guide

Developer guide for stac-utils
Python
2
star
34

stac-examples

A small repository of real world STAC collections and items, to let users get a sense of how STAC is used, without having to dive deep into huge catalogs.
2
star