---
title: "Projector Calibration"
description: "Projector calibration workflows using the Python API"
url: https://developer.disguise.one/python-api/guides/calibration/
---

# 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`](/python-api/docs/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`](/python-api/docs/opticalcalibrator) and instead works by directly manipulating [`Projector`](/python-api/docs/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`](/python-api/docs/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`](/python-api/docs/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]` |