Calibrate projectors with TholusOS

Calibration maps projector pixels onto the real projection surface, aligns the images and adjusts overlapping areas. The TholusOS Guided workflow guides you from camera setup to the final video test. Check the result in the venue using the projectors and content intended for actual sessions.

This guide covers camera-based calibration. A single-projector convex-mirror installation can instead use the mirror-map setup in Room → Space → Projection, including the bundled Paul Bourke maps or a custom map. Confirm the selected map on the actual dome; inter-projector edge blending applies when projector images overlap. For the underlying concepts, read edge blending, black levels and fulldome and 360° formats.

Prepare the installation

You need a clear projection surface, installed projectors connected to the Mac, a camera covering the entire useful area, and a test video. Position, focus and zoom must remain stable during calibration. Complete the procedure before admitting an audience: it projects changing light patterns and diagnostic images.

1. Adjust projector position, optical zoom, lens shift and focus first. Check physical coverage and ensure adjacent images overlap where they need to join.
2. Use matching picture presets, light modes, gamma and colour temperature on compatible projectors. Disable dynamic iris, adaptive contrast, automatic dimming and processing that changes the response during measurement.
3. When TholusOS handles geometry, disable projector keystone, warping and internal edge blending. Avoid applying two corrections to the same signal.
4. Disable overscan and check that HDMI signal levels agree throughout the signal chain. A mismatch between video and full levels can crush shadow detail or raise the black floor.
5. Allow the projectors to stabilise. The TholusOS checklist specifies at least 15 minutes before light and black measurements; allow longer if required by the manufacturer or the installation.
6. Mount the camera on a stable support. Keep room lighting consistent with the measurement conditions and remove obstructions between the camera, surface and projectors.

A camera measures the surface it can see. A hidden area, reflection or region outside its field of view requires an installation adjustment before software can usefully measure it.

Open calibration and identify the output

Open Calibration… from the tools menu, or press ⇧⌘K. Select Guided, then Start calibration. This is the profile also described as Guided / consumer in the calibration controls. Other profiles, when visible, may require internal access; this guide follows the ordinary operator workflow.

In the Camera step, select the device and start the preview. If macOS denies access, allow TholusOS in System Settings → Privacy & Security → Camera. Check framing and focus before proceeding.

In Projectors, select the output display and signal tile arrangement. The arrangement describes how the signal reaches the projectors: a 2×2 splitter, for example, receives an image divided into four tiles. This signal layout does not automatically describe the physical projector positions around the venue.

Check which physical projector receives each tile. Enable only the connected slots. Use the black-level bars to inspect the first visible grey levels and adjust projector brightness without erasing near-black detail. Complete the hardware settings checklist.

Capture and align the surface

Capture and Alignment measure camera-to-projector correspondences and create geometric maps. Keep the projection surface clear and all devices stationary until completion. Moving the camera changes the reference used by subsequent measurements.

1. Start the guided capture sequence and wait for completion. If an attempt reports a problem, inspect its cause before repeating it.
2. Calculate alignment from the captured images. Review the result and the useful coverage of the generated maps.
3. In the visible-area step, define the boundary you want to use. When enabling the live view, inspect that boundary on the actual projectors.

Increasing the blend width cannot complete a partial geometric map. If part of the surface is missing, check framing, obstructions, exposure and physical coverage, then repeat the affected stages. Selecting a smaller useful area changes coverage; it does not reconstruct a missing region.

After moving the camera or changing its zoom or framing, return to capture and recalculate geometry before measuring light and black levels.

Adjust seams and dark scenes

Lights and joints adjusts the sum of overlapping images; Black addresses residual light and very dark greys. These are separate tasks because a seam that looks correct on white may remain visible in a night scene.

Generate the blend maps. The consumer workflow offers camera-assisted light optimisation and an explicit base blend choice. If you run the measurement, wait for its result, read the guidance and apply the improvement when it is usable. Finishing a measurement does not automatically apply it.

If you confirm the base blend, inspect uniformity and seams carefully. This preserves geometric blending without claiming a successful light measurement. Changing the fade curve alone does not correct projectors with different brightness or tonal response.

In the black step, inspect both pure black and low grey. Follow the proposed measurement, or explicitly choose visual inspection where appropriate. An operator’s visual judgement remains different evidence from a camera-validated measurement. If low grey is reported as unverified, decide whether to repeat measurement or accept the stated exclusion after assessing its effect on your content.

Use Retouching for small remaining defects. For widespread problems, return to the responsible stage: geometry, light or black level.

Verify and activate the room profile

Completed maps prepare the calibration. Activation also requires the final checks and an operator’s visual confirmation. Quality control uses the camera and newly projected test points; Test and activation verifies the actual display path for the selected session.

1. Restart the camera if needed, without moving it. Complete the guided checks and select Run final check.
2. Resolve blocking issues using the stage indicated by the app. Adjust the diagnosed cause rather than changing unrelated controls.
3. Load the current session into the renderer in the final test and activation stage.
4. Show the calibrated pattern. Inspect coverage, continuous lines and any doubled images.
5. Show the orientation grid. Confirm the front, horizon and orientation appropriate to the venue.
6. Load and play a real video. Inspect bright and dark scenes, fine detail and motion.
7. Confirm the visual inspection and activate the room profile when the result is acceptable.

The app checks that a real video frame reaches the calibrated renderer. That software check does not by itself measure optical quality on the dome. Inspection of the physical surface, including from audience positions, remains part of acceptance.

Keep the result and investigate problems

Keep the complete session folder and identify the active profile before operating the venue. In Room → Space → Projection, select Open projection panel and inspect calibration-map and room-profile status. Loading a folder does not automatically activate a verified session.

Symptom	First useful check
The desktop appears instead of the pattern	Output display, splitter layout and whether the renderer has taken the output
Part of the surface stays black	Warp coverage, visible area, camera framing and obstructions
Doubled lines at a seam	Geometric alignment and device movement after capture
A bright seam appears only in dark scenes	Black-level adjustment and room reflections
Brightness pulses	Dynamic iris, adaptive contrast, light modes and camera automation
The profile becomes unavailable after installation changes	Agreement between the session, displays, slots and current geometry

For support, export calibration diagnostics and record projector models, signal connections, camera, changed settings and the test content. Continue with media playback and app configuration for everyday operation.