Metadata-Version: 2.1
Name: stacterm
Version: 0.2.0rc3
Summary: STAC Items in the terminal
Author-email: Matthew Hanson <matt.a.hanson@gmail.com>
License: MIT License
Project-URL: homepage, https://github.com/stac-utils/stac-terminal
Keywords: stac
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas >=1.2
Requires-Dist: termtables >=0.2
Requires-Dist: plotext >=3.1
Provides-Extra: dev
Requires-Dist: pre-commit >=3.1.1 ; extra == 'dev'
Requires-Dist: pre-commit-hooks >=4.4.0 ; extra == 'dev'
Requires-Dist: black >=23.1.0 ; extra == 'dev'
Requires-Dist: ruff >=0.0.253 ; extra == 'dev'
Requires-Dist: mypy >=1.0.1 ; extra == 'dev'
Requires-Dist: pip-tools >=6.12.3 ; extra == 'dev'
Requires-Dist: pytest >=7.2.2 ; extra == 'dev'
Requires-Dist: pytest-cov >=4.0.0 ; extra == 'dev'
Requires-Dist: pyupgrade >=3.3.1 ; extra == 'dev'
Requires-Dist: isort >=5.12.0 ; extra == 'dev'
Requires-Dist: types-python-dateutil >=2.8.19.14 ; extra == 'dev'

# stacterm

This library is for displaying information (tables, calendars, plots, histograms) about [STAC](https://stacspec.org/) Items in the terminal. It takes as input a STAC ItemCollection (a GeoJSON FeatureCollection of STAC Items), either by specifying a filename or by piping output from another program.

## Installation

Install from PyPi:

```
$ pip install stacterm
```

PySTAC and Pandas are required, along with two dependencies for rendering tables ([termtables](https://pypi.org/project/termtables/)) and plots ([plotext](https://pypi.org/project/plotext/)) in the terminal.

## Usage

stacterm main usage is as a CLI progam `stacterm`. Use help to see options available:

```
$ stacterm -h
usage: stacterm [-h] {table,cal,hist,plot} ...

Terminal STAC

positional arguments:
  {table,cal,hist,plot}
    table               Output a table
    cal                 Output a calendar
    hist                Output a histogram
    plot                Output a plot

optional arguments:
  -h, --help            show this help message and exit
```

All of the sub-commands in `stacterm` can take optional field names. A field name is:

- `id`: The ID of the Item
- `collection`: The collection of the Item
- Dates
  - `date`: The date portion of the Item's `datetime` field
  - `year-month`: The year and month of the Item's `datetime` field
  - `year`: The year of the Item's `datetime` field
- Any property

The detailed usage examples below are shown using a saved file, however `stacterm` can also read in stdin allowing other programs to pipe output to it, such as [pystac-client](https://github.com/stac-utils/pystac-client).

```
$ export STAC_API_URL=https://earth-search.aws.element84.com/v0
$ stac-client search --intersects aoi.json --datetime 2020-07-01/2020-12-31 -c sentinel-s2-l2a-cogs landsat-8-l1-c1 | stacterm cal --label platform
```

![](images/cal.png)


### Tables

Use `stacterm` to display tabularized data from a saved ItemCollection.

```
$ stacterm table items.json

| id                                       | date       |
|------------------------------------------|------------|
| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |
| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |
| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |
```

By default this is a markdown table (note the terminal will not render Markdown)

| id                                       | date       |
|------------------------------------------|------------|
| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |
| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |
| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |

The fields displayed can be changed via the `--fields` keyword, and sorted via the `--sort` keyword.

```
$ stacterm table items.json --fields date eo:cloud_cover collection --sort eo:cloud_cover

| date       | eo:cloud_cover | collection           |
|------------|----------------|----------------------|
| 2020-10-13 | 0.0            | sentinel-s2-l1c      |
| 2020-10-13 | 0.0            | sentinel-s2-l2a      |
| 2020-10-13 | 0.0            | sentinel-s2-l2a-cogs |
| 2020-10-13 | 0.0            | sentinel-s2-l1c      |
```

The style of the table can also be changed via the `--style` keyword, although it will no longer be usable in a Markdown renderer. See [termtables styles](https://github.com/nschloe/termtables/blob/master/termtables/styles.py) for list of styles.

```
$ stacterm table items.json --fields id date platform sentinel:grid_square --sort date --style thick

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ id                                       ┃ date       ┃ platform    ┃ sentinel:grid_square ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫
┃ S2B_12JXR_20201003_0_L2A                 ┃ 2020-10-03 ┃ sentinel-2b ┃ XR                   ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫
┃ S2B_12JXQ_20201003_0_L1C                 ┃ 2020-10-03 ┃ sentinel-2b ┃ XQ                   ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫
┃ S2B_12JXQ_20201003_0_L2A                 ┃ 2020-10-03 ┃ sentinel-2b ┃ XQ                   ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━┛
```

### Calendars

A UNIX-like calendar (see [`cal`](https://en.wikipedia.org/wiki/Cal_(Unix))) is available to show dates of individual items. By default `cal` will use the field `datetime` (the collection datetime) and group Items by their Collection. These can be overridden by the `--date_field` and `--label_field` keywords. Note that the specified `--date_field` needs to be a date field, such as `created` or `updated`.  `--label_field` will group and label items by the provided field.

```
$ stacterm cal items.json --date_field created --label_field gsd
```

![](images/cal2.png)

### Histograms

Histograms can be created for any numeric field and `datetime` and `date` (just the date portion of `datetime`). `created` and `updated` may also be specified if available in all Items.

```
$ stacterm hist items.json eo:cloud_cover
```

![](images/hist.png)

### Plots

Plots can be created with a single numeric fields, a date field (`datetime`, `date`, `created`, or `updated`) and a numeric field, or two numeric fields. If a single field it will be plotted against the scene number. The `--sort` keyword can control how to sort the data if plotting a single field.

```
$ stacterm plot items.json eo:cloud_cover --sort eo:cloud_cover
```

![](images/plot.png)


## Markers and Colors

For histograms and plots there are options for changing the marker (symbol) and color of the plot, background, and text. These options all come directly from [plotext](https://github.com/piccolomo/plotext).

In addition to a marker being able to be any single character, the following names can also be provided for these symbols:

![](https://raw.githubusercontent.com/piccolomo/plotext/master/images/markers.png)

Color names can be provided as follows:

![](https://raw.githubusercontent.com/piccolomo/plotext/master/images/colors.png)


## Limitations

Currently any provided field must exist in all STAC Items.


## Development

There are a lot more options in the [plotext library](https://github.com/piccolomo/plotext) that could be surfaced here. Additionally, if [support for datetimes](https://github.com/piccolomo/plotext/issues/7) in histograms and plots is added, `stacterm` could create temporal histograms, or plot quantities vs date.
