> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/camera-calibration/using-the-calibration-object.md). # Using the Calibration Object The **Calibration Object** is the central object used to run camera calibration workflows in Grid Studio. It is separate from the Camera Object. The Camera Object represents the virtual camera in the project, while the Calibration Object is used to configure, capture, solve, and output calibration data. A Calibration Object can be used for different calibration workflows, such as Lens Calibration, Lens & Tracking Calibration, Tracking Alignment, Axis-Pole Calibration, or static camera calibration. {% hint style="info" %} The available settings inside the Calibration Object depend on the selected calibration workflow. Some tools only show a subset of the options described in this section. {% endhint %} *** ## What the Calibration Object Does The Calibration Object brings together all data needed for a calibration workflow. This can include the camera image, tracking maps, Calibration Screens, Measurement Points, existing profiles, output settings, and workflow-specific options. #### Separate from the Camera Object The Calibration Object does not replace the Camera Object. The Camera Object is the object that will later be used in the project, driven by tracking data and calibration profiles. The Calibration Object is used to create or update the calibration data that the Camera Object can then use. #### Workflow Container After adding a Calibration Object to the project, a calibration workflow is loaded into it. The selected workflow defines which settings are shown, which data is required, and which outputs can be created. Examples include: * Lens & Tracking Calibration * Lens & Tracking Calibration (Rotation Only) * Lens Calibration * Tracking Alignment * Alignment with Markers * Axis-Pole Calibration * Simple Static Calibration * Simple Static Calibration with Marker *** ## Load a Calibration Workflow To start setting up a calibration, select the Calibration Object and open the **General** tab. Use the **Load Calibration** button to choose the calibration workflow you want to use. #### Workflow-Specific Parameters After loading a workflow, additional parameters become available in the Inspector. These parameters depend on the selected calibration tool. Some workflows require Calibration Screens. Others require Measurement Points, existing profiles, Camera Objects, Axis 2D objects, maps, or specific output settings. {% hint style="info" %} If a setting described in this documentation is not visible in your Calibration Object, it may not be required by the selected calibration workflow. {% endhint %} *** ## Common Inputs Most calibration workflows use a shared set of input concepts. The exact combination depends on the selected tool. #### Image Provider All calibration workflows require a live image from the real camera. This image usually comes from a **Media Input** object and is selected in the Calibration Object as the image source. The image should be the raw camera signal. Do not use an already undistorted, distorted, cropped, scaled, or composited image. #### Calibration References Calibration workflows need known visual or spatial references. Depending on the workflow, this can be: * **Calibration Screens** * **Manual Markers / Measurement Points** Calibration Screens are used when a Calibration Image can be displayed or placed on a known Reference Surface. Measurement Points are used when measured 3D points are manually referenced in captured camera images. #### Maps and Source Data Moving camera workflows use maps to provide tracking, encoder, or movement data. Maps are usually created on the Camera Object, Axis 2D object, or another target object. The Calibration Object references these maps through: ``` Maps → Map List → Input Map ``` Each map entry can define which parts of the selected map should be used: * **Use Pos** * **Use Rot** * **Use Custom Data** Position and rotation data are used for camera tracking and alignment. Custom Data is used for values such as zoom, focus, encoder values, or other workflow-specific data. #### Existing Profiles and Objects Some workflows use existing calibration data or project objects as inputs. Depending on the tool, this may include: * Camera Object * Lens Profile * Alignment Profile * Axis 2D object * Parent Folder * Calibration Screens * Measurement Points These inputs are selected in the Calibration Object Inspector. *** ## Common Outputs The Calibration Object can create different types of outputs depending on the selected workflow. #### Lens Profiles A **Lens Profile** describes the optical behavior of the lens. It can contain lens distortion, focal behavior, and zoom/focus-dependent calibration data. Lens Profiles can be saved and reused when the same lens and lens setup are used again. #### Alignment Profiles An **Alignment Profile** describes the offset between the incoming tracking data and the real optical camera. It aligns the tracked or moved virtual camera with the real camera image. Alignment Profiles are typically used by moving camera workflows. #### Calibration Screen Updates Some workflows can update the placement, orientation, or shape of Calibration Screens. This is useful when the Calibration Screens are not already positioned correctly in the project. {% hint style="warning" %} Only enable screen repositioning when the Calibration Screen placement should actually be updated. If the screens have already been exported to Unreal Engine, a media server, or another external system, changing their placement may require re-exporting or updating those systems. {% endhint %} #### Axis 2D Calibration Data Axis-Pole Calibration can write calibrated movement data into an **Axis 2D** object. This allows the Axis 2D object to drive its child Camera Object along the learned 3D movement path of the real rail / pole / lift system. #### Camera Object Values Static calibration workflows can write calibration values directly to a Camera Object. This can include camera position, rotation, focal values, or distortion-related values depending on the selected static calibration workflow. *** ## General Calibration Workflow Most Calibration Object workflows follow the same general process. The details are different for each tool, but the overall structure is similar. #### Prepare the Project Before using the Calibration Object, prepare the required project setup. This may include: * Media Input * Camera Object * Tracking Objects * Camera Object maps * Axis 2D object * Calibration Screens * Measurement Points * existing Lens Profiles or Alignment Profiles #### Configure the Calibration Object Create or select a Calibration Object. Load the required calibration workflow. Then assign the required inputs, such as: * Image source * Calibration Screens * Measurement Points * Maps * Camera Object * Axis 2D object * Lens Profile * Alignment Profile #### Open the Capture Window After the Calibration Object is configured, open the Capture Window. The Capture Window is used to collect calibration samples, inspect detection quality, monitor tracking and lens data, and evaluate the solve status. #### Capture and Refine Data Capture data across the required camera movement, zoom range, focus range, and calibration volume. The goal is not to capture many samples from one position, but to collect useful and diverse data across the area where the camera will be used. The Capture Window provides feedback such as: * number of captures * detected Calibration Patterns * tracking state * zoom and focus readout * solve status * reprojection error * sensor coverage * zoom / focus coverage #### Save and Assign Outputs After the calibration result is good, close the Capture Window and let Grid Studio finish the solve. Then save or assign the generated outputs. Depending on the workflow, this may include: * saving a Lens Profile * saving an Alignment Profile * assigning profiles directly to a Camera Object * overriding an existing profile * saving screen reposition output * writing Axis 2D calibration data * writing values directly to a Camera Object * apply screen repositioning *** ## Validating the Result After finishing the calibration, the result should be checked visually. One common way to validate the result is to use the camera **Distortion Viewer**. #### Distortion Viewer The Distortion Viewer can show the real camera image together with the virtual camera overlay. This helps verify whether the real image and the calibrated virtual scene line up correctly. For Calibration Screen workflows, check that the virtual screen geometry aligns with the real Calibration Pattern in the camera image. For Manual Marker workflows, check that Measurement Points line up with their real-world positions. #### Renderer Output After the calibration is validated, the calibrated camera data can be sent to a renderer or external system. This is usually done by adding a map output to the calibrated Camera Object and sending the data to the renderer of choice. Examples include: * Unreal Engine * media servers * render engines * XR / AR systems * other external camera consumers *** ## Before Continuing Checklist Before moving to the detailed Calibration Object setup, check the following: * The correct calibration workflow is known. * A Calibration Object has been added to the project. * The required Media Input exists and shows the raw camera image. * The required Camera Object exists. * Required maps have been created on the Camera Object or other target objects. * Calibration Screens or Measurement Points are prepared. * Existing Lens Profiles or Alignment Profiles are available if required. * Axis 2D objects are prepared if required by the workflow. * You know which outputs should be created, saved, assigned, or overwritten.