datapng-tiler 0.1.0__tar.gz

datapng_tiler-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "monthly"

datapng_tiler-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: ci
+
+# PR と main への push で lint / テストを走らせる。
+# 一般公開ツールのため 3 OS で回す。特にプロセス並列は Linux が fork、macOS/Windows が
+# spawn と既定が異なり、ワーカへ状態を渡す経路の壊れ方が OS で変わる（tests/test_engine.py）。
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+# fork からの PR でもブランチ側のコードを実行するため、既定より絞る。
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: ruff check
+        run: uv run --locked ruff check .
+      - name: ruff format --check
+        run: uv run --locked ruff format --check .
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: pytest
+        run: uv run --locked pytest
+
+  spec-schema:
+    # 同梱している JSON Schema が仕様リポジトリの配布物と一致しているかを確認する
+    # （仕様が更新されたのに実装側のスキーマが古いまま、を防ぐ）。
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: 仕様リポジトリのスキーマと突合
+        run: uv run --locked python scripts/check_schema_sync.py

datapng_tiler-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: release
+
+# v* タグの push でビルドし、PyPI へ公開して GitHub Release を作成する。
+# リリース手順:
+#   1. src/datapng_tiler/__init__.py の __version__ と CHANGELOG.md を更新して main にマージ
+#   2. git tag vX.Y.Z && git push origin vX.Y.Z
+#
+# PyPI への公開は Trusted Publishing（OIDC）で行うため API トークンを secrets に置かない。
+# 初回のみ PyPI 側で pending publisher の登録が必要（README「リリース」を参照）。
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: タグとパッケージバージョンの整合チェック
+        run: |
+          pkg=$(grep -oP '__version__ = "\K[^"]+' src/datapng_tiler/__init__.py)
+          if [ "v$pkg" != "$GITHUB_REF_NAME" ]; then
+            echo "タグ $GITHUB_REF_NAME と __version__ v$pkg が不一致"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: テスト
+        run: uv run --locked pytest
+
+      - name: ビルド（sdist + wheel）
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Trusted Publishing（OIDC）に必要
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: GitHub Release 作成
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes "詳細は CHANGELOG.md を参照。"

datapng_tiler-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# ツール
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# 作業用
+/tmp/
+*.tmp

datapng_tiler-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

datapng_tiler-0.1.0/BENCHMARKS.md

@@ -0,0 +1,107 @@
+# 実測
+
+設定を選ぶための相対比較の記録です。**絶対値には意味がありません**（環境とデータで変わります）。
+再現するには次を実行してください。
+
+```sh
+uv run python scripts/benchmark.py --size 4096 --max-zoom 13 --min-zoom 8 --jobs 8
+```
+
+## 測定条件
+
+| 項目 | 値 |
+|------|-----|
+| データ | 合成 DEM 4096×4096 float32（地形らしい空間相関を持たせたもの。縁は無効値） |
+| 出力 | z8–13、タイル 906 枚、512px |
+| 符号化 | `factor=0.01` |
+| 環境 | WSL2 / 16 論理コア / Python 3.12 / rasterio 1.5.1 / Pillow 12 |
+
+合成データは実際の地形より高周波成分が多く、**容量は実データより大きく出ます**。設定どうしの
+比較には使えますが、配信容量の見積もりには使わないでください。
+
+## 形式と圧縮設定
+
+| 設定 | 時間 [s] | 合計 [MB] |
+|------|---------:|----------:|
+| WebP lossless method=0 | 35.3 | 229.0 |
+| **WebP lossless method=1（既定）** | **42.8** | **172.0** |
+| WebP lossless method=4 | 58.1 | 171.8 |
+| WebP lossless method=6 | 127.9 | 171.7 |
+| PNG compress_level=1 | 14.7 | 289.6 |
+| **PNG compress_level=6（既定）** | **27.2** | **244.7** |
+| PNG compress_level=9 | 71.9 | 240.6 |
+
+**WebP の `method` 既定を 1 にした理由**: method 0 → 1 で容量が 25% 減るのに対し、1 → 6 では
+0.2% しか減らず、時間は 3 倍になります。容量がほぼ頭打ちになる最初の点が 1 です。
+
+**PNG の `compress_level` 既定を 6 にした理由**: Pillow の既定と同じで、9 に上げても 1.7% しか
+減らないのに 2.6 倍の時間がかかります。速度が要るなら 1 が選べます（容量 +18%）。
+
+**形式の選択**: WebP は PNG より **30% 小さく**、時間は 1.6 倍かかります。可逆圧縮なので値は
+どちらも劣化しません。配信容量が効く用途では WebP（既定）、PNG しか受け付けないクライアントに
+合わせる必要がある場合だけ PNG を選んでください。
+
+## 並列数
+
+| `-j` | 時間 [s] | 逐次比 |
+|-----:|---------:|-------:|
+| 1 | 217.9 | 1.0× |
+| 2 | 124.4 | 1.8× |
+| 4 | 70.8 | 3.1× |
+| 8 | 43.4 | 5.0× |
+| 16 | 34.1 | 6.4× |
+
+既定は CPU 数です。16 コアで 6.4 倍にとどまるのは、ズーム間に依存があるオーバービュー生成が
+逐次に近づくためです（同一ズーム内は並列）。
+
+## 時間の内訳
+
+ベースタイル 60 枚を 1 プロセスで生成して `cProfile` で測った内訳です。
+
+| 処理 | 割合 |
+|------|-----:|
+| WebP エンコード（Pillow → libwebp） | 75% |
+| 再投影とウィンドウ読み取り（GDAL） | 14% |
+| 符号化・画像の組み立て（本ツール） | 8% |
+
+**支配項は画像エンコードで、自前の配列処理ではありません。** 高速化したいときは、まず
+`--webp-method` や `--format` を見直すのが効きます。
+
+## qchizu-tools との比較
+
+設計の下敷きにした [qchizu-tools](https://github.com/qchizu-project/qchizu-tools)（非公開）の
+`tile --mode numeric` と、同じ入力・同じ設定で比べました。同一マシンで連続して 2 回ずつ。
+
+| 実装 | 1 回目 [s] | 2 回目 [s] | 合計 [MB] |
+|------|----------:|----------:|----------:|
+| qchizu-tools | 61.3 | 58.4 | 172.0 |
+| datapng-tiler | 46.8 | 44.6 | 172.0 |
+
+容量は同一（同じ WebP 設定・同じ符号化）で、時間は約 24% 短くなりました。
+
+**出力の突き合わせ**（有効画素 58,270,353 について復号値を比較）:
+
+- **99.51% が完全一致**
+- 残り 0.49% は raw で 1（= 0.01 m）だけ違う
+- 1 量子化ステップを超える差は 0 件
+
+差の原因は量子化を行う浮動小数の精度です。qchizu-tools は float32 の配列をそのまま
+`values / factor` にかけるため、NumPy の弱い型付けにより float32 のまま計算されます。
+本ツールは float64 を明示しています（`codec.NumericalEncoding._to_scaled`）。原典を独立に
+bilinear 補間して突き合わせると、本ツールの値は量子化の半幅（0.005 m）以内に収まります。
+
+## 値の正確性の実測
+
+合成 DEM（円錐 + 高周波成分、512×512、`factor=0.01`）を z13 までタイル化し、**配信物
+（TileJSON + タイル）だけを見て復号**した値を、原典ラスタを独立に bilinear 補間した値と
+突き合わせました。
+
+| 項目 | 値 |
+|------|-----|
+| 検査画素 | 8,615 |
+| 最大差 | 0.00510 m |
+| 中央値 | 0.00254 m |
+| 量子化の半幅 | 0.005 m |
+
+最大差が量子化の半幅とほぼ一致しており、**量子化以外の誤差（幾何のずれ・補間の食い違い）は
+検出されませんでした**。

datapng_tiler-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# 変更履歴
+
+このファイルの書式は [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) に従い、
+バージョニングは [Semantic Versioning](https://semver.org/lang/ja/) に従います。
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-29
+
+初版。[TileJSON DataPNG Extension](https://github.com/qchizu-project/tilejson-datapng-extension)
+v0.7.0 に準拠します。
+
+### Added
+
+- `tile`: ラスタから数値型・パレット型のタイル木と TileJSON を生成する
+  - 出力形式は WebP（可逆圧縮・既定）と PNG。形式はタイル URL の拡張子が示す
+  - `factor` / `offset` による量子化、`specialEncoding`（mapbox / terrarium）互換出力
+  - `support`（point / block）に応じた再投影アライメントとオーバービュー方式
+  - パレット型は凡例定義（YAML / JSON）から色を引き、PNG ではインデックスカラーで書く
+  - `--auto-data-range` で `dataRange` を生成タイルから実測
+  - プロセス並列・レジューム・アトミック書き込み
+- `convert`: 既存タイル木の再エンコード（Terrain-RGB / Terrarium → 正式エンコード、形式変換）
+- `tilejson`: 既存タイル木から TileJSON を生成する（範囲・ズームは走査して実測）
+- `validate`: JSON Schema による仕様適合検証と、宣言と実タイルの突合
+  （タイル URL の拡張子と中身の食い違いも検出する）
+- `inspect`: タイル 1 枚を復号して統計・特定画素の値を表示する
+- プレビュー HTML（カーソル位置の値を仕様どおりに復号して表示。背景地図は既定で無し）
+
+[Unreleased]: https://github.com/qchizu-project/datapng-tiler/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/qchizu-project/datapng-tiler/releases/tag/v0.1.0

datapng_tiler-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# コントリビューションについて
+
+Issue・Pull Request を歓迎します。日本語でも英語でも構いません。
+
+## どこに出すか
+
+このリポジトリは**仕様の実装**です。指摘の内容によって、出し先が変わります。
+
+| 内容 | 出し先 |
+|------|--------|
+| このツールの不具合・機能追加 | このリポジトリの [Issues](https://github.com/qchizu-project/datapng-tiler/issues) |
+| 仕様そのものへの疑問・提案 | [tilejson-datapng-extension](https://github.com/qchizu-project/tilejson-datapng-extension/issues) |
+
+「仕様ではこう読めるのに実装がそうなっていない」という指摘は、どちらでも構いません（こちらで振り分けます）。仕様の解釈が曖昧だった、という結論になることもあります。
+
+## 開発
+
+```sh
+uv sync
+uv run pytest -v
+uv run ruff check . && uv run ruff format .
+```
+
+CI は Ubuntu / macOS / Windows × Python 3.12 / 3.13 で回ります。プロセス並列の既定が
+Linux は fork、macOS と Windows は spawn と異なるため、**ワーカへ渡す状態はすべて
+`initargs` で明示的に渡してください**（グローバル変数は spawn では引き継がれません）。
+
+## テストの方針
+
+- **仕様適合は独立デコーダで確かめます。** `tests/test_codec.py` には仕様書の変換式を
+  文字どおり写したデコーダがあります。実装のデコーダで往復させても「実装が自分の仕様に
+  従っている」ことしか言えないためです。新しいエンコードを足すときも、まず仕様の式を
+  ここへ写してください。
+- **タイルの値は解析的に検証します。** 値が座標の 1 次関数になる合成ラスタを使い、
+  タイル画素が代表する座標での真値と突き合わせます（`tests/helpers.py`）。
+  「絵として正しそう」では幾何の半画素ずれを検出できません。
+- **外部データ・ネットワークに依存しません。** 必要なラスタはその場で合成します。
+- 決定性（同じ入力から同じバイト列）と、並列・逐次の一致もテストで固定しています。
+
+## 設計上、動かしにくいところ
+
+次の 2 つは、片方だけ変えられない形に閉じてあります。壊さないでください。
+
+- **`support` の宣言と生成方式**（`modes/base.py`）。TileJSON に書く `support` と、
+  実際の再投影アライメント・オーバービュー方式は必ず一致します。
+- **無効値の表し方**（`modes/numerical.py`）。アルファか `invalidColor` のどちらか一方で、
+  併用はできません（仕様 §3.2.2 MUST NOT）。
+
+## コミットメッセージ
+
+[Conventional Commits](https://www.conventionalcommits.org/ja/) の形式（`feat:` / `fix:` /
+`docs:` / `refactor:` / `test:` / `chore:`）を使います。本文には**なぜそうしたか**を書いて
+ください——何をしたかは diff を見れば分かります。
+
+## ライセンス
+
+貢献いただいたコードは MIT License で配布されます。

datapng_tiler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qchizu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datapng_tiler-0.1.0/NOTICE

@@ -0,0 +1,51 @@
+datapng-tiler
+Copyright (c) 2026 qchizu
+
+本ソフトウェアは MIT License で配布されます（LICENSE を参照）。
+
+
+## 準拠する仕様
+
+本ソフトウェアは以下の仕様に準拠して実装されています。いずれも本ソフトウェアの
+著作物ではありません。
+
+- TileJSON DataPNG Extension（qchizu-project, CC0 1.0 Universal）
+  https://github.com/qchizu-project/tilejson-datapng-extension
+
+  `src/datapng_tiler/schema/datapng-0.7.0.schema.json` は、上記仕様が公開する
+  JSON Schema をそのまま同梱したものです。CC0 1.0 Universal（パブリックドメイン
+  献呈）で公開されているため、再配布にクレジット表示は不要ですが、出典を明示する
+  ために記載します。
+
+- TileJSON 3.0.0（Mapbox, CC-BY 3.0）
+  https://github.com/mapbox/tilejson-spec/tree/master/3.0.0
+
+- データPNG／グリッドPNGタイル仕様 v0.1（産業技術総合研究所 地質調査総合センター）
+  https://gsj-seamless.jp/labs/datapng/
+
+- Mapbox Terrain-RGB / Mapzen Terrarium（`specialEncoding` の互換復号式）
+  いずれも公開されている復号式のみを実装しており、コードの流用はありません。
+
+
+## 設計上の参照
+
+タイル生成の設計（EPSG:3857 への再投影パラメータ算出、ベースタイル → オーバー
+ビューの構成、プロセス並列とレジューム、数値の 24 ビット整数エンコード）は、
+同一著作権者が開発した非公開ツール `qchizu-tools` の運用知見を踏まえています。
+コードは本リポジトリのために書き下ろしたものです。
+
+
+## 依存ライブラリ
+
+実行時の依存はいずれも寛容型ライセンスであり、MIT License と両立します。
+
+| パッケージ | ライセンス |
+|-----------|-----------|
+| rasterio  | BSD-3-Clause（同梱される GDAL は MIT/X 系、PROJ は MIT） |
+| numpy     | BSD-3-Clause |
+| Pillow    | MIT-CMU (HPND) |
+| jsonschema | MIT |
+| PyYAML    | MIT |
+
+プレビュー HTML は Leaflet（BSD-2-Clause）を CDN から読み込みます。Leaflet の
+コードは本リポジトリに同梱していません。

datapng_tiler-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: datapng-tiler
+Version: 0.1.0
+Summary: Generate data tiles (numerical / palette) 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 タイル**（数値型・パレット型）と **TileJSON** を生成する CLI / Python ライブラリです。
+
+[TileJSON DataPNG Extension](https://github.com/qchizu-project/tilejson-datapng-extension) v0.7.0 に準拠します。
+
+> **Language**: [English README](./README.en.md)
+
+## これは何か
+
+標高・水深・気温のような**連続値**や、土地利用・浸水深階級のような**区分**を、地図タイルとして配信するときに使います。値を RGB に可逆に埋め込んだタイルと、それを復号するために必要なメタデータ（係数・単位・無効値・凡例など）を記述した TileJSON を、まとめて生成します。
+
+| | 数値型（numerical） | パレット型（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 に同梱されているので、別途インストールする必要はありません。
+
+## 使い方
+
+### 数値型タイル（標高など）
+
+```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` を提示します。
+
+### パレット型タイル（区分など）
+
+凡例定義（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
+```
+
+## 正確性について
+
+このツールが特に気をつけていることを挙げます。
+
+**無効値の判定に閾値を使いません。** 「nodata に近い値を無効とみなす」実装は、nodata が 0 や正の値であるデータで有効値を消してしまいます。GDAL のマスクを正とし、nodata の宣言が無いソースではワープの被覆マスク（`add_alpha`）でソース範囲外を無効にします。
+
+**24 ビットに収まらない値を黙って通しません。** 既定でエラーにし、`--on-overflow clamp|nodata` で明示的に選べます。
+
+**`support` の宣言と生成方式が必ず一致します。** `--support point`（既定）なら左上法で再投影し、オーバービューも左上の値を運びます。`--support block` なら中心整列で、オーバービューは整数領域での平均になります。TileJSON にはそのとおりの `support` が出ます。片方だけ変えられる API にはしていません。
+
+**再投影は厳密寄りのトランスフォーマで行います。** GDAL 既定の近似トランスフォーマは近似誤差が出力解像度（＝生成ズーム）によって変わるため、同じ地点を狙っても標本位置がサブピクセルでにじみ、「ズームによって値が違う」現象を生みます。
+
+**オーバービューは raw 整数のまま合成します。** 値は raw 整数のアフィン関数なので、整数領域の平均と値領域の平均は一致し、ズームを重ねても量子化誤差が積み上がりません。
+
+**出力は決定的です。** 同じ入力・同じ設定なら、`--jobs` を変えても生成されるタイルはバイト単位で一致します。
+
+## 無効値の表し方
+
+無効値はアルファ 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/` などで開いてください）。別オリジンのタイルは表示はできますが値を読めません。
+- **背景地図は既定で無しです。** 地理院タイルや OpenStreetMap を既定にすると、このツールを使うすべての人に第三者サービスの利用規約を負わせることになるためです。`--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` は純粋関数だけなので、符号化・復号だけを使うこともできます。
+
+## 開発
+
+```sh
+uv sync
+uv run pytest -v
+uv run ruff check . && uv run ruff format .
+```
+
+テストは外部データやネットワークに依存しません。仕様適合の検証には、**仕様書の変換式を文字どおり写した独立デコーダ**を使っています（実装同士の往復では「実装が自分の仕様に従っている」ことしか言えないため）。
+
+性能の実測は [BENCHMARKS.md](./BENCHMARKS.md) を参照してください。
+
+## リリース
+
+1. `src/datapng_tiler/__init__.py` の `__version__` と `CHANGELOG.md` を更新して main にマージ
+2. `git tag vX.Y.Z && git push origin vX.Y.Z`
+
+タグの push で GitHub Actions が PyPI（Trusted Publishing）と GitHub Release へ公開します。初回のみ PyPI 側で pending publisher の登録が必要です。
+
+## ライセンス
+
+MIT License（[LICENSE](./LICENSE)）。準拠仕様と依存ライブラリの帰属は [NOTICE](./NOTICE) を参照してください。
+
+準拠する仕様 [TileJSON DataPNG Extension](https://github.com/qchizu-project/tilejson-datapng-extension) は CC0 1.0 で公開されています。