Metadata-Version: 2.4
Name: starlet
Version: 0.3.1
Summary: Spatial tiling, MVT generation, and tile serving for geospatial data
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyarrow>=15
Requires-Dist: pandas>=2
Requires-Dist: numpy>=1.24
Requires-Dist: shapely>=2.0
Requires-Dist: click>=8
Requires-Dist: ijson>=3.3
Requires-Dist: mapbox-vector-tile>=2
Requires-Dist: pyproj>=3
Requires-Dist: flask>=3
Requires-Dist: flask-cors
Requires-Dist: geopandas>=0.14
Requires-Dist: gunicorn
Requires-Dist: datasketch
Requires-Dist: pmtiles>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"

# Starlet

Spatial tiling, Mapbox Vector Tile (MVT) generation, and on-demand tile serving
for large geospatial datasets (GeoParquet / GeoJSON).

The pipeline is: **partition a dataset into spatial tiles → build density
histograms → (optionally) pre-generate MVTs → serve them over HTTP.**

## Install

```bash
pip install starlet
```

Requires Python 3.10+. This installs the `starlet` command-line tool.

> Want to work on Starlet itself (run from a clone, run the tests)? See
> [DEVELOPMENT.md](DEVELOPMENT.md).

## Quick start

Turn a GeoParquet or GeoJSON file into a running tile server in two commands:

```bash
# 1. Build a dataset: partition into tiles + pre-generate vector tiles
starlet build --input data.parquet --outdir datasets/mydata

# 2. Serve it
starlet serve --dir datasets --port 8765
```

Then open <http://localhost:8765> and pick your dataset to explore it on a map.

## Commands

Everything is available through the `starlet` CLI (`starlet --help`).

### `starlet build` — full pipeline (tile + MVT)

```bash
starlet build --input data.parquet --outdir datasets/mydata --zoom 8
```

| Flag | Default | Description |
|------|---------|-------------|
| `--input` | (required) | Path to a GeoParquet or GeoJSON file |
| `--outdir` | (required) | Output dataset directory |
| `--zoom` | 7 | Maximum MVT zoom level |
| `--partition-size` | 512mb (GeoJSON) / 128mb (GeoParquet) | Target partition size, e.g. `256mb`, `1gb` |
| `--threshold` | 100000 | Minimum feature count per MVT tile |
| `--pmtiles` | off | Also export a single `.pmtiles` archive |

### `starlet tile` — partition a dataset only

```bash
starlet tile --input data.parquet --outdir datasets/mydata
```

| Flag | Default | Description |
|------|---------|-------------|
| `--input` | (required) | Path to a GeoParquet or GeoJSON file |
| `--outdir` | (required) | Output dataset directory |
| `--partition-size` | 512mb (GeoJSON) / 128mb (GeoParquet) | Target partition size; the number of tiles is derived from the input size |
| `--sort` | zorder | Within-tile row order: `zorder`, `hilbert`, `columns`, `none` |
| `--orchestrator` | two-stage | Tiling engine: `two-stage` (fast, map-reduce) or `round` |
| `--geojson-executor` | process | `process` for large files, `thread` for small GeoJSON |
| `--covering-bbox` | off | Write per-row bbox columns for faster on-demand serving |
| `--geom-col` | geometry | Geometry column name (e.g. `wkb_geometry` for OGR exports) |
| `--compression` | zstd | Parquet compression codec |

### `starlet mvt` — generate vector tiles from a tiled dataset

```bash
starlet mvt --dir datasets/mydata --zoom 7 --threshold 100000
```

| Flag | Default | Description |
|------|---------|-------------|
| `--dir` | (required) | Dataset directory (contains `parquet_tiles/` and `histograms/`) |
| `--zoom` | 7 | Maximum zoom level |
| `--threshold` | 0 | Minimum feature count per tile |
| `--outdir` | `<dir>/mvt/` | MVT output directory |

### `starlet serve` — launch the tile server

```bash
starlet serve --dir datasets --port 8765
```

| Flag | Default | Description |
|------|---------|-------------|
| `--dir` | (required) | Root directory containing dataset subdirectories |
| `--host` | 0.0.0.0 | Host to bind |
| `--port` | 8765 | Port to bind |
| `--cache-size` | 256 | In-memory tile cache size |

### `starlet info` — inspect a dataset

```bash
starlet info --dir datasets/mydata
```

## Server API

Once `starlet serve` is running:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/` | Interactive dataset selector |
| `GET` | `/api/datasets` | List all datasets |
| `GET` | `/datasets/<dataset>.json` | Dataset metadata |
| `GET` | `/<dataset>/<z>/<x>/<y>.mvt` | Mapbox Vector Tile |
| `GET`/`POST` | `/datasets/<dataset>/features.<csv\|geojson>` | Download features (optional geometry filter) |
| `GET` | `/api/datasets/<dataset>/stats` | Attribute statistics |

## Notes & tips

- **Big GeoJSON?** The default `process` executor parallelizes reading. For
  small files (<10 MB) add `--geojson-executor thread` to skip process-pool
  startup overhead.
- **Geometry column** not named `geometry` (common with OGR/`pyogrio`
  exports)? Pass `--geom-col wkb_geometry`.
- **Serving tiles on the fly** (zooming past the pre-generated levels)? Build
  with `--covering-bbox` so the server can prune row groups at read time.
- **One-file distribution:** `starlet build --pmtiles` writes a single
  `datasets/mydata.pmtiles` archive alongside the dataset.

## Deploying a server

See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for a step-by-step guide to standing
up a production tile server, including a no-root recipe behind an existing
Apache install.

## License

See the repository for license details.
