Image-to-Depth Web Viewer

Language / 言語: English | 日本語

English

Overview

This repository now ships a two-part toolchain: a WebGL viewer in webapp/ and a FastAPI backend in server/. Raw JPG/PNG images are uploaded through the UI, the backend runs Apple Depth Pro (pulled in as the third_party/ml-depth-pro submodule plus depth-pro_rgbde.py) to infer depth, and the resulting depth-augmented PNG (RGBDE PNG) streams straight back to the browser for preview and download. Generated RGBDE PNGs include Depth Pro focal length metadata, and metadata-bearing RGBDE files initialize the Geometry FOV from that camera estimate. Precomputed RGBDE assets remain fully supported. From the viewer you can export the adjusted mesh and texture as a binary glTF (.glb) with an unlit material (KHR_materials_unlit) for DCC packages such as Blender. While inspecting the scene you can switch between linear/log depth, apply magnification (0.1×–100×), clamp the far plane (1–1000 m), and tune both reconstruction and display FOVs in real time.

Getting Started

1. Initialise the repo (installs requirements, creates .venv, pulls Depth Pro submodule):

   python scripts/bootstrap.py

   The script upgrades pip, creates the .venv virtual environment, installs requirements.txt (NumPy is pinned to <2 for Depth Pro compatibility), and then installs the Depth Pro package (pip install -e third_party/ml-depth-pro). This step also pulls in PyTorch, torchvision, timm, and the other dependencies required by Depth Pro. If the automatic submodule checkout fails, the script falls back to cloning the repository directly. You can also run git submodule update --init --recursive yourself before re-running the bootstrap step.

2. Activate the virtual environment:

   # Linux / macOS
   source .venv/bin/activate
   # Windows PowerShell / CMD
   .\.venv\Scripts\activate

   On startup the backend checks checkpoints/depth_pro.pt; if absent it is fetched automatically from Hugging Face (apple/DepthPro). Set DEPTH_DEVICE (e.g., cuda, cpu) before launching if you need to force a specific device.

3. Start the development servers (frontend + backend). Recommended:

   python scripts/run.py

   This launches both servers in one terminal (http://localhost:8000, http://localhost:5173). To run them separately, launch the backend first:

   python scripts/run_backend.py

   …then, in another terminal:

   python scripts/run_frontend.py

   Both approaches expose http://localhost:5173 (configurable via RGBDE_FRONTEND_PORT). For local performance spot checks, open http://localhost:5173/perf-harness.html after the frontend starts. The harness benchmarks the repository-local RGBDE fixtures and, when the backend is running, can also time one /api/process round trip.

4. Open the viewer in Chrome/Edge/Safari:

   • 2D Image (JPEG or PNG) selects a source image; Generate Depth runs Depth Pro through the backend. The backend does not keep uploaded files after responding.
   • Save RGBDE downloads the current RGBDE PNG, and Save glTF exports the displayed mesh as a .glb with embedded texture and an unlit material (KHR_materials_unlit).
   • Load RGBDE PNG file / Open file... loads a precomputed RGBDE PNG. Drag-and-drop also works. If the PNG contains Depth Pro focal length metadata, Geom FOV is initialized from it for 2D, SBS, and XR display paths.
   • Display Mode switches between 2D and 3D SBS. Stereo Separation adjusts SBS eye spacing, and Swap Left/Right for Cross-Eyed Viewing swaps the SBS eye order.
   • Geom FOV controls reconstruction rays. The compact Mesh selector beside it switches reconstruction density between 1x, 2x, and 4x. Screen FOV controls the display camera separately.
   • Depth Magnification, Depth Mode, Log Power, Far Crop Distance, and Model Z Offset adjust depth shaping, clipping, and placement. Mouse wheel zooms, left-drag rotates, right-drag pans, and double-click resets the view.
   • Enter VR, Enter Looking Glass, and Show XR hints are described in the WebXR section below. Running the backend elsewhere? Set window.__RGBDE_API_BASE__ = 'http://host:port' before loading, or adjust API_BASE in webapp/src/app.js.

WebXR / XR playback

• The control panel now includes Enter VR and Enter Looking Glass buttons (requires a WebXR-enabled Chromium-based browser on HTTPS/localhost).
• PC-tethered OpenXR headsets (Meta Quest via Link, Valve Index, HTC Vive, Varjo, HP Reverb G2, etc.): launch the vendor’s OpenXR runtime (Meta Quest Link, SteamVR, Windows Mixed Reality, Varjo Base, …), open the viewer in Chrome/Edge on the host PC, then click Enter VR. Ending the session returns to the standard canvas.
• Looking Glass displays: install Looking Glass Bridge, connect the display, and click Enter Looking Glass. The viewer dynamically loads the official @lookingglass/webxr v0.6.0 polyfill to drive the multi-view quilt. Keep Bridge running so the polyfill detects the display. Looking Glass renders many viewpoints at once, so once in XR the model appears freely rotatable even though the mouse-driven offsets stay within the ±30° clamp.
• VR controller mapping: while in VR, the left controller mirrors the desktop interactions—trigger + move to orbit, grip + move to pan, trigger + forward/back to zoom, stick left/right adjusts Geometry FOV (15–120°, default 32°), stick up/down changes Depth Magnification (0.1×–100×), X decreases Far Clip, Y increases Far Clip. Controllers are not rendered in the scene, but inputs remain live. Double-click the canvas to reset if the view drifts.
• Hint overlay: the viewer shows a brief control cheat sheet when a VR session starts and single-line popups for subsequent inputs. If you prefer a clean view, untick Show XR hints next to the Enter VR button; you can re-enable it at any time.
• Looking Glass to VR workflow: the Looking Glass WebXR polyfill replaces navigator.xr and leaves it patched; after exiting a Looking Glass session, reload the page (Ctrl+F5) before starting a standard VR session. Skipping the reload typically yields “VR session blocked: click Enter VR again”.
• WebXR requires a secure origin; deploy behind HTTPS in production (self-signed certificates won’t satisfy Quest browsers). Local development on http://localhost works because browsers treat it as a secure context.
• While an XR session is active the 2D UI hides automatically—press the toggle on exit to restore it if needed.

Repository Layout

• webapp/index.html – entry point and UI shell.
• webapp/perf-harness.html – lightweight local benchmark page for RGBDE decode, preprocessing, mesh generation, and optional backend round-trip timing.
• webapp/src/geometry.js – RGBDE decoding, depth preprocessing, mesh density selection, and pinhole projection.
• webapp/src/rendering.js – WebGL2 renderer, shader setup, and camera math.
• webapp/src/app.js – event wiring, UI bindings, and interaction logic.
• webapp/src/gltf-exporter.js – binary glTF (.glb) writer used by the Save glTF workflow.
• webapp/src/webxr.js – WebXR session orchestration for VR and Looking Glass.

Third-Party Resources

• Apple Depth Pro – Pulled via scripts/bootstrap.py into third_party/ml-depth-pro. Usage is governed by Apple’s sample code license (third_party/ml-depth-pro/LICENSE). Installers must agree to that license before running the backend.
• Looking Glass WebXR Polyfill – Loaded at runtime from the official CDN (@lookingglass/webxr). The package is not bundled with this repo; when used, it remains subject to Looking Glass Factory’s license terms (see the package’s LICENSE on npm).
• These components are external dependencies and are not redistributed here. If you plan to bundle them, ensure your distribution complies with each provider’s license terms (including any redistribution restrictions).

日本語

概要

本リポジトリは WebGL ビューア (webapp/) と Python/FastAPI バックエンド (server/) をセットで提供します。フロントエンドから JPG / PNG をアップロードすると、バックエンドが submodule で取り込んだ Apple Depth Pro（third_party/ml-depth-pro と depth-pro_rgbde.py）を実行し、右半分に little-endian の uint32 深度を埋め込んだデプス付き PNG（RGBDE PNG）を生成、即座にブラウザへ返します。生成される RGBDE PNG には Depth Pro の推定焦点距離メタデータも埋め込まれ、メタデータを持つ RGBDE を読み込むと、そのカメラ推定値から Geometry FOV が初期化されます。既存の RGBDE PNG をドラッグ＆ドロップで読み込むこともできます。UI では線形／対数デプス、拡大率（0.1×〜100×）、最大距離クロップ（1〜1000 m）、再構成・表示 FOV を調整でき、調整済みメッシュとテクスチャをバイナリ glTF (.glb) として書き出して Blender などで再利用できます。

使い方

1. まず依存関係と Submodule をまとめてセットアップします。

   python scripts/bootstrap.py

   上記で .venv が作成され、requirements.txt と Depth Pro パッケージ（pip install -e third_party/ml-depth-pro）がインストールされます。 サブモジュール初期化に失敗した場合でもスクリプトが直接 clone を試みますが、git submodule update --init --recursive を手動で実行してから再度ブートストラップすることもできます。

2. 仮想環境を有効化します。

   # Linux / macOS
   source .venv/bin/activate
   # Windows PowerShell / CMD
   .\.venv\Scripts\activate

   起動時に checkpoints/depth_pro.pt が存在しない場合は Hugging Face (apple/DepthPro) から自動ダウンロードします。デバイスを固定したい場合は起動前に DEPTH_DEVICE=cuda（または cpu など）を設定してください。

3. 開発用サーバーを起動します。おすすめの方法:

   python scripts/run.py

   1つのターミナルでバックエンド (http://localhost:8000) とフロントエンド (http://localhost:5173) が一括起動します。 個別に起動したい場合は、先にバックエンドを立ち上げてから別ターミナルでフロントエンドを起動してください。

   python scripts/run_backend.py
   # 別ターミナル
   python scripts/run_frontend.py

   どちらの場合も RGBDE_FRONTEND_PORT でフロントエンドのポートを変更できます。 ローカルで処理時間をざっと確認したい場合は、フロントエンド起動後に http://localhost:5173/perf-harness.html を開いてください。リポジトリ同梱の RGBDE fixture を使って、デコード・前処理・メッシュ生成を計測でき、バックエンド起動中なら /api/process の往復時間も確認できます。

4. ブラウザ (Chrome / Edge / Safari) で http://localhost:5173 を開き、以下を操作します。

   • 2D Image (JPEG or PNG) で元画像を選び、Generate Depth でバックエンド経由の Depth Pro 推論を実行します。サーバー側の一時ファイルはレスポンス後に削除されます。
   • Save RGBDE は表示中の RGBDE PNG を保存し、Save glTF は現在のメッシュとテクスチャを .glb としてエクスポートします。KHR_materials_unlit 拡張を使ったアンリットマテリアル付きです。
   • Load RGBDE PNG file / Open file... で作成済み RGBDE PNG を読み込めます。ドラッグ＆ドロップにも対応します。Depth Pro の推定焦点距離メタデータを含む場合は、2D / SBS / XR の表示方式に関係なく Geom FOV の初期値に反映されます。
   • Display Mode は 2D / 3D SBS の切り替えです。Stereo Separation は SBS の目間距離、Swap Left/Right for Cross-Eyed Viewing は SBS の左右入れ替えを調整します。
   • Geom FOV は再構成用の視野角です。横のコンパクトな Mesh セレクタで再構成密度を 1x / 2x / 4x に切り替えられます。Screen FOV は表示カメラ側の視野角です。
   • Depth Magnification、Depth Mode、Log Power、Far Crop Distance、Model Z Offset はデプス変形、クロップ、配置を調整します。マウスホイールでズーム、左ドラッグで回転、右ドラッグで平行移動、ダブルクリックでリセットします。
   • Enter VR、Enter Looking Glass、Show XR hints は下の WebXR セクションで説明しています。バックエンドを別ホスト／別ポートで稼働させる場合は、ページ読込前に window.__RGBDE_API_BASE__ = "http://host:port" を設定するか、webapp/src/app.js の API_BASE を編集してください。

WebXR / XR 再生

• コントロールパネルに Enter VR / Enter Looking Glass ボタンを追加しました（WebXR 対応の Chromium 系ブラウザ + HTTPS/localhost が必要）。
• PC 接続型 OpenXR ヘッドセット（Meta Quest + Link、Valve Index、HTC Vive、Varjo、HP Reverb G2 など）: 各ベンダーの OpenXR ランタイム（Quest Link、SteamVR、Windows Mixed Reality、Varjo Base など）を起動し、PC の Chrome / Edge でビューアを開いて Enter VR を押すと没入セッションが開始します。終了すると通常表示に戻ります。
• Looking Glass displays: Looking Glass Bridge を起動しディスプレイを接続してから Enter Looking Glass を押すと、公式 @lookingglass/webxr v0.6.0 polyfill を動的に読み込み、多視点キルト描画に切り替わります。Bridge を常時起動しておいてください。多視点キルトにより表示側で広い角度が補間されるため、XR中はモデルを自由に回しているように見えます（マウス操作の回転制限自体は従来どおり ±30° です）。
• VR コントローラー操作: 左コントローラーでマウス操作に相当するインタラクションが行えます。トリガー＋左右／上下で回転、グリップ＋移動で平行移動、トリガー＋前後でズーム、スティック左右で再構成 FOV、スティック上下で Depth Magnification、X ボタンで Far Clip を短く、Y ボタンで Far Clip を大きくできます。コントローラー自体は描画されませんが、入力は反映されます。ビューが崩れた場合はキャンバスをダブルクリックで初期状態に戻せます。
• ヒント表示: VR セッション開始時に操作チートシートが表示され、その後は操作に応じて 1 行のヒントがポップアップします。不要な場合は Enter VR の横にある Show XR hints のチェックを外すと非表示にでき、必要になったら再度チェックを入れて表示を戻せます。
• Looking Glass と VR の切り替え: Looking Glass の WebXR ポリフィルは navigator.xr を差し替えたまま復元しないため、Looking Glass を Exit した直後に Enter VR を押すとブラウザがセッションを拒否して「VR session blocked: click Enter VR again」と表示されます。現状はページをリロード（例: Ctrl+F5）した後に VR を開始してください。
• WebXR API は HTTPS などのセキュアオリジンでのみ利用可能です。Quest ブラウザでは自己署名証明書は使えないため、本番では正規証明書を用意してください。ローカル開発での http://localhost アクセスは例外的にセキュア扱いとなるため、その場合は従来どおり動作します。
• XR セッション中は 2D UI が自動的に非表示になります。終了後に必要なら「Hide UI」ボタンで再表示できます。

ディレクトリ構成

• webapp/index.html – 画面レイアウトと UI。
• webapp/perf-harness.html – RGBDE デコード、前処理、メッシュ生成、必要に応じてバックエンド往復時間を確認するための軽量なローカル計測ページ。
• webapp/src/geometry.js – RGBDE の展開、デプス前処理、メッシュ分割と投影ロジック。
• webapp/src/rendering.js – WebGL2 レンダラーとカメラ行列。
• webapp/src/app.js – UI イベントとインタラクション制御。
• webapp/src/gltf-exporter.js – Save glTF で使用する glTF (.glb) エクスポータ。
• webapp/src/webxr.js – VR / Looking Glass 向け WebXR セッション管理。

サードパーティリソース

• Apple Depth Pro – scripts/bootstrap.py 実行時に third_party/ml-depth-pro として取得されます。利用には Apple のサンプルコードライセンス (third_party/ml-depth-pro/LICENSE) への同意が必要です。
• Looking Glass WebXR Polyfill – 実行時に CDN (@lookingglass/webxr) から読み込みます。このリポジトリには同梱していませんが、利用時は Looking Glass Factory のライセンス（パッケージの LICENSE 参照）に従ってください。
• これら外部コンポーネントを成果物に含める場合は、各提供元のライセンス条件（再配布可否や同梱義務を含む）に従ってください。