Metadata-Version: 2.5
Name: datapng-tiler
Version: 0.1.2
Summary: Generate data PNG tiles (numerical PNG / palette PNG) and TileJSON conforming to the TileJSON DataPNG Extension
Project-URL: Homepage, https://github.com/qchizu-project/datapng-tiler
Project-URL: Repository, https://github.com/qchizu-project/datapng-tiler
Project-URL: Issues, https://github.com/qchizu-project/datapng-tiler/issues
Project-URL: Changelog, https://github.com/qchizu-project/datapng-tiler/blob/main/CHANGELOG.md
Project-URL: Specification, https://github.com/qchizu-project/tilejson-datapng-extension
Author: qchizu
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: dem,gis,png,raster,tilejson,tiles,webp,xyz
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: jsonschema>=4.20
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rasterio>=1.3
Description-Content-Type: text/markdown

# datapng-tiler

ラスタデータから [データPNG](https://gsj-seamless.jp/labs/datapng/) タイル（**数値PNG**・**パレットPNG**）と **TileJSON** を生成する CLI / Python ライブラリです。

[TileJSON DataPNG Extension](https://github.com/qchizu-project/tilejson-datapng-extension) v0.7.0 に準拠します。

> **Language**: [English README](https://github.com/qchizu-project/datapng-tiler/blob/main/README.en.md)

## これは何か

標高・水深・気温のような**連続値**や、土地利用・浸水深階級のような**区分**を、地図タイルとして配信するときに使います。値を RGB に可逆に埋め込んだタイルと、それを復号するために必要なメタデータ（係数・単位・無効値・凡例など）を記述した TileJSON を、まとめて生成します。

| | 数値PNG（numerical） | パレットPNG（palette） |
|---|---|---|
| 入力 | 連続値のラスタ | クラス値ラスタ、または RGB ラスタ + 凡例定義 |
| 格納 | 値を 24 ビット符号付き整数に量子化して RGB へ | 凡例の色をそのまま |
| 用途 | 標高・水深・気温・濃度 | 土地利用・災害リスク区分 |

タイル画像は **WebP（可逆圧縮）が既定**で、PNG も選べます。どちらも可逆なので値は劣化しません。

## インストール

```sh
uvx datapng-tiler --help          # 実行するだけなら（インストール不要）
pipx install datapng-tiler        # コマンドとして常設する
pip install datapng-tiler         # ライブラリとしても使う
```

Python 3.12 以上が必要です。GDAL は rasterio の wheel に同梱されているので、別途インストールする必要はありません。

## 使い方

### 数値PNGタイル（標高など）

```sh
datapng-tiler tile dem.tif -o tiles/ --factor 0.01 --unit m \
    --description "標高は東京湾平均海面（T.P.）基準。"
```

`tiles/` に以下が生成されます。

```
tiles/
├── {z}/{x}/{y}.webp   タイル
├── tiles.json         TileJSON（datapng 拡張つき）
└── index.html         プレビュー（ブラウザで開くと値を読める）
```

`--factor 0.01` は「0.01 単位で量子化する」という意味です。標高なら 1cm 刻み。値が 24 ビット整数（±8,388,607）に収まらない場合は**エラーで止まります**——黙って折り返した誤った値を出力しないためです。エラーメッセージが適切な `--factor` を提示します。

### パレットPNGタイル（区分など）

凡例定義（YAML または JSON）を用意します。

```yaml
# legend.yaml
title: 洪水浸水想定区域（想定最大規模）浸水深
items:
  - value: 1          # クラス値ラスタを入力にするときの対応値
    r: 245
    g: 245
    b: 50
    title: 0.5m未満
    description: 床下浸水相当。避難行動は徒歩で可能。
  - value: 2
    r: 255
    g: 216
    b: 0
    title: 0.5〜3.0m
```

```sh
datapng-tiler tile flood.tif -o tiles/ --type palette --legend legend.yaml
```

RGB ラスタ（すでに色が塗られたデータ）も入力にできます。その場合 `value` は不要です。**凡例に無い色が見つかるとエラーで止まります**（`--on-unknown-color nodata` で無効値として扱えます）。

### 既存タイルの移行

Mapbox Terrain-RGB や Mapzen/Terrarium で配信されている既存のタイル資産を、正式なデータPNG エンコードへ移せます。タイルはすでに目的の格子に載っているので再投影せず、値を読み替えるだけです。

```sh
datapng-tiler convert ./terrain-rgb/ -o tiles/ --from mapbox --factor 0.01 --unit m
```

逆に、既存のラスタから Terrain-RGB 互換のタイルを作ることもできます。

```sh
datapng-tiler tile dem.tif -o tiles/ --encoding mapbox
```

### 検証

生成物が仕様に適合しているかを確かめます。CI に組み込めます。

```sh
datapng-tiler validate tiles/tiles.json --tiles tiles/
```

2 段階で見ます。

1. `datapng` を仕様の JSON Schema にかける
2. **宣言と実タイルを突き合わせる** — ズーム範囲・形式・無効値の表し方・凡例の色

とくに「アルファチャンネルを持つタイルに `invalidColor` を宣言してはならない」（仕様 §3.2.2 MUST NOT）は TileJSON だけを見ても分からず、実タイルを開いて初めて検出できます。

### 1 枚を確認する

```sh
datapng-tiler inspect tiles/14/14552/6451.webp --tilejson tiles/tiles.json --pixel 100 200
```

## 無効値の表し方

無効値はアルファ 0 か、指定した色のどちらか一方で表します。

| | 無効値 | `invalidColor` |
|---|---|---|
| 既定 | アルファ 0 | 宣言しない |
| `--no-alpha --invalid-color R G B` | 指定した色 | 宣言する |

仕様 §3.2.2 の `invalidColor` は**完全に透明な画素を指せません**（WebP の可逆圧縮が透明画素の RGB を保存しないため）。既定の出力では無効画素が完全に透明になるので、色を宣言しても判定に使われません。CLI は `--invalid-color` の単独指定を拒否します。

なお、無効画素が 1 つも無いタイルはアルファチャンネルを持たない形で書かれます（容量が減ります）。

## 主なオプション

```
--format webp|png            タイル画像形式（既定: webp）
--tile-size N                タイル一辺の画素数（既定: 512）
--support point|block        画素値が代表する領域（既定: point = 左上節点）
--resampling nearest|bilinear|cubic|lanczos    再投影カーネル（既定: bilinear）
--factor F --offset O        v = F × rawValue + O
--encoding mapbox|terrarium  互換エンコードで出力する
--on-overflow error|clamp|nodata               範囲外の値の扱い（既定: error）
--data-range MIN MAX         TileJSON に載せる期待範囲
--auto-data-range            期待範囲を生成タイルから実測する
-z / --min-zoom              ズーム範囲（既定: ソース解像度から自動）
--bounds W S E N             生成範囲（既定: ソース範囲）
-j / --jobs N                並列プロセス数（既定: CPU 数）
--overwrite                  既存タイルも作り直す（入力を更新したときに必要）
--basemap none|gsi|osm       プレビューの背景地図（既定: none）
```

`datapng-tiler <サブコマンド> --help` で全オプションを確認できます。

中断した実行は、同じコマンドをもう一度走らせれば続きから再開します（既存タイルはスキップされます）。**入力データを更新したときは `--overwrite` が必要です**——既定では既存タイルを作り直さないため、1 枚も更新されません。

## プレビューについて

`index.html` はタイル木のルートに置かれ、ブラウザで開くとカーソル位置の値を表示します。画像として並べるだけでなく **TileJSON の宣言どおりに復号して見せる**ので、「絵としては出ているが値が違う」を見つけられます。

- 値の読み取りにはタイルが HTML と同一オリジンにある必要があります（`python -m http.server -d tiles/` などで開いてください）。別オリジンのタイルは表示はできますが値を読めません。
- **背景地図は既定で無し**です。`--basemap gsi|osm` で選べます。

## ライブラリとして使う

```python
from datapng_tiler.codec import NumericalEncoding
from datapng_tiler.engine import tile_raster
from datapng_tiler.modes import NumericalMode
from datapng_tiler.tilejson import from_tree, write_tilejson

mode = NumericalMode(encoding=NumericalEncoding(factor=0.01), unit="m")
result = tile_raster("dem.tif", "tiles/", mode, processes=8)
write_tilejson(from_tree("tiles/", mode, name="標高"), "tiles/tiles.json")
```

`datapng_tiler.codec` は純粋関数だけなので、符号化・復号だけを使うこともできます。

開発・貢献については [CONTRIBUTING.md](https://github.com/qchizu-project/datapng-tiler/blob/main/CONTRIBUTING.md) を参照してください。性能の実測は [BENCHMARKS.md](https://github.com/qchizu-project/datapng-tiler/blob/main/BENCHMARKS.md) を参照してください。

## ライセンス

MIT License（[LICENSE](https://github.com/qchizu-project/datapng-tiler/blob/main/LICENSE)）。準拠仕様と依存ライブラリの帰属は [NOTICE](https://github.com/qchizu-project/datapng-tiler/blob/main/NOTICE) を参照してください。

準拠する仕様 [TileJSON DataPNG Extension](https://github.com/qchizu-project/tilejson-datapng-extension) は CC0 1.0 で公開されています。
