{"id":13735387,"url":"https://github.com/stac-utils/stac-terminal","last_synced_at":"2025-06-23T17:12:20.908Z","repository":{"id":46321677,"uuid":"356764278","full_name":"stac-utils/stac-terminal","owner":"stac-utils","description":"Output info on STAC Items in the terminal","archived":false,"fork":false,"pushed_at":"2023-10-31T22:46:25.000Z","size":160,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-25T08:00:31.240Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stac-utils.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-04-11T04:15:34.000Z","updated_at":"2024-02-06T07:47:39.000Z","dependencies_parsed_at":"2023-12-18T20:50:20.822Z","dependency_job_id":null,"html_url":"https://github.com/stac-utils/stac-terminal","commit_stats":{"total_commits":46,"total_committers":2,"mean_commits":23.0,"dds":"0.13043478260869568","last_synced_commit":"48d48a7c84240ea08eece13dc9a8aadcf80e039e"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stac-utils","download_url":"https://codeload.github.com/stac-utils/stac-terminal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224727181,"owners_count":17359532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T03:01:06.323Z","updated_at":"2024-11-15T03:31:50.582Z","avatar_url":"https://github.com/stac-utils.png","language":"Python","readme":"# stacterm\n\nThis library is for displaying information (tables, calendars, plots,\nhistograms) about [STAC](https://stacspec.org/) Items in the terminal. It takes\nas input a STAC ItemCollection (a GeoJSON FeatureCollection of STAC Items),\neither by specifying a filename or by piping output from another program.\n\n## Installation\n\nInstall from PyPi:\n\n```cmdline\n❯ pip install stacterm\n```\n\nPySTAC and Pandas are required, along with two dependencies for rendering\ntables ([termtables](https://pypi.org/project/termtables/)) and plots\n([plotext](https://pypi.org/project/plotext/)) in the terminal.\n\n## Usage\n\nstacterm main usage is as a CLI progam `stacterm`. Use help to see options\navailable:\n\n```cmdline\n❯ stacterm -h\nusage: stacterm [-h] {table,cal,hist,plot} ...\n\nTerminal STAC\n\npositional arguments:\n  {table,cal,hist,plot}\n    table               Output a table\n    cal                 Output a calendar\n    hist                Output a histogram\n    plot                Output a plot\n\noptional arguments:\n  -h, --help            show this help message and exit\n```\n\nAll of the sub-commands in `stacterm` can take optional field names. A field\nname is:\n\n- `id`: The ID of the Item\n- `collection`: The collection of the Item\n- Dates\n  - `date`: The date portion of the Item's `datetime` field\n  - `year-month`: The year and month of the Item's `datetime` field\n  - `year`: The year of the Item's `datetime` field\n- Any property\n\n`stacterm` reads from in stdin allowing other programs to pipe output to it,\nsuch as [pystac-client](https://github.com/stac-utils/pystac-client).\n\n```cmdline\n❯ export STAC_API_URL=https://earth-search.aws.element84.com/v0\n❯ stac-client search --intersects aoi.json \\\n    --datetime 2020-07-01/2020-12-31 \\\n    -c sentinel-s2-l2a-cogs landsat-8-l1-c1 | stacterm cal --label platform\n```\n\nThe detailed usage examples below are all shown using the item collection from\na search saved to a file and redirected to stdin.\n\n![](images/cal.png)\n\n### Tables\n\nUse `stacterm` to display tabularized data from a saved ItemCollection.\n\n```cmdline\n❯ \u003cinput.json stacterm table\n\n| id                                       | date       |\n|------------------------------------------|------------|\n| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |\n| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |\n| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |\n```\n\nBy default this is a markdown table (note the terminal will not render Markdown)\n\n| id                                       | date       |\n|------------------------------------------|------------|\n| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |\n| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |\n| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |\n\nThe fields displayed can be changed via the `--fields` keyword, and sorted via\nthe `--sort` keyword.\n\n```cmdline\n❯ \u003cinput.json stacterm table \\\n    --fields date eo:cloud_cover collection \\\n    --sort eo:cloud_cover\n\n| date       | eo:cloud_cover | collection           |\n|------------|----------------|----------------------|\n| 2020-10-13 | 0.0            | sentinel-s2-l1c      |\n| 2020-10-13 | 0.0            | sentinel-s2-l2a      |\n| 2020-10-13 | 0.0            | sentinel-s2-l2a-cogs |\n| 2020-10-13 | 0.0            | sentinel-s2-l1c      |\n```\n\nThe style of the table can also be changed via the `--style` keyword, although\nit will no longer be usable in a Markdown renderer. See [termtables\nstyles](https://github.com/nschloe/termtables/blob/master/termtables/styles.py)\nfor list of styles.\n\n```cmdline\n❯ \u003cinput.json stacterm table \\\n    --fields id date platform sentinel:grid_square\\\n    --sort date \\\n    --style thick\n\n┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓\n┃ id                        ┃ date       ┃ platform    ┃ sentinel:grid_square ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫\n┃ S2B_12JXR_20201003_0_L2A  ┃ 2020-10-03 ┃ sentinel-2b ┃ XR                   ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫\n┃ S2B_12JXQ_20201003_0_L1C  ┃ 2020-10-03 ┃ sentinel-2b ┃ XQ                   ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫\n┃ S2B_12JXQ_20201003_0_L2A  ┃ 2020-10-03 ┃ sentinel-2b ┃ XQ                   ┃\n┗━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━┛\n```\n\n### Calendars\n\nA UNIX-like calendar (see [`cal`](https://en.wikipedia.org/wiki/Cal_(Unix))) is\navailable to show dates of individual items. By default `cal` will use the\nfield `datetime` (the collection datetime) and group Items by their Collection.\nThese can be overridden by the `--date_field` and `--label_field` keywords.\nNote that the specified `--date_field` needs to be a date field, such as\n`created` or `updated`.  `--label_field` will group and label items by the\nprovided field.\n\n```cmdline\n❯ \u003cinput.json stacterm cal --date_field created --label_field gsd\n```\n\n![](images/cal2.png)\n\n### Histograms\n\nHistograms can be created for any numeric field and `datetime` and `date` (just\nthe date portion of `datetime`). `created` and `updated` may also be specified\nif available in all Items.\n\n```cmdline\n❯ \u003citems.json stacterm hist eo:cloud_cover\n```\n\n![](images/hist.png)\n\n### Plots\n\nPlots can be created with a single numeric fields, a date field (`datetime`,\n`date`, `created`, or `updated`) and a numeric field, or two numeric fields. If\na single field it will be plotted against the scene number. The `--sort`\nkeyword can control how to sort the data if plotting a single field.\n\n```cmdline\n❯ \u003cinput.json stacterm plot eo:cloud_cover --sort eo:cloud_cover\n```\n\n![](images/plot.png)\n\n## Markers and Colors\n\nFor histograms and plots there are options for changing the marker (symbol) and\ncolor of the plot, background, and text. These options all come directly from\n[plotext](https://github.com/piccolomo/plotext).\n\nIn addition to a marker being able to be any single character, the following\nnames can also be provided for these symbols:\n\n![](https://raw.githubusercontent.com/piccolomo/plotext/master/images/markers.png)\n\nColor names can be provided as follows:\n\n![](https://raw.githubusercontent.com/piccolomo/plotext/master/images/colors.png)\n\n## Limitations\n\nCurrently any provided field must exist in all STAC Items.\n\n## Development\n\nThere are a lot more options in the [plotext\nlibrary](https://github.com/piccolomo/plotext) that could be surfaced here.\nAdditionally, if [support for\ndatetimes](https://github.com/piccolomo/plotext/issues/7) in histograms and\nplots is added, `stacterm` could create temporal histograms, or plot quantities\nvs date.\n","funding_links":[],"categories":["`Python` processing of optical imagery (non deep learning)"],"sub_categories":["Cloud Native Geospatial"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstac-utils%2Fstac-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-terminal/lists"}