ユーザーガイド

第4章 — 補助ウィンドウ

メインウィンドウ(3Dビューポートおよびインスペクター)のほかに、RadianceKitはさらに3つのウィンドウを管理しており、そのすべてがHelpメニューから開けます。メニューには上から順に5つの項目があります:User Guide (⌘?)、Keyboard Shortcuts (⌘/)、Open Training Logs… (⇧⌘L)、Open Exports Folder…、Manage Storage…。2つの「Open …」項目はアプリのウィンドウではなくFinderを開くものなので、ここでは扱いません。

3つのシンプルなウィンドウ(User Guide、Keyboard Shortcuts、Manage Storage)と2つのフォルダーメニュー項目(Open Training Logs / Open Exports Folder)については、各コントロールごとに簡潔な項目を用意しています。

章の最後には、メインウィンドウのインスペクターへのクロスリファレンスの節があります:トレーニング実行中にライブ損失チャートとGaussian数の表示から何を読み取れば有用か、という内容です。

ユーザーガイド (W1–W4)

左側にサイドバー、右側にレンダリングされたMarkdownコンテンツがあるユーザーガイドウィンドウ
左側にサイドバー、右側にレンダリングされたMarkdownコンテンツがあるユーザーガイドウィンドウ

それは何か: アプリに同梱されている guide_<sprache>.md をレンダリングする、組み込みのヘルプウィンドウ。言語はSettings(Tab General → Language)から、そこに「System」と指定されている場合はmacOSの言語設定から導出される。レイアウトはクラシックで、左にすべての見出しを表示するサイドバー、右に本文が表示される。

個々のポイントについて素早く確認したいとき — つまりキーワード代わりとして使う場合。詳細なリファレンスはこのマニュアルであり、組み込みのヘルプウィンドウは素早く調べるための短縮版だ。アプリのリリースごとに更新されるが、内容はより表面的にとどめられている。

W1NavigationSplitView(サイドバー + 詳細)

場所

Help → User Guide (⌘?)。

技術詳細

コンテンツツリー用の細いサイドバー(幅は最低180 pt)と、実際のMarkdownコンテンツ用のスクロール可能な詳細領域からなる2カラムレイアウト。ウィンドウの最小サイズは700 × 500 pt。初回起動時にウィンドウはアプリバンドルから該当する guide_<lang>.md を読み込み(フォールバックは guide_en.md)、それをブロックレコード(見出しH1–H4、段落、リスト、テーブル、区切り線)にパースし、サイドバー用に見出し構造を別途抽出する。インライン書式(太字、斜体、コードスパン)は組み込みのMarkdownエンジンによってレンダリングされる。 言語はアプリの設定から読み込まれ、中国語(zh-Hans)とブラジルポルトガル語(pt-BR)は特殊ケースとして完全なロケールタグのまま保持される。これはこれらのバリアントがそれぞれzhおよびptと異なるためである。

W2List(見出しサイドバー)

場所

ユーザーガイドウィンドウの左カラム。

技術詳細

現在のMarkdownドキュメントのすべてのH2・H3見出しの一覧。H2項目はインデントなしで中程度のフォントウェイトで表示され、H3項目は左に16 ptのインデントと控えめなフォアグラウンドスタイルで表示される。それ以外のレベル — H1もH4以下も同様に — はサイドバーに表示されない。表示すると見通しが悪くなるためだ。アンカーIDは見出しテキストからスラッグ化によって生成される(小文字化 + スペースをダッシュに変換 + 文字・数字・ダッシュのみへのフィルタリング — これはGitHubがMarkdownアンカーに使用しているのと同じアルゴリズムであり、ドキュメントへの外部URLも潜在的に同じアンカーに到達しうる)。リストにはネイティブのmacOSスタイルが使われる。

W3Button(見出し → アンカージャンプ)

場所

サイドバーの各行にひとつずつ配置されたボタン。

技術詳細

各サイドバー項目はボタンであり、現在のアンカーを設定するが、見た目はリスト項目のように見える。オブザーバー変数がそれをトリガーとして、0.3秒のなめらかなアニメーションで対応するアンカーへスクロールジャンプする。ジャンプ後、アンカー値はリセットされる。これは同じアンカーへの次のクリックでも再度発火させるためだ(そうしないと値が変化していないため、オブザーバーが再発火しない)。

W4ScrollView(詳細コンテンツ)

場所

右カラム。

技術詳細

スクロール可能な、垂直に積み重なるコンテンツ領域で、遅延レンダリングを採用している。長めのガイドでは200個を超えるMarkdownブロックになることも珍しくなく — 遅延読み込みでない場合はすべてを同時にインスタンス化することになってしまう。各ブロックには固有のIDが付与され、見出しアンカー(レベルにかかわらずすべての見出しに付与される)またはインデックス用のプレースホルダーのいずれかが使われる。 最大幅は720 pt、パディングは水平32 / 垂直24で、長い行でも読みやすいレイアウトが保たれる。テーブルはセル単位で水平スタックと区切り線を使ってレンダリングされ、インラインコードは組み込みのMarkdownエンジンによって処理される。実際のコードブロックは現状では段落として扱われる — これはヘルプウィンドウの既知の制限である。

キーボードショートカット (W5–W6)

Keyboard Shortcuts ウィンドウ — Navigation/Views/Capture/Editor/Trainingの5つのグループ。左にホットキー列、右に説明
Keyboard Shortcuts ウィンドウ — Navigation/Views/Capture/Editor/Trainingの5つのグループ、 左にホットキー列、右に説明

5つのセクションに分かれた静的なリファレンスリスト。Navigation: Mouse Drag(Orbit/Fly)、 Shift+Drag/Right-Drag(Pan)、Scroll(Zoom)、WASD(Fly-Through移動)、 Q/E(Up/Down)、F(Orbit/Fly切り替え)、Double-click(再センタリング)、 Cmd+Scroll(FoV調整)。Views: R(Camera Reset)、T (自動回転)、P(Camera Playback)、B(Background切り替え)、0–9 (Training-Camへジャンプ 1=10%/5=50%/0=last)、Left/Right Arrow (前/次のCam)。Capture: S(デスクトップへScreenshot)、V (Turntable動画)、C(Camera情報をコピー)。Editor: Tab (Editモード)、Click/Drag(ペイント選択)、Option+Click(選択解除)、 X / Delete(選択を削除)、Cmd-Z(直前の削除を取り消し)、 [ / ](ブラシサイズを縮小/拡大)、Esc(選択解除)。 Training: Option+Space(Trainingの一時停止/再開)、Cmd+E (シーンをエクスポート)。ここに書かれているのはこれだけだ — Start、Cancel、延長操作は Trainingメニュー(第1章)から行う。

これは何か: すべてのキーボードショートカット — Navigation、Views、Capture、Editor、Training — をまとめた、シンプルな静的一覧だ。内容は固定で組み込まれており、ファイルから読み込まれるわけではない。

Viewport内で何かを最速で行う方法を探しているときに。WASDでのFly-Through、Rでの Camera Reset、BでのBackground切り替え — すべてここに載っている。

W5ScrollView(コンテンツ領域)

場所

Help → Keyboard Shortcuts (⌘/)。

技術詳細

中に縦方向のリストが入った、シンプルなスクロール領域。周囲に20 ptのPaddingがあり、 サイドバーのナビゲーションツリーはない(リストは十分短いため)。内容は 5つのセクション(Navigation、Views、Capture、Editor、Training)にグループ化されている。 各キーの組み合わせごとに、両カラムに翻訳可能なテキストを持つ1行がある。左カラム(キーコード)は 幅180 ptに固定されており、右側の説明が縦方向に揃うようになっている。スクロール以外の インタラクションはない — 行をクリックしても何も起こらず、キーボードショートカットは メニューとViewport上での本物のキーボードModifierだ。

W6VStack(ショートカットセクション)

場所

ScrollViewの内部。

技術詳細

左揃えで16 ptの間隔を空けて積み重ねられたセクション。5つのセクションそれぞれの中に Heading + 行の並びがある。Headingにはセカンダリなsubheadlineスタイルを使用している — セクションが ナビゲート可能である必要はないため、意図的にTitle形式は使っていない。内容は意図的に フラットにしてある(Disclosureなし、Searchなし、Filterなし)ため、このコンポーネントは どのmacOSバージョンでも変わらず動作し、ファイルも読みやすい状態を保てる。

ストレージを管理 (W7–W12)

Manage Storage Fenster — Header zeigt „1,356 items · 55.1 GB total”, Tabelle mit Export-PLY-Dateien sortiert nach Datum, jeweils Icon + Dateiname + Größe + Datum
「Manage Storage」ウィンドウ — ヘッダーには「1,356 items · 55.1 GB total」と表示され、テーブルには日付順に並んだExport-PLYファイルが、それぞれアイコン + ファイル名 + サイズ + 日付 という形式で並んでいる

RadianceKitが管理するすべてのファイルのテーブル表示。ヘッダーには1,356件のアイテム、合計55.1 GBと表示されている。上部のツールバー: 「Show in Finder」+「Refresh」。各行の内容: Exportアイコン、ファイル名(例: training_20260718T194416Z.ply)、 Export日時、サイズ(このキャプチャでは7.8 MBから2.24 GBまでばらつきがある)、虫眼鏡アイコン (Reveal)、ゴミ箱アイコン(Move to Trash)。ソート順はまずカテゴリ別、カテゴリ内では日付順で新しいものが上に来る。 この画面ではPLYエクスポートが大半を占めているが、これはこの保存先に主にトレーニング結果が保存されているためだ。

これは何か: RadianceKitが ~/Documents/RadianceKit/ 以下に保存する すべてのもの — ログ、エクスポート、シーン、(iOSコンパニオンからの)キャプチャバンドル、 インポート(入力画像のステージングコピー) — についてのディスク使用状況の一覧だ。各項目にはバイト単位のサイズと 2つのボタンがある: 「Finderで表示」と「ゴミ箱に入れる」。これは自動的な クリーンアップでは【ない】— アプリ自体は何も削除しない。あなたが項目ごとに 判断する。このウィンドウはローカライズされていて、ドイツ語では「Speicher verwalten」という名称になり、 ヘッダーの2つのボタンは「Im Finder anzeigen」と「Aktualisieren」、行のボタンは「Im Finder anzeigen」と「In den Papierkorb legen」という名称になる。下記の各項目にある英語名は 英語版での表記だ。

ディスクが一杯になってきたとき。特にログは たまりやすい(トレーニング試行1回につきJSONLが1つ、加えて _qualityMetrics.json)。エクスポートも当然たまる(PLYは生データそのまま100%で、 エクスポート1回につき1ファイル)。クラッシュ後、Importsのステージングディレクトリに 古い入力画像のコピーがまだ残っている場合にも役立つ。

W7「Show in Finder」ボタン

場所

ストレージブラウザウィンドウ右上のヘッダー。

技術詳細

RadianceKitのデータフォルダをFinderで開く — まさにこのウィンドウが一覧表示している内容のディレクトリだ。これにより フォルダ構成(Logs、Exports、Scenes、Captures、Imports)を 直接見ることができ、Finder自体でファイルを移動やコピーすることもできる。この操作は 新しいFinderウィンドウを開くだけで、このウィンドウ内のリストがそれに合わせて更新されることはない — そのために「Refresh」(W8)がある。

W8「Refresh」ボタン

場所

ヘッダー、Finderボタンの隣。

技術詳細

ユーザーが起動した非同期タスク上で実行される バックグラウンドスキャンをトリガーする。これにより大きなディレクトリツリーのスキャンが UIをブロックしないようになっている。実際のウォーク処理は既知の サブフォルダ(Logs、Exports、Scenes、Captures、Imports)をすべて 巡回し、直下の子要素ごとにストレージエントリを生成する。各エントリについて 再帰的なサイズが計算される — 優先されるのは実際のディスク消費量 (APFSのハードリンク共有を考慮したもの)で、フォールバックとして論理的な ファイルサイズが使われる。

W9List(ストレージ項目一覧)

場所

ヘッダー下のメインコンテンツ。

技術詳細

各行が次のレイアウトを持つリスト: カテゴリ 固有のSF Symbolsアイコン(Logsは書類、Exportsは上向き矢印、 Scenesは立方体、Capture-Bundlesはスマホ、Importsはトレイ)、名前 + サブタイトル (種類ラベル + フォーマット済みの更新日時)、右側のバイトカウンター (右揃え、等幅フォント)、Revealボタン(虫眼鏡アイコン)、Trashボタン (ゴミ箱アイコン)。ソート順: まず種類(Scenesが最初、その後 Exports、Logs、Captures、Imports、Otherの順)、次に更新日時の 降順(新しいものが上)。スキャンがまだ進行中の場合は、その部分に 「Scanning…」という進捗表示が代わりに出る。何も見つからなかった場合は、 トレイアイコン付きの空状態表示になる。

W10行内ボタン「Reveal in Finder」

場所

各行、右側の虫眼鏡アイコン。

技術詳細

Finderを開き、特定の項目(ファイルまたはフォルダ)を 選択状態にする。W7との違い: W7はルートディレクトリを開くのに対し、 W10はまさにこの1つの項目だけを選択状態にする。実践的な ワークフロー: 大きな項目を特定し、虫眼鏡をクリックし、 例えば外部ボリュームへコピーする、という流れになる。

W11行内ボタン「Move to Trash」

場所

各行、虫眼鏡の隣にあるゴミ箱アイコン。

技術詳細

確認ダイアログボックス(W12)をトリガーする。 確認後にはじめてmacOS標準の「ゴミ箱に移動する」操作が 実行される(つまり可逆的であり、即時削除ではない)。ゴミ箱移動が 成功すると、その項目はリストから削除され、合計バイトカウンターが 更新される。エラー発生時にはモーダルの エラーダイアログが表示される。

W12ConfirmationDialog(削除確認)

場所

W11によってトリガーされ、macOSのシートとして表示される。

技術詳細

動的なタイトル「Delete <name>?」を持つ 標準的な確認ダイアログで、メッセージ行には項目がゴミ箱に 入り、そこから(ゴミ箱が空にされるまでは)復元可能であることが 明示的に記載されている。ボタンは2つ: 破壊的な操作(赤色で表示)としての「Move to Trash」と、Escキーが 自動的に割り当てられた「Cancel」。このダイアログは非モーダルという 意味合いでは、このウィンドウのみをブロックし、アプリ全体は ブロックしない — これは可逆的な削除に対するmacOSの標準的な挙動だ。

メインウィンドウ:損失推移とガウシアン数(I39–I41、相互参照)

メインウィンドウの Inspector 表示のうち3つは、トレーニング実行中は常に目にするものであり、また推移が健全に見えるかどうかを判断する重要な経験則があるため、個別に説明する価値がある。これらの表示は Inspector の進捗セクション内、折りたたみ可能なグループ損失推移(第2章 — Inspector を参照)にあり、トレーニングの進捗を読み取るための補足情報となる。

Loss カーブが健全なのはどんなとき? 健全な Loss カーブは3つのフェーズを示す。(1) ウォームアップ — 最初の200–500イテレーションで、Loss はシーンにもよるが高い値(L1+SSIM 結合で典型的に0.15–0.25)からその半分程度まで急激に下がる。このフェーズで Loss が下がらない場合、たいてい入力に問題がある(画像が壊れている、SfM のポーズが悪い、初期ガウシアン数が少なすぎる、など)。(2) Densification — ~500 から densifyUntilIteration(クラシックでは典型的に15K、MCMC では20K または25K まで)の間、Loss はさらに下がり続け、Densify 操作が新しいガウシアンを挿入してオプティマイザがそれを活用するたびに小さな段差状の下降が見られることが多い。このフェーズではガウシアン数が増加する。(3) リファインメント — その後、Loss はだんだん平坦になっていくテールに入る。目安となる典型的な最終値としては、良好に照明されたオブジェクトシーン(例えば Tanks-&-Temples の Truck を P4 Quality で処理した場合)では L1 ≈ 0.023 に落ち着き、Mip-NeRF 360 のような広範囲の屋外シーンでは当然それより高め(0.04–0.07)になる。

プラトーは何を意味するのか? プラトー(Loss カーブが数千イテレーションにわたって水平に推移する状態)には2つの解釈がある。(a) モデルが収束しており、これ以上トレーニングしても意味がない — これは良いケースだ。(b) モデルがスタックしている(局所最小値、勾配情報が乏しい、バッファ上限に達したなど) — これは悪いケースだ。両者はチャート上では同じに見える。見分け方:ガウシアン数を確認しよう。もしそれも平坦で、かつ MCMC の Cap に近い(例えば Preset P8 Quality (MCMC) で150K のうち150K に達している場合)なら、上限に達している状態だ — Cap を上げるか、プラトーを受け入れるかのどちらかになる。ガウシアン数がまだ増えているのに Loss が下がらない場合は、スタックしている。

いつ中止し、いつトレーニングを続けるべきか? 経験則:10K イテレーションの間 Min-Loss の改善が見られなければ中止する。それ以上続けてもイテレーションが無駄になる。それより前の段階では、Training メニュー → Continue Training → 「+5,000 iterations」から延長を追加できる(限界的な改善が見られる場合。これに対応するキーボードショートカットはない)。注意:MCMC の場合、プラトーは本物であることが多い — Cap が自然な限界だからだ。

ガウシアン数のプラトーは「完了」のシグナルではない。 それは単に MCMC が Cap に達したか、Classic Densification が限界まで使い切られたことを 意味するにすぎない。本当の「完了」の問いに答えられるのは、独立した テストセットに対する PSNR/SSIM/LPIPS だけだ。独立したテストセットは、 あなたのカメラセットがそもそもトレーニング用とテスト用の視点に公平に 分割できるかどうかも示す。

PSNR/ホールドアウトこそが真実であり、Loss はあくまで代理指標にすぎない。 Loss は相対的なメトリクスであり、モデルがトレーニング用ビューに適応するにつれて下がっていく。しかし Loss が低いからといって、自動的に良いモデルというわけではない — もしモデルがトレーニング画像を丸暗記してしまっていたら(過学習)、Loss は小さくなる一方で、未見のビュー(ホールドアウト)に対する PSNR は悪くなるだろう。だからこそ、最終的な品質評価では常にホールドアウトのメトリクスを見るべきであり、最終 Loss だけを見てはいけない。

経験則ボックス

- User Guide と Keyboard Shortcuts は静的なヘルプです — キーワードで調べたいときは素早く使え、深く知りたいときはこの本編のマニュアルを使ってください。 - ディスクの空き容量が10%を下回ったら Manage Storage を開きましょう。ログと Imports のステージングが大抵の元凶です。 - Loss-Plateau と Gaussian-Count-Plateau は別々に解釈する必要があります。 Cap-Limit は「完了」のシグナルではありません。本当の品質は Holdout-PSNRでしか測れません。 - Min-Lossの改善なしに10,000イテレーションが経過したら → トレーニングを停止してください。