Metadata-Version: 2.1
Name: criticalmaas.ta1-geopackage
Version: 0.1.0
Summary: GeoPackage schema for validating and storing vector geologic map data produced by computer-vision pipelines
License: MIT
Author: Daven Quinn
Author-email: code@davenquinn.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: fiona (>=1.9.5,<2.0.0)
Requires-Dist: geopandas (>=0.14.1,<0.15.0)
Requires-Dist: macrostrat-utils (>=1.2.0,<2.0.0)
Requires-Dist: macrostrat.database (>=3.0.0,<4.0.0)
Description-Content-Type: text/markdown

# TA1 GeoPackage library

This repository contains the schema definitions and
a reference Python library for manipulating a GeoPackage-based data transfer format for CriticalMAAS TA1, based on
the [TA1 output
schemas](https://github.com/DARPA-CRITICALMAAS/schemas/tree/main/ta10).  It was
created by the [Macrostrat TA4
team](https://github.com/UW-Macrostrat/criticalmaas) and will be maintained
jointly by TA1 and TA4 as the schema is updated.

## Installation

This Package can be installed directly from GitHub:

```bash
# PIP installation
pip install git+https://github.com/DARPA-CRITICALMAAS/ta1-geopackage.git
# Poetry
poetry add git+https://github.com/DARPA-CRITICALMAAS/ta1-geopackage.git
# etc. for other package managers
```
If you are not using Python, you can load the schema directly from
the [`criticalmaas/ta1_geopackage/fixtures`](criticalmaas/ta1_geopackage/fixtures) directory,
and use other tools such as `ogr2ogr` to load data into the database.

## Examples

Example maps (output from [Macrostrat's CLI writer][macrostrat_writer]):

- [`bc_kananaskis.gpkg`](https://storage.macrostrat.org/web-assets/criticalmaas/example-files/ta1-geopackage/bc_kananaskis.gpkg): [Kananaskis Lakes, BC/AB](https://v2.macrostrat.org/maps/234), 1.5 MB
- [`grandcanyon.gpkg`](https://storage.macrostrat.org/web-assets/criticalmaas/example-files/ta1-geopackage/grandcanyon.gpkg): [Grand Canyon, AZ](https://v2.macrostrat.org/maps/34), 11.7 MB

At the moment, these only show final feature datasets (e.g. `polygon_feature`) for digital-native maps. Examples of
TA1 output for raster-based maps will be added soon.

## Usage

Basic usage is as follows:

```python

from criticalmaas.ta1_geopackage import GeopackageDatabase

db = GeopackageDatabase(
  "my_map.gpkg",
  crs="EPSG:4326" # Geographic coordinates (default)
  # crs="CRITICALMAAS:pixel" # Pixel coordinates
)

# Insert types (required for foreign key constraints)
db.write_models([
  db.model.map(id="test", name="test", description="test"),
  db.model.polygon_type(id="test", name="test", description="test"),
])

# Write features
feat = {
    "properties": {
        "id": "test",
        "map_id": "test",
        "type": "test",
        "confidence": None,
        "provenance": None,
    },
    "geometry": {
        "type": "MultiPolygon",
        "coordinates": [[[(0.0, 0.0), (0.0, 1.0), (1.0, 1.0), (1.0, 0.0), (0.0, 0.0)]]],
    },
}
db.write_features("polygon_feature", [feat])
```

See the [tests][tests] and the [Macrostrat CLI writer][macrostrat_writer] for more examples.

## Schema

![Schema diagram](diagram/schema-diagram.png)

## Ongoing work

- [x] Tests with geographic data
- [x] Helpers for working with multiple projections
- [x] Example datasets
- [x] Example script for dumping a Macrostrat map
- [x] Schema adjustments and improvements (see [tracking issue][change-tracking-issue])
- [ ] Create example of writing `page_extraction`s with pixel coordinates
- [ ] Make the package available as `criticalmass.ta1_geopackage` on PyPI.

## Resources

- [GeoPackage](https://www.geopackage.org/)
- [OGC GeoPackage spec](https://www.geopackage.org/spec120/)
- [Switch from Shapefile](http://switchfromshapefile.org/)

## Prior art

- [Fiona](https://fiona.readthedocs.io/en/stable/): A python library for working with geospatial vector data.
- [GeoPandas](https://geopandas.org/): A python library for working with geospatial vector data.
- [GeoAlchemy 2](https://geoalchemy-2.readthedocs.io/en/latest/): A python library for interfacing in PostGIS, Spatialite, and GeoPackage.
- [Fudgeo](https://github.com/realiii/fudgeo): modern Python package for working with GeoPackages. Duplicates many features of more common
  packages like `fiona` and `geopandas` but provides low-level access to the GeoPackage spec.

[macrostrat_writer]: https://github.com/UW-Macrostrat/macrostrat/blob/main/macrostrat-cli/macrostrat_cli/io/criticalmaas/__init__.py
[tests]: criticalmaas/ta1_geopackage/test_create_geopackage.py
[change-tracking-issue]: https://github.com/DARPA-CRITICALMAAS/ta1-geopackage/issues/3
