# 入力データ契約ガイド

最終更新: 2026-02-28

この文書は、描画・天体計算・クラウド投影で使う入力データの型/単位/座標系の規約です。
将来の変更では、本ガイドを優先して整合を保ってください。

## 1. 角度・座標系の基本規約

- 角度は原則として `deg`（度）を使う。
- 方位角 `az` は `0=N, 90=E, 180=S, 270=W` とする。
- 視点中心 `view_center` は `(alt_deg, az_deg)` の順とする。
- 新規APIでは `altaz` 順（`alt_deg` → `az_deg`）を採用する。

## 2. 命名規約

- 角度: `*_deg`
- ピクセル: `*_px`
- 距離(km): `*_km`
- 高さ(m): `*_height_m`
- 標高/絶対高度(m): `*_elevation_m`
- 時間差: `timedelta` を使い、生の時間数値は境界でのみ扱う。

例:
- `view_alt_deg`, `width_px`, `height_px`, `radius_px`, `cloud_shell_km`, `observer_height_m`, `viewpoint_height_m`

## 3. 型規約

- `types.py` の単位付きエイリアスを使う:
  - `AltDeg`, `AzDeg`, `LatDeg`, `LonDeg`
  - `LocationLatLon`, `ViewCenterAltAz`
- 星空テーブルは `StarsTable(TypedDict)` を使い、キー契約を固定する:
  - `name`, `alt`, `az`, `vmag`, `bv`
- 観測者情報は少なくとも以下を一貫して保持する:
  - `location`: `(lat_deg, lon_deg)`
  - `observer_height_m`: 地面からの高さ[m]

## 3.1 観測者高さの契約

- 公開CLIでは `observer_height_m` を扱う。
- 値の意味は「地面からの高さ[m]」であり、海抜の絶対標高ではない。
- 既定値:
  - 都市名/緯度経度入力: `1.7`
  - タワー入力: `viewpoint_height_m + 1.7`
- viewpoint dataset では tower 系に `viewpoint_height_m` を持てる。
- `viewpoint_height_m` は、地表から観測基準点までの高さ[m]を表し、`observer_height_m` とは別概念とする。
- 地形地平線側では `observer_ground_m + observer_height_m` の形で使う。
- 天体計算側でも同じ `observer_height_m` を `EarthLocation` / `Topos` へ通す。
- 将来 `observer_elevation_m` を公開する場合でも、内部では `observer_height_m` と混同しない。

## 4. API互換と移行

- 引数順を変更する場合は段階導入する:
  - 新APIを追加
  - 内部呼び出しを新APIへ移行
  - 互換ラッパーを廃止予定として明示
  - 内部利用が消えた時点でラッパーを削除

## 5. Docstring規約

- 単位・座標系・順序・範囲を明記する。
- 実装と食い違う説明は禁止する。
  - 例: 正規化座標は `90deg -> 1.0` 基準であり、値が `1.0` を超える場合がある。

## 6. レビュー観点（チェックリスト）

- 引数名に単位が含まれているか（`*_deg/*_px/*_km`）。
- 高さが `height` なのか `elevation` なのか命名で区別されているか。
- `alt/az` の順序が規約どおりか。
- 観測者座標系と画面座標系が混在していないか。
- 型注釈が `types.py` の契約に沿っているか。
- docstring と実装が一致しているか。

## 7. 星カタログ生成契約（v1）

`zstarview` を星データ生成の正本とし、Desktop/VR で同一データ系統を使うための契約。

### 7.1 入力カタログ

- Hipparcos（明るい恒星の基準）
- Tycho-2（暗い恒星の補完）

### 7.2 正規化後の出力列

- 必須列:
  - `ra_hours`（J2000, hour）
  - `dec_deg`（J2000, deg）
  - `vmag`（視等級）
  - `bv`（B-V 色指数, 欠損可）
  - `name`（表示名。なければ空文字）
  - `source_catalog`（`hip` / `tyc2`）
  - `source_id`（元カタログID文字列）
- 任意列:
  - `hip_id`, `tyc_id`（重複解決の追跡用）

### 7.3 等級レンジ運用

- 基本レンジ: `vmag <= 6.0`（既存品質の維持対象）
- 拡張レンジ: `6.0 < vmag <= 7.0`, `<= 8.0`, `<= 9.0`, `<= 10.0`
- 配布成果物は以下の段階生成を許可する:
  - `base`（`<= 6.0`）
  - `extra7`（`6.0 < ... <= 7.0`）
  - `extra8`（`7.0 < ... <= 8.0`）
  - `extra9`（`8.0 < ... <= 9.0`）
  - `extra10`（`9.0 < ... <= 10.0`）

### 7.4 重複解決ルール

- 原則:
  - 同一天体候補（ID対応または近傍一致）は1件に統合する。
- 優先順位:
  - `vmag <= 6.0` は Hipparcos 優先。
  - `vmag > 6.0` は Tycho-2 補完を優先し、Hipparcos と重複する場合は片側を除去。
- 近傍一致の暫定判定:
  - 角距離しきい値 + 等級差しきい値で候補化し、最終選択は上記優先順位で決める。
  - しきい値の具体値は生成スクリプト内定数として管理し、変更時は本書更新を必須とする。

### 7.5 欠損値ルール

- `ra_hours`, `dec_deg`, `vmag` 欠損行は除外。
- `bv` 欠損は許容し、描画側既定色（中性色）へフォールバックする。
- `name` 欠損は空文字で保持する。

### 7.6 受け入れ基準（データ）

- `vmag <= 6.0` の総件数が現行比で大幅に逸脱しないこと。
- 既知の明るい恒星（例: Sirius, Canopus, Vega）が欠落しないこと。
- 重複解決後に同一天体の近傍重複が目視で支配的に残らないこと。
- 生成ログに以下を出力すること:
  - 入力件数
  - 出力件数（レンジ別）
  - 除外件数（欠損/範囲外/重複）
  - `bv` 欠損率
