Metadata-Version: 2.4
Name: scse-spatial
Version: 1.0.0
Summary: A registry enabling the indexing and querying of spatial data resources on other services.
Author: Max Wolschlager
Author-email: rxtx@ungut.at
Requires-Python: >=3.11,<3.15
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: alembic (>=1.12.0,<2.0.0)
Requires-Dist: dask (>=2024.0.0)
Requires-Dist: geoalchemy2 (>=0.20.0,<0.21.0)
Requires-Dist: geopandas (>=1.0,<2.0)
Requires-Dist: jsonschema (>=4.26.0,<5.0.0)
Requires-Dist: litestar (>=2.0.0,<3.0.0)
Requires-Dist: mapbox-vector-tile (>=2,<3)
Requires-Dist: morecantile (>=7.0.3,<8.0)
Requires-Dist: netcdf4 (>=1.7.3,<2.0.0)
Requires-Dist: pmtiles (>=3.7,<4)
Requires-Dist: psycopg[binary] (>=3.1.12,<4.0.0)
Requires-Dist: pydantic (>=2.4.2,<3.0.0)
Requires-Dist: pydantic-settings (>=2.0.3,<3.0.0)
Requires-Dist: pyproj (>=3.1,<4.0)
Requires-Dist: pystac[validation] (>=1.12,<1.13)
Requires-Dist: rasterio (>=1.4.3,<2.0.0)
Requires-Dist: rich (>=13.9.4,<14.0.0)
Requires-Dist: rioxarray (>=0.19,<1.0)
Requires-Dist: s3fs (>=2024.10.0,<2027.0.0)
Requires-Dist: scse-toolkit (>=2,<3)
Requires-Dist: sqlalchemy (>=2.0.21,<3)
Requires-Dist: tippecanoe (>=2.45)
Requires-Dist: titiler-core (>=2.0,<3.0)
Requires-Dist: titiler-xarray[fs] (>=2.0,<3.0)
Requires-Dist: typer (>=0.24.1,<0.25.0)
Requires-Dist: uvicorn (>=0.52.1,<0.53.0)
Requires-Dist: xarray (>=2025.1.0,<2026)
Requires-Dist: xxhash (>=3.4.1,<4.0.0)
Requires-Dist: zarr (>=3.0.0,<4.0)
Description-Content-Type: text/markdown

# scse-spatial

A registry that indexes and queries spatial data resources on other services.

## Overview

scse-spatial is the spatial data extension to a scenario services web
application stack. It turns geodata files into fast, web-optimized resources
and serves them to any map app.

A workflow loads data. A web app reads it. This repository provides both
sides: the ingest path and the HTTP API.

### Feeding it

Workflows push data in with the CLI or a few lines of Python. The `Spatial`
object connects to a PostGIS database and to object storage. It exposes
services for rasters, features, and a STAC catalog.

```python
with Spatial("<platform>", settings=Settings()) as spatial:
    spatial.rasters.sync_hierarchy(
        "emissions",
        [path],
        parameters_class=EmissionParameters,
        metadata_class=EmissionMetadata,
        extract_meta=extract_em_meta,
    )
    spatial.stac.export_catalog()
```

The platform converts each source file into optimized formats, uploads them,
and indexes them. A re-run skips files whose content did not change.

Workflows live in their own repositories. See `WORKFLOWS.md` for more information.

### Connecting to a platform

In multi-tenant deployments the connection details come from the manager
API. Staff log in with their user account once; the credentials are cached
locally and used in place of the shared service secret.

```bash
spatial login          # prompts for username and password, caches them
spatial whoami         # show the identity the CLI would use
spatial platforms      # list the platforms you can access
```

The manager DSN's secret material stays in the local environment through
`{env:...}` placeholders. Imports are attributed to the logged-in user.

### HTTP API

Web apps can read data over HTTP. A Litestar server lists hierarchies and
layers, renders map tiles through TiTiler, and streams vector tiles and
GeoJSON from object storage.

```bash
curl -X PATCH http://<scse-spatial>/v1/{platform}/rasters/ \
     -H "Content-Type: application/json" \
     -d '{"hierarchy_id": 3, "parameters__contains": {"sector": "power"}}'
```

Point an scse-app at the `/v1` or `/titiler` endpoints, or open `/docs` and
`/titiler/docs` for interactive API docs. See `HTTP_API.md` for more information.

## Development Setup

```bash
# Install Poetry, minimum version >=1.2 required
pipx install poetry

# You may have to reinitialize your shell at this point.
source ~/.bashrc

# Activate in-project virtualenvs
poetry config virtualenvs.in-project true

# Add dynamic versioning plugin
poetry self add "poetry-dynamic-versioning[plugin]"

# Install dependencies
# (using "--with dev" if dev dependencies should be installed as well)
poetry install --with dev

# Activate virtual environment
poetry shell

# Copy the template environment configuration
cp template.env .env

```

