Metadata-Version: 2.4
Name: prettyplateau
Version: 0.1.0
Summary: Print-quality city visualizations from Project PLATEAU data.
Project-URL: Homepage, https://github.com/pixelx-jp/prettyplateau
Project-URL: Documentation, https://github.com/pixelx-jp/prettyplateau#readme
Project-URL: Issues, https://github.com/pixelx-jp/prettyplateau/issues
Project-URL: Source code, https://github.com/pixelx-jp/prettyplateau
Project-URL: Organization, https://yodolabs.jp
Author-email: "Yodo Labs (PixelX Inc.)" <pan@yodolabs.jp>
Maintainer-email: Yodo Labs <pan@yodolabs.jp>
License: MIT
License-File: LICENSE
License-File: NOTICE.md
Keywords: city,geospatial,japan,map,plateau,poster,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Requires-Dist: geopandas>=0.14
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: pillow>=10.0
Requires-Dist: pyarrow>=15.0
Requires-Dist: pydantic>=2.6
Requires-Dist: rich>=13.7
Requires-Dist: shapely>=2.0
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: cairocffi>=1.6; extra == 'all'
Requires-Dist: imageio-ffmpeg>=0.4.9; extra == 'all'
Requires-Dist: imageio>=2.30; extra == 'all'
Requires-Dist: moviepy>=1.0.3; extra == 'all'
Provides-Extra: animation
Requires-Dist: imageio-ffmpeg>=0.4.9; extra == 'animation'
Requires-Dist: imageio>=2.30; extra == 'animation'
Requires-Dist: moviepy>=1.0.3; extra == 'animation'
Provides-Extra: cairo
Requires-Dist: cairocffi>=1.6; extra == 'cairo'
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<img src="docs/assets/branding/yodo-labs-logo.svg" alt="Yodo Labs" width="120" />

# prettyplateau

**Print-quality city visualizations from [Project PLATEAU](https://www.mlit.go.jp/plateau/) data.**

[English](./README.md) · [日本語](./README.ja.md)

[![PyPI](https://img.shields.io/pypi/v/prettyplateau.svg)](https://pypi.org/project/prettyplateau/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
[![Data: CC BY 4.0](https://img.shields.io/badge/data-CC%20BY%204.0-orange.svg)](https://creativecommons.org/licenses/by/4.0/)

</div>

---

<img src="gallery/shibuya_use_mosaic.png" alt="Shibuya — Use Mosaic, generated by prettyplateau" />

```bash
pip install prettyplateau
prettyplateau render --city shibuya --preset use_mosaic --out shibuya.png
```

```python
from prettyplateau import render

render(city="fukuoka", preset="age_rainbow", out="fukuoka.png")
```

> The commands above need a local `out_<city>/buildings.parquet` produced by
> [`plateau-bridge`](https://github.com/pixelx-jp/plateau-bridge).
> See [§ Data](#data) below for how to get one.

## What it does

Project PLATEAU is Japan's national 3D urban dataset (56+ cities, CC BY 4.0
from MLIT). Every building carries attributes that OpenStreetMap cannot
match — year built, structure type, usage, hazard exposure.
`prettyplateau` is the rendering layer that turns those attributes into
poster-quality maps and animations:

|  |  |
|---|---|
| <img src="gallery/minato_height_topo.png" /> | **Height Topo** — Minato's skyline as a topographic ramp (every building binned by `height`). |
| <img src="gallery/koto_flood_depth.png" /> | **Flood Depth** — Kōtō's river-flood exposure per building, with hashed grey for *no data* (never "low risk"). |
| <img src="gallery/shinjuku_density_hex.png" /> | **Density Hex** — Shinjuku station as a density spike on a 250 m hex lattice. |
| <img src="gallery/fukuoka_age_rainbow.png" /> | **Building Age Rainbow** — Fukuoka coloured by `year_built`. Buildings without a year stay grey — never inferred. |

See [`gallery/`](./gallery/) for the full 35-image launch matrix.

## Built-in presets

| id | type | core fields | best on |
|---|---|---|---|
| `use_mosaic` | static | `usage` | almost every city |
| `height_topo` | static | `height` | dense Tokyo wards, central Osaka |
| `flood_depth` | static | `river_flood_*` | wards along rivers |
| `risk_choropleth` | static | wood × pre-1981 × flood | the plan's flagship intersection |
| `wood_survivor` | static | `structure` + `fire_resistance` fallback | Taitō, Sumida, Kamakura |
| `age_rainbow` | static | `year_built` | Fukuoka, Sapporo |
| `hazard_confluence` | static | overlap of PLATEAU hazards | wards with multi-hazard coverage |
| `density_hex` | static | centroid → hex grid | any city, cheapest on mega-cities |
| `zoning_mosaic` | static | `zoning_use` (用途地域) | Tokyo / Osaka |
| `survivor_timeline` | mp4 (60 s) | `year_built` | Fukuoka, Sapporo |

> PLATEAU field coverage varies by city. prettyplateau treats missing data
> as **`unknown`** with a clearly-labelled grey swatch — never silently
> imputed, never recoloured by a theme.

## Themes

```bash
prettyplateau render --city shibuya --preset use_mosaic --theme sakura --out shibuya.png
```

`default` · `print` · `sakura` · `summer_matsuri` · `snow` · `neon_night`

Themes change visual presentation (background, contrast, paper texture);
they cannot change data semantics — the reserved palette keys for `unknown`,
`no_data`, and hazard severity ordering are enforced in code.

## Multi-format export

```bash
# One data load, three formats:
prettyplateau render --city shibuya --preset use_mosaic \
  --out 'shibuya.{png,svg,pdf}' --sidecar
```

| format | use |
|---|---|
| PNG (4K) | social / posters |
| SVG | Illustrator post-processing |
| PDF (300 dpi) | print-ready |
| mp4 (H.264) | animation presets |

`--sidecar` writes `{out}.json` with the full request + preset metadata
for reproducibility.

## Custom presets

```bash
prettyplateau create-preset my-preset --name "My Preset"
cd prettyplateau_preset_my_preset
pip install -e .
pytest    # green out of the box
```

Third-party presets register via Python entry points
(`prettyplateau.presets`). The scaffolding command emits a runnable
package with a sample preset, palette JSON, smoke test, and pyproject.toml.

## Attribution

Every PNG / SVG / PDF / mp4 carries:

```
© Project PLATEAU / MLIT (CC BY 4.0) · {dataset_id} · {generated_date}
```

Both as visible text **and** as file metadata. There is no flag to disable
it; themes can't hide it; custom logos can't cover it. This is a hard
requirement of the CC BY 4.0 licence under which PLATEAU data is published —
see [`NOTICE.md`](./NOTICE.md) for the full third-party-notices index.

## Data

prettyplateau **does not redistribute** PLATEAU data. The renderer reads
`buildings.parquet` files produced by
[plateau-bridge](https://github.com/pixelx-jp/plateau-bridge) which in turn
derives from the public PLATEAU dataset. Three ways to feed the renderer:

### Option 1 — run plateau-bridge yourself (any of 56+ cities)

```bash
git clone https://github.com/pixelx-jp/plateau-bridge && cd plateau-bridge
pip install -e .
plateau pipeline --city shibuya --out out_shibuya
prettyplateau render --city shibuya --preset use_mosaic \
  --out shibuya.png --data-root /path/to/plateau-bridge
```

### Option 2 — download a pre-built sample (planned)

A small set of pre-built parquets for the most-rendered cities will live
on Hugging Face Datasets so casual users can try the CLI without running
the full pipeline. *(Planned with v0.2.)*

### Option 3 — bring your own GeoDataFrame

Construct a `prettyplateau.data.access.CityDataset` directly and pass it
to the preset machinery; see `examples/custom_preset.py`.

### Licensing

PLATEAU data is **CC BY 4.0** by Japan's Ministry of Land, Infrastructure,
Transport and Tourism (国土交通省). When you publish a prettyplateau
output, the visible attribution + file-metadata attribution together
satisfy the licence. **Do not** crop the attribution out — that breaks the
licence.

## Performance

Render times on an Apple M-series:

| City | Buildings | 2400 px PNG |
|---|---|---|
| Shibuya | 42 k | 18 s |
| Minato | 32 k | 27 s |
| Fukuoka | 355 k | 120 s |
| Osaka | 615 k | 230 s |
| Yokohama | 880 k | ~330 s (density_hex only) |

Animation: 60-second Fukuoka `survivor_timeline.mp4` (180 frames at 3 fps)
≈ 5 min 40 s. See [`distribution/perf_notes.md`](./distribution/perf_notes.md)
for the profile + planned v0.2 4-5× speedup.

## Status

`0.1.0` — first public release. See [`CHANGELOG.md`](./CHANGELOG.md).

## Contributing

Bug reports, preset PRs, theme PRs, city translation PRs all welcome.
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the architecture invariants
that PRs need to respect (chief among them: attribution can't be disabled).

## Licence

- **Code**: MIT (see [`LICENSE`](./LICENSE))
- **Bundled fonts**: SIL Open Font License 1.1 — Noto Sans CJK JP + Inter
- **Generated outputs**: carry PLATEAU's CC BY 4.0 attribution both as
  visible text and file metadata
- **Third-party notices index**: [`NOTICE.md`](./NOTICE.md)

---

<div align="center">

Built by **[Yodo Labs](https://yodolabs.jp)** · PixelX Inc. (ピクセルエックス株式会社) · 東京
<br/>
Questions / partnerships: [pan@yodolabs.jp](mailto:pan@yodolabs.jp)

</div>
