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
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.
Quick start
Turn a GeoParquet or GeoJSON file into a running tile server in two commands:
# 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)
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
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
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
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
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
processexecutor parallelizes reading. For small files (<10 MB) add--geojson-executor threadto skip process-pool startup overhead. - Geometry column not named
geometry(common with OGR/pyogrioexports)? Pass--geom-col wkb_geometry. - Serving tiles on the fly (zooming past the pre-generated levels)? Build
with
--covering-bboxso the server can prune row groups at read time. - One-file distribution:
starlet build --pmtileswrites a singledatasets/mydata.pmtilesarchive alongside the dataset.
Deploying a server
See 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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file starlet-0.3.1.tar.gz.
File metadata
- Download URL: starlet-0.3.1.tar.gz
- Upload date:
- Size: 87.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ae17f0c82c35afdc36bb176099f44311a7d8fef1e9b714b8a992a4d1f0ca33fc
|
|
| MD5 |
ec62ff3ab89b99f5a694c0401338062b
|
|
| BLAKE2b-256 |
641d1904a72a3acc6c75b1789a993532f74045a0abf124c1fdaca95bfad1ca51
|
Provenance
The following attestation bundles were made for starlet-0.3.1.tar.gz:
Publisher:
publish.yml on ucr-bdlab/starlet
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
starlet-0.3.1.tar.gz -
Subject digest:
ae17f0c82c35afdc36bb176099f44311a7d8fef1e9b714b8a992a4d1f0ca33fc - Sigstore transparency entry: 2108061512
- Sigstore integration time:
-
Permalink:
ucr-bdlab/starlet@6de012065cacee7d1916e1a00e088306285e9119 -
Branch / Tag:
refs/tags/v0.3.1 - Owner: https://github.com/ucr-bdlab
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@6de012065cacee7d1916e1a00e088306285e9119 -
Trigger Event:
push
-
Statement type:
File details
Details for the file starlet-0.3.1-py3-none-any.whl.
File metadata
- Download URL: starlet-0.3.1-py3-none-any.whl
- Upload date:
- Size: 104.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dc941e07e9b25029479624a8d22f06da58932e5df8e9d81475c04f4178f99022
|
|
| MD5 |
135cc409717b0351f1b2c4220a2f09ff
|
|
| BLAKE2b-256 |
0a6d171e46495f595e3a4f990789bd2c9c8e1882d11676e28fed76e40176d846
|
Provenance
The following attestation bundles were made for starlet-0.3.1-py3-none-any.whl:
Publisher:
publish.yml on ucr-bdlab/starlet
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
starlet-0.3.1-py3-none-any.whl -
Subject digest:
dc941e07e9b25029479624a8d22f06da58932e5df8e9d81475c04f4178f99022 - Sigstore transparency entry: 2108061645
- Sigstore integration time:
-
Permalink:
ucr-bdlab/starlet@6de012065cacee7d1916e1a00e088306285e9119 -
Branch / Tag:
refs/tags/v0.3.1 - Owner: https://github.com/ucr-bdlab
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@6de012065cacee7d1916e1a00e088306285e9119 -
Trigger Event:
push
-
Statement type:
