Projector Calibration in Python

This guide explains how to use the Disguise Python API for projector calibration, covering the three main workflows: OmniCal, QuickCal, and Manual Calibration. These systems are used to align projectors in a 3D scene, ensuring that the projected image accurately maps onto physical and virtual objects.

---

Calibration Systems Overview

Disguise offers three distinct systems for projector calibration, each suited to different production needs:

1. OmniCal (Automated Calibration): A fully automated, camera-based system that uses observations of the real world to calibrate projectors. It’s the most advanced and hands-off method, ideal for complex setups where precision is key. In the Python API, this is managed through the OpticalCalibrator resource.

2. QuickCal (Semi-Automated Alignment): A workflow for manually aligning 2D pixel coordinates from a projector’s output to known 3D points in the scene. This is useful for making quick adjustments without running a full automated calibration, especially when objects or projectors have moved slightly.

3. Manual Calibration: This involves directly manipulating a projector’s intrinsic and extrinsic properties, such as lens shift, throw ratio, and position. It is often used for fine-tuning or in situations where camera-based calibration is not feasible. This can also be used in conjunction with feed warping for precise control.

---

OmniCal: Automated Projector Calibration

OmniCal is Disguise’s camera-based calibration system. It automates the process of capturing data from the environment and calculating the correct alignment for projectors.

Typical OmniCal Workflow:

1. Access the OpticalCalibrator: The main entry point for all OmniCal operations is the opticalCalibrator resource.
2. Configure the Plan: The OptiCalStagePlan holds all the settings for the calibration, including which cameras and projectors to use.
3. Run Calibration: The requestCalibrate() method starts the automated calibration process. This returns an OptiCalTask that can be monitored for progress.
4. Review Results: Once the task is complete, the results are available in the report and result properties.

Goal	Python
Access the OmniCal system	omnical = Resource.opticalCalibrator
Get the current stage plan	plan = omnical.plan
Get calibration settings	settings = plan.calibrationSettings
Start an automated capture	task = omnical.requestCapture()
Start a full calibration	task = omnical.requestCalibrate()
Check if a task is running	is_running = task.running()
Get task progress	progress = task.progress() (returns 0.0 to 1.0)
Check if a task was successful	was_successful = task.success()
Get the calibration report	report = omnical.report
Get the calibration result	result = omnical.result

---

QuickCal: Manual 2D-to-3D Alignment

QuickCal is a workflow for aligning known 3D points to 2D pixel coordinates in a projector’s output. It’s a manual process but faster than a full OmniCal run. It does not use an OptiCalStagePlan and is instead managed through a ManualAlignmentPlan.

Typical QuickCal Workflow:

1. Access the Manual Alignment Plan: The workflow is managed through a ManualAlignmentPlan resource.
2. Select Projector and Points: In the Disguise UI, select the projector and the 3D reference points you want to align.
3. Adjust Pixel Coordinates: For each point, adjust the 2D pixel coordinates in the projector’s output to match the 3D point’s position in the physical scene.
4. Apply the Alignment: Once all points are aligned, the new calibration is applied to the projector.

While the core QuickCal workflow is performed in the UI, you can access and modify alignment data via Python:

Goal	Python
Access the manual alignment plan	manual_plan = Resource.ManualAlignmentPlan
Get alignment data for the plan	alignment_data = manual_plan.alignmentData
Get QuickCal view settings	quick_align_settings = manual_plan.alignmentSettings
Add an alignment coordinate	alignment_data.addAlignmentCoordinate(...)

---

Manual Calibration: Direct Projector Control

Manual calibration allows you to directly edit a projector’s properties. This is useful for fine-tuning or when you need to match a specific physical setup without camera-based calibration. This workflow does not involve the OpticalCalibrator and instead works by directly manipulating Projector resources.

Manual Calibration Workflow:

1. Access the Projector: Get the desired projector object from the stage. You can access all projectors via stage.projectors.
2. Get the ProjectorConfig: Each projector has a calibration property which is a ProjectorConfig object that holds its settings.
3. Modify Properties: Change the values of properties like lensShift, throwRatio, position, and rotation.
4. Apply Changes: The changes are applied directly when you set the properties on the ProjectorConfig object.

Goal	Python
Get a projector from the stage	proj = stage.projectors[0]
Access the calibration config	proj_config = proj.calibration
Set the lens shift	proj_config.lensShift = [0.1, -0.05] # [horizontal, vertical]
Set the throw ratio	proj_config.throwRatio = 1.5
Set the position	proj_config.position = [1.0, 2.5, -3.0] # [x, y, z]
Set the rotation	proj_config.rotation = [0, 45, 0] # [yaw, pitch, roll]