set up STAC metadata

.github/workflows/continuous-integration.yml

@@ -53,6 +53,6 @@ jobs:
       - name: Update Conda's environemnt
         run: conda env update -f environment.yml -n test
       - name: Install package
-        run: uv sync
+        run: uv sync --all-extras
       - name: Execute linters and test suites
         run: uv run ./scripts/test

CHANGELOG.md

@@ -9,9 +9,11 @@ number as needed.
 
 ## [Unreleased]
 
+## [0.1.0]
+
 ### Added
 
-- Nothing.
+- Initial attempt at representing Overture Maps data in STAC!
 
 ### Deprecated
 
@@ -25,4 +27,5 @@ number as needed.
 
 - Nothing.
 
+[0.1.0]: <https://github.com/stactools-packages/overture-maps/tree/v0.1.0/>
 [Unreleased]: <https://github.com/stactools-packages/overture-maps/tree/main/>

LICENSE

@@ -1,6 +1,6 @@
 This software is licensed under the Apache 2 license, quoted below.
 
-Copyright 2022 COMPANY [COMPANY WEBPAGE URL]
+Copyright 2022 Development Seed [https://developmentseed.org]
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not
 use this file except in compliance with the License. You may obtain a copy of

README.md

@@ -1,23 +1,97 @@
-# stactools-template
-
-This is a template repo used for creating new packages for `stactools`.
-
-## How to use
-
-1. Clone this template repository as your package name, e.g. `landsat`.
-   This name should be short, memorable, and a valid Python package name (i.e.
-   it shouldn't start with a number, etc). It can, however, include a hyphen, in
-   which case the name for Python imports will be the underscored version, e.g.
-   `landsat-8` goes to `stactools.landsat_8`.  Your name will be used on PyPI to
-   publish the package in the stactools namespace, e.g. `stactools-landsat`.
-2. Change into the top-level directory of your package and run `scripts/rename`.
-   This will update _most_ of the files in the repository with your new package name.
-3. Update `pyproject.toml` with your package description and such.
-4. Install with the development requirements (`uv sync`).
-5. Update the LICENSE with your company's information (or whomever holds the copyright).
-6. Edit or replace the existing functions to create stac Items and Collections
-   for your dataset.
-7. Add example Items (and Collections and Catalogs, if included) to an
-   `examples/` directory.
-8. Delete this file, and rename `README-template.md` to `README.md`. Update your
-   new README to provide information about how to use your package.
+# stactools-overture-maps
+
+[![PyPI](https://img.shields.io/pypi/v/stactools-overture-maps?style=for-the-badge)](https://pypi.org/project/stactools-overture-maps/)
+![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/stactools-packages/overture-maps/continuous-integration.yml?style=for-the-badge)
+
+- Name: overture-maps
+- Package: `stactools.overture_maps`
+- [stactools-overture-maps on PyPI](https://pypi.org/project/stactools-overture-maps/)
+- Owner: @hrodmn
+- [Dataset homepage](https://docs.overturemaps.org/)
+- STAC extensions used:
+  - [table](https://github.com/stac-extensions/table/)
+  - [version](https://github.com/stac-extensions/version/)
+  - [item-assets](https://github.com/stac-extensions/item-assets/)
+- Extra fields:
+  - `overture:theme`: Overture Maps theme
+  - `overture:type`: Overture Maps feature type
+- [Browse the example in human-readable form](https://radiantearth.github.io/stac-browser/#/external/raw.githubusercontent.com/stactools-packages/overture-maps/main/examples/catalog.json)
+- [Browse a notebook demonstrating the example item and collection](https://github.com/stactools-packages/overture-maps/tree/main/docs/example.ipynb)
+
+This package can be used to generate STAC metadata for the Overture Maps dataset.
+Collections are separated by the Overture 'Themes': Addresses, Base, Buildings, Divisions, Places, and Transportation.
+
+Items represent individual parquet files in object storage and each one will correspond to a single partition for a theme (`overture:theme`), feature type (`overture:type:`), and release (`version`).
+
+Ideally we would include some collection-level assets for the entire `theme/type` table connections, but that will come in a later version of this package.
+
+## STAC examples
+
+- [Collection](examples/collection.json)
+- [Item](examples/item/item.json)
+
+## Installation
+
+You will want to install either the `azure` or `aws` extras depending on which storage backend you intende to reference:
+
+```shell
+pip install stactools-overture-maps[azure]
+```
+
+or
+
+```shell
+pip install stactools-overture-maps[aws]
+```
+
+## Command-line usage
+
+You can create a collection with the theme, storage backend (`azure` or `aws`), and latest release version:
+
+```bash
+stac overturemaps create-collection \
+  buildings \
+  azure \
+  2024-12-18.0 \
+  collection.json
+```
+
+You can create an item with just the `href` for the parquet asset:
+
+```bash
+stac overturemaps create-item \
+  https://overturemapswestus2.blob.core.windows.net/release/2024-12-18.0/theme=addresses/type=address/part-00000-de803747-d78d-4060-b3da-da6dcd5dbab8-c000.zstd.parquet \
+  item.json
+```
+
+After generating item metadata for a new release, you should update the collection metadata to capture the new temporal extent.
+
+Use `stac overture-maps --help` to see all subcommands and options.
+
+## Contributing
+
+We use [pre-commit](https://pre-commit.com/) to check any changes.
+To set up your development environment:
+
+```shell
+uv sync --all-extras
+uv run pre-commit install
+```
+
+To check all files:
+
+```shell
+uv run pre-commit run --all-files
+```
+
+To run the tests:
+
+```shell
+uv run pytest -vv
+```
+
+If you've updated the STAC metadata output, update the examples:
+
+```shell
+uv run scripts/update-examples
+```