# Dome Projection

This guide covers setting up Exaplay 3 for dome projection — full-dome digital planetariums, immersive art domes, inflatable event domes, and simulation domes.

## Dome Projection Basics

A dome screen is a hemispherical surface. A standard flat-screen projector cannot illuminate it correctly without a special optical element and geometric correction:

| Approach                     | How it works                                                                        | Best for                                                      |
| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Single fisheye projector** | One projector with a fisheye lens illuminates the entire dome from below the centre | Small domes (≤ 8 m), inflatable domes, mobile setups          |
| **Multi-projector ring**     | 4–6 standard projectors arranged around the dome, edge-blended at the joins         | Large permanent domes (> 8 m), planetariums, simulation domes |

***

## Part 1 — Single Fisheye Projector Setup

### Hardware requirements

* One projector with a **180° fisheye projection lens**
* Projector positioned at the dome's **tilt point** (below centre, angled up)
* Ensure the projector's lens covers the full dome with a single image

### Step 1.1 — Set up the Output

1. Open **Config → Outputs → + Add Output**.
2. Set resolution to the projector's native resolution (typically **2048 × 2048** square for dome, or **4096 × 4096** for higher quality).
3. Enable the output on the projector's display.

> **Tip:** Most dome content is created in a **square aspect ratio** (1:1) — the fisheye lens handles the mapping to the dome surface. Use a 2K or 4K square framebuffer for best quality.

### Step 1.2 — Load Fisheye Calibration (if using VIOSO)

If your fisheye projector has a VIOSO calibration file:

1. Open **Config → Outputs → Load Warp File**.
2. Select the `.vwf` file from VIOSO Calibrator.
3. Toggle **Warp Enable** on.

If you don't have a VIOSO calibration file, use the **Manual Warp Editor** to do a rough alignment (see below).

### Step 1.3 — Manual Warp Adjustment

1. Open **Config → Outputs → Edit Warp**.
2. Use a test pattern (cross-hatch or grid) as the output content.
3. Move the control points on the grid to align the projected image with the dome seam.
4. Use **arrow keys** for fine adjustment (0.01 steps) and **Shift + arrows** for coarse (0.1 steps).
5. Switch interpolation to **Bicubic** for smoother warping on a curved surface.

***

## Part 2 — Multi-Projector Ring Setup

For large domes, a ring of projectors each covers a \~90° sector of the dome, with a 15–25% overlap at the joins.

### Hardware Layout Example (4-projector ring)

```
          ┌──── North projector (0°)
          │
West ─────┼───── East
(270°)    │     (90°)
          │
          └──── South projector (180°)

Each projector: standard lens, angled up at ~30° elevation
Each sector: ~120° wide (with 30° overlap on each side)
```

### Step 2.1 — Add One Output per Projector

1. Open **Config → Outputs**.
2. Add one output per projector (e.g. Output 1: North, Output 2: East, etc.).
3. Set each output's resolution to the projector's native resolution (1920×1080 or 1920×1200 for standard dome projectors).
4. Assign each output to a **separate display port** on the Exaplay PC's GPU.

### Step 2.2 — Calibrate with VIOSO AutoAlign

For large permanent domes, VIOSO AutoAlign is the professional choice:

1. Connect a calibration camera (e.g. Canon DSLR with a fisheye lens) to the Exaplay machine.
2. Go to the **Auto Calibration** view (`http://<ip>:8123/autocalibration`).
3. Follow the on-screen wizard — VIOSO fires structured-light patterns at each projector in sequence.
4. The wizard produces a `.vwf` file for each projector automatically.
5. Load each `.vwf` into its respective output in **Config → Outputs**.

For full details see [Projection Mapping & Warp/Blend](/v3/features/projection-mapping.md).

### Step 2.3 — Manual Edge Blend Adjustment

After loading calibration files, fine-tune the edge blend:

1. Open **Config → Outputs → Edge Blend** for the first output.
2. Increase **Blend Width** on the overlapping edge until the join becomes invisible.
3. Adjust **Gamma Curve** — dome surfaces scatter light differently; a lower gamma (e.g. 1.8) often gives a better blend on fabric domes.
4. Repeat for all overlapping edges.

***

## Part 3 — Dome Content

### Fulldome Format

Dome content is typically delivered in **fulldome format** — a 360° circular image inside a square frame, representing a top-down or angular view of the dome hemisphere:

```
┌─────────────────────────────────┐
│         (black corners)         │
│      ┌─────────────────┐        │
│      │  Dome content   │        │
│      │  (circle inside │        │
│      │   the square)   │        │
│      └─────────────────┘        │
│         (black corners)         │
└─────────────────────────────────┘
```

Standard fulldome resolutions:

* **2K fulldome:** 2048 × 2048 px (small domes, real-time)
* **4K fulldome:** 4096 × 4096 px (medium/large domes)
* **8K fulldome:** 8192 × 8192 px (permanent planetariums — requires high-end GPU)

> **Codec recommendation:** Use **HAP Q** for 4K fulldome content — it provides GPU-accelerated decode with no CPU bottleneck. At 8K, consider splitting the content across two clips on separate tracks and outputs.

### For Multi-Projector Setups

Each projector receives a pre-rendered **sector slice** of the fulldome image. Ask your content creator to export the dome content as individual slices matching each projector's coverage angle and resolution, or use VIOSO's pixel-mapping to project the full equidistant image across all outputs automatically.

***

## Part 4 — Audio for Dome

Immersive domes typically use **ambisonic** or **multichannel spatial audio** to match the 360° visual experience.

1. Open **Config → Audio Settings**.
2. Select an ASIO interface with enough output channels (8+ for immersive audio).
3. Route each audio channel to the correct speaker position in the dome.
4. In the Timeline, use separate audio tracks per speaker group (front, left, right, rear, top).

See [Audio](/v3/features/audio.md) for ASIO routing details.

***

## Part 5 — Show Operation

### Cue-Based Shows (Planetarium Programs)

1. Build the programme as a composition with the full show timeline.
2. Create cues at each programme segment for the presenter to advance the show manually.
3. Use the **Operator Control View** (`/control`) on a presenter tablet.

### Continuous Loop (Art Installation)

1. Set the composition to **Loop: ∞ Infinite**.
2. Configure the Scheduler to start the loop when the venue opens and fade to black when it closes.
3. Enable Auto-Heal for unattended operation between shows.

### Live Presenter Mode

For a live presenter performing under the dome (narrator, musician):

1. Set up NDI or a capture card as a live input if you want to feed camera footage of the presenter into the dome content.
2. Create a dedicated **PRESENTER** track in the composition — drag the NDI source onto it.
3. In the CueList, add a cue that enables the presenter track and another that hides it.

***

## Part 6 — Performance Considerations

| Factor  | Recommendation                                                                |
| ------- | ----------------------------------------------------------------------------- |
| GPU     | NVIDIA RTX 3080 / 4080 or better for 4K fulldome; 4090 for 8K                 |
| CPU     | 8+ cores; HAP decoding is GPU-bound but CPU handles decompression metadata    |
| RAM     | 32 GB minimum; 64 GB for multi-projector 8K setups                            |
| Storage | NVMe SSD for content drives; > 2 GB/s read speed for 4K HAP Q                 |
| Network | Gigabit Ethernet if using NDI live inputs inside the dome                     |
| Cooling | Good airflow is essential — GPU and CPU run at near 100% during dome playback |

Use the **Diagnostics Panel** in the Control View to monitor GPU, CPU, RAM, and VRAM usage during the show.

***

## Summary Checklist

**Single-projector fisheye:**

* [ ] Square output resolution configured (2K or 4K)
* [ ] Fisheye warp calibration loaded or manual warp adjusted
* [ ] Fulldome content format confirmed (circular image in square frame)

**Multi-projector ring:**

* [ ] One output per projector, each assigned to correct display
* [ ] VIOSO AutoAlign calibration run and .vwf files loaded
* [ ] Edge blend width and gamma tuned per overlapping edge
* [ ] Content delivered as sector slices (or VIOSO pixel-mapped)

**Both setups:**

* [ ] HAP or HAP Q codec used for all dome content
* [ ] ASIO multichannel audio routing configured
* [ ] Cue list built for show navigation
* [ ] Diagnostics Panel checked during full-load test
* [ ] Auto-Heal enabled (for unattended dome loops)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.exaplay.one/v3/workflows/dome-projection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.