projects:ep_dome [wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Planetarium Dome Visuals — Project Summary ======

===== The Project =====
Live, real-time visuals for a planetarium dome theatre, streamed over NDI from Unreal Engine. Concept: audience is inside a capsule that descends from air into the sea — water ripple/drip shader, camera passes through the water surface partway through.

----

===== Confirmed Technical Specs =====

^ Item ^ Value ^
| Output resolution | 4096×4096 ("4K" fulldome — refers to the ~4096 dimension, not equivalent to 4K flat video pixel count) |
| Frame rate | 30fps |
| Projection format | Domemaster / fisheye (equidistant azimuthal) |
| NDI format | **Full NDI (SpeedHQ codec)** — confirmed acceptable by theatre, HX not required |
| Source OS | Windows (required — Unreal Engine doesn't run on Linux/Mac in a way that fits this pipeline) |
| Receiver OS | Windows (confirmed by theatre IT) |
| Dome type | Planetarium dome (standard hemisphere, not a tilted theatre-style dome) |
| Audio | None — visuals only |

===== Computer / GPU =====
  * Water/ripple shaders are procedural (fragment-shader-bound) — no heavy geometry or lighting, much lighter load than a lit 3D environment at the same resolution
  * Resolution (16.8MP/frame at 4096×4096) still dominates cost even for simple shaders
  * 30fps (not 60fps) gives more render budget per frame (~33ms) than a 60fps target would
  * **Working target: RTX 4070/4080-class GPU, 12GB+ VRAM** — a reasonable floor for this content type, not a hard spec
  * No hard benchmark data exists for this exact combination (Unreal + 4096² + OWL fisheye capture + NDI encode) — build a small test scene at target complexity early and measure actual frame time before buying/renting hardware
  * NDI encode (SpeedHQ, CPU-based) adds overhead on top of the render itself — factor in decent multicore CPU, not just GPU

===== Projection Math — You Don't Need It =====
  * OWL's 360 camera rig handles the fisheye/domemaster projection automatically — no manual polar-coordinate (radius/angle) math needed in the shader or scene
  * **Sphere vs. hemisphere** is just OWL's adjustable "dome angle" setting (1–360°) on the camera rig — not a geometry decision you need to model yourself

===== Domemaster Coordinate System =====
  * **Center of the 4096×4096 image (2048, 2048) = zenith** (straight up)
  * **Edge of the inscribed circle (radius 2048) = horizon**, 360° around
  * Corners of the square (outside the circle) = unused, black
  * **Quadrants** (per theatre's handout): Q1 = bottom-left, Q2 = bottom-right, Q3 = top-right, Q4 = top-left
  * **Q1/Q2 boundary (bottom-center of the circle) = audience-front/center**
  * **Q1 = audience-left, Q2 = audience-right** (IT "pretty sure," worth final confirmation)
  * **Top half (Q3/Q4) = behind the audience**

===== Content Placement Guidance (from theatre + OWL's own dome docs) =====
  * Avoid dead center/zenith — geometrically simple but causes neck strain, hardest place for audience to look
  * Avoid the very edge/horizon — peripheral, easy to miss
  * Primary content/action belongs in a ring roughly **30–45° above horizon**, weighted toward the **lower half (Q1/Q2)**
  * Camera motion: **no roll**, minimal/no pitch-down (motion sickness risk), yaw only slow and anchored

----

===== Software Pipeline =====

**Unreal Engine** (Windows) — build the scene normally in 3D (sky, water plane, underwater environment). No dome-shaped geometry needed; you don't manually place content in the flat 4096×4096 canvas.

**OWL Live-Streaming Toolkit — Pro tier (~$350, one-time/perpetual, per machine)**
  * Confirmed via OWL docs + support: 360 camera supports domemaster/fisheye projection directly
  * 360 camera is a **Pro-only** feature (not in Beginner)
  * NDI Sender included in same product, outputs BGRA or UYVY under the SpeedHQ codec (Full NDI only)
  * HX/HX-3 sending is in **alpha** (not needed — theatre confirmed Full NDI is fine)
  * Standard Unreal Sequencer keyframing works normally with the 360 camera (camera moves, transitions)

**Camera/scene logic:**
  * Camera = the "viewer" position; place scene geometry (sky, water plane, underwater world) around it in normal 3D space
  * The 360 camera rig auto-captures everything around itself and outputs the correct domemaster render target — no manual warping
  * Descent = animate the camera moving downward through the water plane's height via Sequencer
  * Rotate the camera rig so world-forward aligns with the theatre's audience-front (Q1/Q2 boundary)

----

===== Network =====
  * **Wired Ethernet required** — Full/SpeedHQ NDI at this resolution needs a stable, high-bandwidth connection; not reliable over Wi-Fi
  * NDI discovery normally works via mDNS on the same subnet; theatre's IT is testing whether an explicit **NDI Discovery Server** is needed on their network
  * Both ends being Windows means Discovery Server (if needed) is configured via **NDI Access Manager** GUI — no workaround needed
  * **Known issue to flag later (not yet raised with IT):** Windows Update KB5063878 has caused NDI drops for some; fix is switching Access Manager's Receive Mode from Auto (RUDP) to Single-TCP

----

===== Quest 2 Preview Setup =====
  * **App:** Dome Viewer (prefrontalcortex/DomeTools) — free, confirmed compatible with Quest 2/3/Pro (Meta App Lab + SideQuest listings both confirm Quest 2 explicitly)
  * Receives NDI streams directly; select via Media Sources > NDI in-app
  * Can also play local files (jpg/png/mp4) placed in ''Download/DomeViewer'' folder — useful fallback with no network needed
  * **Hardware:** Cable Matters 5-Port USB-C Hub On-The-Go — top recommendation from QuestNav's tested adapter list (community-verified for Quest headsets doing standalone Android networking, not PC VR/Link). List is officially scoped to Quest 3/3s; Quest 2 compatibility is a reasonable bet (same Android base) but **not directly confirmed** — test on arrival.
  * Provides Ethernet + power passthrough (keeps headset charged during testing)
  * **Avoid direct PC-to-Quest Ethernet with no DHCP** — a documented Quest firmware bug can prevent the headset from getting a valid IPv4 address in that config. Use a cheap switch/router with DHCP enabled, or Windows Internet Connection Sharing (ICS) on the PC.
  * This setup is unrelated to Oculus Link/PC VR — Quest runs Dome Viewer as a standalone Android app, not as a USB peripheral

----

===== Open Items — Still Need Answers =====
  * [ ] Confirm Q1 = audience-left (IT said "pretty sure," not fully certain)
  * [ ] Exact elevation cutoff angle — full 90° hemisphere, or does their dome stop short of true horizon?
  * [ ] Result of IT's Discovery Server test (mDNS sufficient, or explicit server needed?)
  * [ ] Color/gamma expectations for their projector system
  * [ ] On-site test window before the actual show date
  * [ ] Whether the "green zone" placement guidance = confirmation that bottom half is literally audience-facing (currently an inference from the handout's coloring, not an explicit IT statement)

===== Purchases Needed =====
  * OWL Live-Streaming Toolkit Pro (~$350)
  * Cable Matters 5-Port USB-C Hub On-The-Go (for Quest 2)
  * Ethernet cable(s) + a basic switch/router (if not using PC-side ICS)

===== Resources =====
  * [[https://www.youtube.com/watch?v=9qjdghAZ2-g|demo video of OWL]]