> 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/calibration-workflows/lens-and-tracking-calibration.md). # Lens & Tracking Calibration {% embed url="" %} *** **Lens & Tracking Calibration** is used when you want to calibrate the lens and the camera tracking alignment in one workflow. This workflow creates a **Lens Profile** and an **Alignment Profile** from the same calibration process. It is intended for moving camera setups where the camera provides position, rotation, zoom, and focus data. {% hint style="info" %} This page only describes workflow-specific best practices. The general Calibration Object setup, Capture Window, capture process, and output handling are explained in the **Using the Calibration Object** section. {% endhint %} *** ## When to Use This Workflow Use **Lens & Tracking Calibration** when the camera is tracked and the lens should be calibrated at the same time. This workflow is useful when the lens, tracking system, and camera image should be solved together as one calibration. #### Typical Use Cases Use this workflow for: * fully tracked cameras * handheld tracked cameras * tripod or dolly cameras with full position and rotation tracking * camera tracking systems that provide position, rotation, zoom, and focus * setups where no valid Lens Profile and Alignment Profile exist yet #### When Not to Use It Do not use this workflow if only part of the setup needs to be updated. Use another workflow instead when: * only the lens needs calibration → use **Lens Calibration** * an existing Lens Profile should only be aligned to tracking → use **Tracking Alignment** * the camera only rotates or behaves like a pan/tilt system → use **Lens & Tracking Calibration (Rotation Only)** * the camera is static → use **Simple Static Calibration** * the setup uses an Axis 2D rail / pole system → use **Axis-Pole Calibration** * Calibration Screens cannot be used → use **Alignment with Markers** *** ## What This Workflow Solves Lens & Tracking Calibration solves the optical lens behavior and the tracking alignment together. #### Lens Profile The workflow creates a **Lens Profile**. The Lens Profile describes the optical behavior of the lens, including lens distortion and zoom/focus-dependent calibration data. This profile can later be assigned to the Camera Object and reused when the same lens setup is used again. #### Alignment Profile The workflow also creates an **Alignment Profile**. The Alignment Profile aligns the incoming tracking data with the real optical camera image. This is needed because the tracking device usually does not sit exactly at the optical center of the camera and may not have the same orientation as the real camera view. #### Optional Calibration Screen Updates The workflow can optionally update the placement, orientation, or shape of Calibration Screens. Only enable this if the Calibration Screens should actually be repositioned. {% hint style="warning" %} If the Calibration Screens are already positioned correctly or already exported to Unreal Engine, a media server, or another external system, disable screen repositioning unless you intentionally want to update the screen placement. {% endhint %} *** ## Required Setup Lens & Tracking Calibration requires a prepared camera image, Calibration Screens, and mapped tracking / lens data. #### Required Inputs The workflow requires: * a **Media Input** with the raw camera image * **Calibration Screens** * a map that provides camera position * a map that provides camera rotation * zoom and focus values as Custom Data * a Calibration Object loaded with **Lens & Tracking Calibration** #### Camera Object and Maps The Calibration Object usually does not read directly from the tracking integration object. Instead, tracking and lens data should be mapped to the Camera Object first. The Calibration Object then references the required map through: ``` Maps → Map List → Input Map ``` For a complete Lens & Tracking Calibration, the map should provide: | Required Data | Map Option | | ------------- | ------------------- | | Position | **Use Pos** | | Rotation | **Use Rot** | | Zoom / Focus | **Use Custom Data** | {% hint style="info" %} Zoom and focus values are handled as **Custom Data**. {% endhint %} #### Calibration Screens Lens & Tracking Calibration uses Calibration Screens as visual references. Make sure that: * the correct Calibration Images are displayed * the Calibration Images are not scaled, cropped, or distorted * all required screens are added to the Calibration Object * the Master Screen is selected if required * the screens are visible from enough camera positions during capture *** ## Important Settings Only the settings that are important for this workflow are listed here. The exact UI setup is explained in the general Calibration Object pages. #### Image Select the Media Input that belongs to the camera being calibrated. The image must be the raw camera signal. #### Maps Add the required map or maps to the Calibration Object. Enable: * **Use Pos** for position data * **Use Rot** for rotation data * **Use Custom Data** for zoom and focus If position / rotation and zoom / focus come from different sources, add multiple maps and enable only the required data from each map. #### Reposition Screens Enable screen repositioning only if the Calibration Screen placement should be updated. Disable it when using already measured, already solved, or already exported Calibration Screens. #### User Outputs Configure the outputs for: * Lens Profile * Alignment Profile * optional Calibration Screen updates Choose whether the profiles should be saved as new profiles, overwrite existing profiles, or be assigned to the Camera Object after calibration. *** ## Capture Strategy This workflow needs varied capture data across both the camera movement volume and the lens range. #### Start with Broad Movement Start with the camera far enough away to see a large part of the setup. Capture data from different positions, heights, distances, and viewing angles. This gives the solver a broad understanding of the relationship between the camera image, tracking data, and Calibration Screens. #### Cover the Shooting Volume Move through the full area where the camera will be used. Include: * center positions * outer boundaries * near and far distances * low and high positions * different rotations The calibration should cover the real production movement range, not only one comfortable camera position. #### Cover Sensor and Screen Areas Capture data so that Calibration Patterns appear across different parts of the camera image. Try to cover: * image center * image edges * image corners * all relevant Calibration Screens * different screen angles and distances This helps the Lens Profile, especially for distortion behavior. #### Capture Zoom and Focus Range For zoom lenses, capture data at important zoom positions. Start with maximum zoom, then add data where the alignment error is greatest. For focus-dependent calibration, start at infinity focus and add stable focus positions where marker detection remains reliable. {% hint style="info" %} For zoom lenses, capture additional data at the lens positions where the real and virtual views show the largest difference. {% endhint %} *** ## Best Practices Good Lens & Tracking Calibration depends on reliable image detection, accurate tracking data, and broad capture coverage. #### Use Raw Tracking and Encoder Values Use raw position, rotation, zoom, and focus values whenever possible. Avoid tracking data where lens distortion, nodal shifts, or zoom/focus-dependent offsets are already applied to the camera transform. Grid Studio needs raw values so it can create its own Lens Profile and Alignment Profile. #### Prefer Broad Coverage Over Many Similar Captures Do not collect many captures from nearly the same camera position. A smaller number of diverse, useful captures is usually better than many repeated captures from one area. #### Check the Solve While Capturing Use the Capture Window feedback to check: * marker detection * map values * reprojection error * sensor coverage * screen coverage * zoom / focus coverage * Solve Engine Camera View alignment Capture more data where the feedback shows missing coverage or visible error. *** ## Common Mistakes Avoid these common problems during Lens & Tracking Calibration. #### Wrong or Processed Image Input The Media Input must be the raw camera image. Do not use an already undistorted, distorted, cropped, scaled, or composited image. #### Wrong Map or Missing Custom Data If the wrong map is selected, the calibration may use the wrong tracking data. If **Use Custom Data** is disabled, zoom and focus values may not be available to the lens calibration. #### Duplicate Map Data Do not enable the same data type from multiple maps unless the workflow explicitly requires it. For example, avoid enabling **Use Pos** on two different maps if only one position source should drive the calibration. #### Screen Repositioning Enabled by Accident If screen repositioning is enabled unintentionally, the workflow may update Calibration Screen placement. This can cause mismatch with external systems that already use the previous screen positions. #### Poor Lens Range Coverage If the result looks good at one zoom or focus position but drifts at another, more data is needed at the weak lens positions. Use the Zoom Focus Steps feedback to find missing or weak areas. *** ## Outputs Lens & Tracking Calibration can create multiple outputs. #### Lens Profile The generated Lens Profile should be saved and assigned to the Camera Object that will use the calibrated lens. #### Alignment Profile The generated Alignment Profile should be saved and assigned to the same Camera Object. The Lens Profile and Alignment Profile work together to align the tracked virtual camera with the real image. #### Calibration Screen Updates If screen repositioning was enabled, check and save the updated Calibration Screen placement only if intended. If the screens are used by Unreal Engine, a media server, or another external system, update or re-export the screen data there as needed. *** ## Before Continuing Checklist Before using Lens & Tracking Calibration, check the following: * The camera is fully tracked with position and rotation data. * Zoom and focus values are available as Custom Data. * The Media Input uses the raw camera image. * Calibration Screens are visible and configured correctly. * The correct maps are selected in the Calibration Object. * **Use Pos**, **Use Rot**, and **Use Custom Data** are enabled correctly. * Screen repositioning is enabled only if screen placement should be updated. * The capture data covers the shooting volume. * The capture data covers the required zoom and focus range. * Lens Profile and Alignment Profile outputs are configured.