# zstarview 仕様書

最終更新: 2026-03-14

## 1. この文書の位置づけ

この文書は、`zstarview` の機能仕様を利用者視点でまとめたものである。  
README より詳細に、何ができるか、どう振る舞うか、どのような制約があるかを記述する。  
内部モジュール構成や実装手順は `docs/design.md` と `docs/implementation-history.md` に分離する。

## 2. 製品概要

`zstarview` は、指定した地点と時刻における空の見え方をデスクトップ上に表示するアプリケーションである。

主な目的は次の通り。

- 地点ごとの星空を視覚的に把握できること
- 昼間、薄明、曇天でも空の状態を把握しやすいこと
- 現在時刻だけでなく、任意時刻の空を確認できること
- 位置指定、表示方向変更、重ね合わせ表示を軽快に行えること

## 3. 想定利用者とユースケース

### 3.1 想定利用者

- 任意の都市や座標から見た星空を確認したいユーザー
- タワーや展望地点からの見え方を確認したいユーザー
- 観望前に雲の状態も含めて空の状況を把握したいユーザー
- 特定の星、惑星、アステリズム、DSO の位置関係を見たいユーザー

### 3.2 代表的なユースケース

1. 都市名を指定して現在の星空を表示する。
2. 緯度経度を直接指定して、その地点の空を表示する。
3. タワー名または山名を指定して、そのビューポイントからの見え方を表示する。
4. 視線方向を変えて、天頂から地平線付近まで任意方向を観察する。
5. 指定日時の空を表示して、過去または未来の見え方を確認する。
6. 雲表示や地形地平線を補助情報として重ねて観察する。
7. 星名検索や代表恒星ジャンプで目的の天体へ素早く移動する。

## 4. 仕様範囲

### 4.1 対象機能

- 地点解決
  - 都市名
  - 国コード付き都市名
  - GeoNames ID
  - タワー名
  - Wikidata ID
  - 緯度経度
- 時刻指定
  - 現在時刻
  - 相対時間シフト
  - 絶対日時指定
- 星空表示
  - 恒星
  - 太陽、月、惑星
  - 地平線、天の赤道、黄道
  - 地平線下の地面ティント
  - 赤緯に基づく never-rises 領域の可視化
- 補助表示
  - DSO
  - アステリズム
  - 雲オーバーレイ
  - 地形地平線
- GUI 操作
  - キーボード操作
  - ハンバーガーメニュー
  - ホバー情報
- CLI 起動
- GNOME 向け `.desktop` ファイル生成

### 4.2 対象外

- 学術用途の厳密保証
- 小惑星や人工衛星などの網羅表示
- 複数ユーザー間での設定共有
- オフラインでの雲データ提供保証

## 5. 入力仕様

### 5.1 起動引数

アプリケーションは `zstarview [options] [location]` 形式で起動する。

利用者が主要に指定する入力は次の通り。

- `location`
- `-p`, `--place`
- `--place-countrycode`
- `--place-lang`
- `--datetime`
- `--hours`
- `--days`
- `-Z`, `--view-center-az`
- `-A`, `--view-center-alt`
- `--observer-height-m`
- `--cloud-opacity`
- `--sky-opacity`
- `--terrain-horizon-opacity`
- `--urban-outline-opacity`
- `-r`, `--urban-outline-radius-km`
- `-b`, `--urban-outline-min-building-height-m`
- `--ground-tint-opacity`
- `-t`, `--theme`

詳細なオプション一覧は README を正本とし、本書では動作仕様を補足する。

#### 5.1.0 地名・駅名検索オプション

- `--place QUERY`
  - OpenStreetMap Nominatim を使って地名、駅名、施設名などの自由入力文字列を検索し、その検索結果から観測地点を決める。
  - 位置引数 `location` とは相互排他とする。
  - 対話選択は行わず、正規化後の先頭候補を採用して通常起動する。
- `--place-countrycode CODE`
  - Nominatim の `countrycodes` パラメータとして検索対象国を ISO 3166-1 alpha-2 で制限する。
  - `--place` 指定時のみ意味を持つ。
- `--place-lang LANG`
  - Nominatim への `Accept-Language` として送る。
  - 既定値は `en` とする。
  - `--place` 指定時のみ意味を持つ。

`--place` 系オプションは、既存の `location` による offline-first 解決とは別経路で扱う。
`--place` が指定されていない通常起動では、GeoNames、viewpoint dataset、緯度経度解析による既存の地点解決規則を維持する。

### 5.1.1 ビューポイント dataset 一覧・詳細出力オプション

CLI には次のビューポイント dataset 参照専用オプションを持つ。

- `--list-viewpoints KIND`
  - `KIND` は `t` または `m` とする。
  - `t` は同梱タワー dataset、`m` は同梱 mountain viewpoint dataset の主表示名を 1 行 1 件で標準出力へ出し、終了する。
  - 各行は `t/NAME` または `m/NAME` 形式で出力する。
  - ASCII フォールバック名を算出できる項目では、`name` ではなくその ASCII フォールバック名を表示する。
- `--list-viewpoint-names KIND`
  - `KIND` は `t` または `m` とする。
  - `name`、`names`、`labels`、ASCII フォールバック名に含まれる名前を重複除去して 1 行 1 件で標準出力へ出し、終了する。
  - 各行は `t/NAME` または `m/NAME` 形式で出力する。
- `--show-viewpoint-json NAME`
  - `NAME` に `t/` または `m/` の prefix がある場合は、その kind だけを対象に 1 件解決して JSON で標準出力へ出し、終了する。
  - `NAME` に prefix がない場合は tower と mountain の両方を対象に解決を試みる。
  - prefix なしで tower と mountain の両方に exact match がある場合は、曖昧一致エラーとして終了する。
  - この場合、エラーメッセージには `t/...` / `m/...` 形式の候補名を列挙する。
  - JSON には、利用可能な場合 `ascii_name` を含める。

これらのオプションは相互排他とし、指定時は GUI を起動しない。
また、位置引数 `location` や描画・時刻調整オプションとは併用不可とする。
データは同梱 `tower_viewpoints.json` / `mountain_viewpoints.json` のみを参照し、GeoNames 読込や設定保存は行わない。
`mountain_viewpoints.json` は、Wikipedia を起点に候補収集し、Wikidata メタデータで正規化した同梱データである。

### 5.2 地点指定

`location` には次の形式を許容する。

- 都市名
  - 例: `Tokyo`
- 国コード付き都市名
  - 例: `JP/Tokyo`
- GeoNames ID
  - 数値のみ
- タワー名
  - 例: `Tokyo Skytree`
- 明示タワー名
  - 例: `t/Tokyo Skytree`
- 山名
  - 例: `Mount Fuji`
- 明示山名
  - 例: `m/Mount Fuji`
- Wikidata ID
  - 例: `wikidata:Q57965`
- 緯度経度
  - 例: `35.68;139.76`
  - 例: `N35.68;E139.76`

地点が省略された場合は、前回起動時の地点を使用する。初回起動時の既定地点は `Tokyo` である。
ただし、`--place` 指定時は位置引数 `location` を受け付けない。

### 5.3 地点解決の挙動

- 都市名は GeoNames データに基づいて解決する。
- 都市候補が複数ある場合は、優先規則に従って 1 件を選ぶ。
- `--place QUERY` 指定時は Nominatim に対して free-form 検索を行う。
- `--place` に対する Nominatim 候補は `importance` 降順で正規化し、先頭候補を採用する。
- `--place` で複数候補が得られた場合は、採用した先頭候補を含め、候補一覧をターミナルへ出力してよい。
- `--place` の候補選択に対して起動時の対話入力は行わない。
- `--place` で採用した地点の GUI 表示名には、Nominatim が返す長い `display_name` を短縮せずそのまま使ってよい。
- `t/NAME` は tower viewpoint としてのみ解決する。
- `m/NAME` は mountain viewpoint としてのみ解決する。
- タワー名は内蔵の viewpoint データセットから解決する。
- 山名も内蔵の mountain viewpoint データセットから解決する。
- タワー名解決では、主表示名や別名に加えて ASCII フォールバック名も受け付ける。
- 山名解決でも、主表示名や別名に加えて ASCII フォールバック名も受け付ける。
- mountain viewpoint データセットは、Wikipedia 起点の候補選定と Wikidata メタデータ正規化に基づく。
- 緯度経度入力時は都市名解決を行わない。
- 解決された地点は次回起動用設定として保存する。
- `--place` で解決した地点は、次回起動時に再検索しないよう、採用済み候補の結果オブジェクトを設定へ保存してよい。
- この保存形式は、従来の文字列ベース地点保存とは異なる構造化オブジェクトであってよい。
- 構造化オブジェクトには、少なくとも「Nominatim 由来であることを判別できる情報」と「採用した候補の正規化済み JSON」を含める。
- `--place` で解決した地点のタイムゾーンは、tower / mountain と同様に最近傍の GeoNames 都市から補完してよい。補完できない場合は UTC を用いる。

### 5.3.1 `--place` の失敗時挙動

- Nominatim 検索が 0 件だった場合は起動を中断する。
- HTTP エラー、レート制限、通信エラー、JSON 解析失敗、想定外レスポンスも起動を中断する。
- これらの失敗理由は、ターミナルとスプラッシュスクリーンの両方に表示してよい。
- 失敗メッセージには、少なくとも検索文字列と失敗理由を含める。
- `--place` を使わない通常起動時の地点解決失敗も、従来通りターミナルとスプラッシュスクリーンに表示してよい。

### 5.4 観測者高さ

- `--observer-height-m` は地面からの観測者高さをメートルで指定する。
- この値は、観測地点そのものの標高や構造物高ではなく、観測地点の足元から観測者の目線までの高さを表す。
- 既定値は入力種別にかかわらず `1.7m` とする。
- ユーザー指定値がある場合は、この既定の `1.7m` を置き換える。
- 都市名または緯度経度入力時は、観測点はその地点の地表とし、実効観測点は「地表 + 観測者高さ」とする。
- 山名入力時は、観測点は mountain viewpoint dataset に登録された山頂ビューポイントとし、実効観測点は「山頂ビューポイント + 観測者高さ」とする。
- タワー名入力時は、観測点は tower viewpoint dataset に登録されたタワーのビューポイント高とし、実効観測点は「タワービューポイント高 + 観測者高さ」とする。

### 5.5 地点種別ごとの高さ情報

- 山ビューポイントでは、利用者向け表示として山頂の海抜標高を示してよい。
- この表示ラベルは `Elevation` を用い、観測者高さとは別概念として扱う。
- タワービューポイントでは、利用者向け表示として地表からのタワー高またはビューポイント高を示してよい。
- この表示ラベルは `Tower height` を用い、観測者高さとは別概念として扱う。
- 都市名または緯度経度入力では、既定の `1.7m` は情報価値が低いため、通常表示では観測者高さを省略してよい。
- 山やタワーの情報表示において、`Height` だけの曖昧なラベルは使わず、海抜標高は `Elevation`、構造物高は `Tower height` と明示する。

## 6. 時刻仕様

### 6.1 時刻モード

本アプリケーションは次の時刻モードを持つ。

- 実時間表示
  - 現在時刻を基準に表示する
- 相対時間シフト表示
  - `--hours` または `--days` によるオフセットを適用する
- 絶対日時表示
  - `--datetime` により日時を明示指定する

### 6.2 タイムゾーン

- 都市名、タワー名、山名から起動した場合は、その地点のタイムゾーンを用いる。
- 緯度経度入力時は、指定がない限り UTC を基準とする。
- `--datetime` ではタイムゾーン略称、IANA タイムゾーン名、UTC オフセット形式を受け付ける。

### 6.3 雲表示との関係

- 雲データは現在時刻近傍の実データに依存するため、時間シフト表示では利用できない。
- 実時間以外の表示では、雲表示は無効化される。

## 7. 表示仕様

### 7.1 表示対象

画面上には次を表示する。

- 恒星
- 太陽
- 月
- 惑星
- 地平線
- 天の赤道
- 黄道
- DSO
- アステリズム
- 雲オーバーレイ
- 地形地平線
- 都市アウトライン
- ステータス表示、地点表示、時刻表示
- 山ビューポイントでは地点表示の補足情報として `Elevation` を表示してよい。
- タワービューポイントでは地点表示の補足情報として `Tower height` を表示してよい。
- `--observer-height-m` による観測者高さは、通常の地点表示では省略してよい。
- `--observer-height-m` が CLI で明示指定された場合は、地点種別にかかわらず地点表示の補足情報として `Observer height` を追加表示してよい。
- 山ビューポイントで `--observer-height-m` が指定された場合は、`Elevation` と `Observer height` を別行で併記してよい。
- タワービューポイントで `--observer-height-m` が指定された場合は、`Tower height` と `Observer height` を別行で併記してよい。

### 7.2 ビューの考え方

- 表示は円形の sky disc を基本とする。
- 視線中心は方位と高度で指定する。
- 高度は天頂方向が `90`、地平線方向が `0` である。
- 方位は度数または方位記号により解釈する。

### 7.3 星と天体の見え方

- 恒星は等級に応じて明るさとサイズを変えて表示する。
- 色のある恒星は色指数を反映した見た目を持つ。
- 月は位相を反映して表示する。
- 惑星は恒星とは異なるスタイルで識別しやすく描画する。
- 太陽、月、惑星は恒星とは別レイヤーの重要天体として扱う。
- 視線変更またはウィンドウリサイズの直後は、短時間の簡易描画モードに入り、`vmag <= 4.0` の明るい星のみを即時再投影して表示する。

### 7.4 地平線と地面表示

- 地平線上と地平線下が視覚的に区別されること。
- 地平線下の領域には地面色のティントを適用する。
- 地形地平線が有効な場合、地面/空の境界には地形地平線を用いる。
- 地形地平線が無効な場合、幾何学的地平線を用いる。
- 視線変更またはウィンドウリサイズ直後の簡易描画モードでも、天の赤道、黄道、地平線、地形地平線、方位ラベル、天頂マーカーは即時に追随表示する。

### 7.5 DSO 表示

- 対象 DSO は名称付きの主要天体に限定する。
- DSO は恒星とは異なる柔らかい強調表示で描画する。
- DSO の表示有無は GUI から切り替えられる。

### 7.6 アステリズム表示

- IAU 星座境界ではなく、一般的な線パターンとしてのアステリズムを表示する。
- 通常時は淡い補助線として表示する。
- 線分は、少なくとも片端がアステリズム表示境界内にある場合に表示し、境界外へはみ出す部分は描画しない。
- 構成恒星へホバーしたときは、そのアステリズムを強調表示する。
- 同じ恒星が複数のアステリズムに属する場合は、一定間隔で表示対象を切り替える。
- 表示有無は GUI から切り替えられる。

### 7.7 雲オーバーレイ

- 利用可能な衛星データに基づく雲表示を重畳する。
- 雲は観望の補助情報として扱う。
- 雲表示は透明度を調整できる。
- データ欠損領域は、通常領域と区別できるよう薄いティントで示す。
- 雲取得中、失敗時、部分欠損時には状態が利用者に分かるよう表示する。

### 7.8 地形地平線

- DEM から推定した地形地平線を補助線として表示できる。
- 地形地平線は地点依存であり、時刻依存ではない。
- 表示は透明度で制御する。
- `opacity == 0` の場合、DEM 取得、計算、描画をすべて行わない。
- CLI で `0` を指定して起動した場合、そのセッションでは GUI から再有効化できない。

### 7.9 都市アウトライン

- 都市アウトラインは、観測地点周辺の Overture building data から生成した建物上端の輪郭を白線で表示する。
- 表示は透明度で制御する。既定値は `0.2` である。
- CLI で指定した都市アウトライン不透明度は、高さ `50m` 以上の建物に対する基準値として扱う。
- 建物高さ `0m` の場合は基準不透明度の `1/4`、`0m` から `50m` の間は線形補間で不透明度を下げてよい。
- `opacity > 0` の場合、起動時にバックグラウンドで都市アウトライン取得またはキャッシュ読込を開始し、完了後に表示してよい。
- 都市アウトラインの取得単位は自治体ではなく、観測地点 `lat/lon` を中心とする半径 `2.5km` の範囲である。
- 取得結果は、地点、半径、最小建物高さ、feature type をキーとするローカルキャッシュとして保持してよい。
- `overturemaps` CLI が利用できない場合、または取得に失敗した場合、そのセッションでは都市アウトラインを表示しなくてよい。
- `-r`, `--urban-outline-radius-km` で取得半径を変更してよい。
- `-b`, `--urban-outline-min-building-height-m` で取得対象の最小建物高さを変更してよい。
- 取得中、キャッシュ読込中、失敗時には状態が利用者に分かるよう表示する。
- `opacity == 0` を CLI で指定して起動した場合、そのセッションでは GUI から再有効化できない。
- 都市アウトライン描画時には、キャッシュ済み derived tile に保持されている建物を runtime 側で高さ再フィルタせず利用してよい。
- runtime の都市アウトライン内部表現は、各輪郭ごとに `height_m` を保持する前提でよい。
- 見かけの方位幅が `0.5°` 未満の細い屋根線分は、細かい輪郭ではなく、太い水平線として簡略表示する。

## 8. GUI 操作仕様

### 8.1 基本操作

- 矢印キーで表示方向を変更できる。
- 矢印キーによる連続操作中は、最後の入力から約 0.7 秒間、明るい星とガイドライン中心の簡易描画モードを維持する。
- `M` で月の拡大表示を切り替える。
- `D` で DSO 表示を切り替える。
- `A` でアステリズム表示を切り替える。
- `S` で sky color disc 表示を切り替える。
- `C` で雲表示を切り替える。
- `T` で地形地平線表示を切り替える。
- `U` で都市アウトライン表示を切り替える。
- `F11` で fullscreen を切り替える。
- `Q` で終了する。

### 8.2 メニュー操作

ハンバーガーメニューから次を実行できる。

- 代表恒星ジャンプ
- 星とアステリズムの検索
- 各種表示トグル
- fullscreen
- 終了

### 8.3 ホバーとハイライト

- 恒星ホバー時は名称などの情報を表示する。
- DSO ホバーは恒星ホバーと独立して扱う。
- ジャンプや検索で選択した対象は一時的にハイライトする。

### 8.4 ビューポート操作中の簡易描画

- 視線変更またはウィンドウリサイズの直後は `viewport interaction mode` に入る。
- このモードは最後の入力またはリサイズから約 0.7 秒で終了する。
- このモード中に表示するのは、`vmag <= 4.0` の恒星、天の赤道、黄道、地平線、地形地平線、方位ラベル、天頂マーカーである。
- このモード中は惑星、全星等の星空、sky color disc、雲、DSO、アステリズムは表示しない。
- 都市アウトラインは、このモード中は描画しない。
- モード終了後に通常の星空、sky color disc、雲、地形地平線、都市アウトラインの更新を行う。

## 9. 設定保持仕様

- 最後に使用した地点を保存する。
- ウィンドウ位置やサイズなどの GUI 状態を保存する。
- ローカル設定ファイルはユーザー環境下に保存し、リポジトリには含めない。

## 10. エラー時の利用者向け挙動

### 10.1 起動不能なエラー

- 星データや必須初期化に失敗した場合は、起動を中断する。
- 起動失敗時は原因が分かる形でログまたはメッセージを残す。

### 10.2 継続可能なエラー

- 雲取得失敗時でも星空表示は継続する。
- 地形地平線取得失敗時でも本体表示は継続する。
- 一時的なネットワーク不調で全体が異常終了しないこと。

### 10.3 ステータス表示

- 雲の取得状態や失敗状態を利用者が確認できること。
- 地形地平線の読み込みや失敗状態を利用者が確認できること。
- ステータス表示は画面操作を妨げない補助情報として提供する。

## 11. 非機能仕様

### 11.1 応答性

- UI は操作に対して即応すること。
- 重い処理は利用者操作を長時間ブロックしないこと。

### 11.2 耐障害性

- 外部データ取得失敗が発生しても、本体表示機能はできるだけ維持すること。

### 11.3 保守性

- 利用者向け仕様、内部設計、実装履歴を別文書として維持すること。

## 12. 既知の制約

- 雲表示は外部の衛星データ供給状況に依存する。
- オフライン環境では雲表示は利用できない。
- 高密度な表示設定では計算量と描画負荷が増える。
- 表示精度は利用ライブラリ、元データ品質、地点解決結果に依存する。
