Metadata-Version: 2.5
Name: pixelworld-pipeline
Version: 0.1.0
Summary: Offline geo pipeline for Pixelworld: real data -> gridded world packages.
Project-URL: Homepage, https://github.com/alexngai/pixelworld
Project-URL: Documentation, https://github.com/alexngai/pixelworld/blob/main/docs/worlds.md
Project-URL: Repository, https://github.com/alexngai/pixelworld
Project-URL: Issues, https://github.com/alexngai/pixelworld/issues
Author: The pixelworld contributors
License-Expression: MIT OR Apache-2.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Keywords: dem,gis,isometric,openstreetmap,overture-maps,pixel-art,procedural,world-generator
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.12
Requires-Dist: certifi>=2024.2.2
Requires-Dist: laspy>=2.7.0
Requires-Dist: lazrs>=0.8.2
Requires-Dist: numpy>=2.0
Requires-Dist: pyarrow>=26.0.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rasterio>=1.4
Requires-Dist: scipy>=1.18.1
Requires-Dist: shapely>=2.2.0
Description-Content-Type: text/markdown

# pixelworld-pipeline

The offline geo pipeline of [pixelworld](https://github.com/alexngai/pixelworld): real elevation, land cover, roads and buildings in, gridded world packages out. A region spec (YAML) says where, at what scale and with what data; `pixelworld build` turns it into a package the viewer (the npm package `pixelworld`) draws.

```sh
pip install pixelworld-pipeline        # or: uv tool install pixelworld-pipeline
pixelworld build region.yaml --out my-world
```

In a checkout of the repository, from `pipeline/`:

```sh
uv sync                                                    # once
uv run pixelworld check ../worlds/jerome/region.yaml       # validate a spec, offline
uv run pixelworld build ../worlds/jerome/region.yaml --out ../fixtures/_try/jerome
uv run pixelworld view ../fixtures/_try/jerome             # serve a package, print the viewer URL
uv run pixelworld --help                                   # every command, the exit codes
```

- **Making a world of your own place:** [docs/worlds.md](https://github.com/alexngai/pixelworld/blob/main/docs/worlds.md), a walkthrough with Jerome, Arizona as the example, and the reference of every spec key (`pixelworld reference` prints it).
- **How the pipeline works:** [docs/architecture.md](https://github.com/alexngai/pixelworld/blob/main/docs/architecture.md) §4–6: the spec, the stages, the warp.
- **The package it writes:** [docs/world-format.md](https://github.com/alexngai/pixelworld/blob/main/docs/world-format.md).
- **Data sources** (terrain, land cover, the map, building facts and the rest, built in or your own) and the Python API (`pixelworld_pipeline.build(spec)`): [docs/plugins.md](https://github.com/alexngai/pixelworld/blob/main/docs/plugins.md).
- **Data and licences:** [docs/data-sources.md](https://github.com/alexngai/pixelworld/blob/main/docs/data-sources.md).

**Exit codes:** 0 done; 1 the package was written but its road report found problems; 2 the spec or command line is invalid; 3 the build failed (a download, or a bug) and the output was left as it was.

**Downloads** are cached in `pipeline/.cache/`, or in `$PIXELWORLD_CACHE`, which several checkouts can share.

**Development:** `uv run pytest` (offline), `uv run ruff check . && uv run ruff format --check .`. The spec schema is [`src/pixelworld_pipeline/schema.py`](https://github.com/alexngai/pixelworld/blob/main/pipeline/src/pixelworld_pipeline/schema.py); after changing it, `uv run pixelworld reference --write ../docs/worlds.md` (a test checks the two agree).
