> 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/project-setup/camera-rails-and-2d-axis-systems.md). # Camera Rails and 2D Axis Systems An **Axis 2D** object is used for camera systems where the camera movement is based on two movement values, such as a rail position and a pole or lift position. This is useful for camera rigs where the camera is not directly tracked as a complete 3D transform, but where separate movement values describe the mechanical position of the system. Typical examples include: * rail and lift systems * camera movement systems with two mechanical axes * systems where one value describes the camera position along a rail * systems where another value describes the lift, or vertical movement The Axis 2D object is calibrated with the **Axis-Pole Calibration** workflow. {% hint style="info" %} The Axis 2D object does not simply move the camera in a flat two-axis grid. During calibration, Grid Studio learns how the real camera system moves in 3D space. {% endhint %} *** ## What Axis 2D Does The Axis 2D object receives two movement values and uses them to drive a calibrated 3D camera movement. Before calibration, these values are only input values. They do not yet describe the real 3D camera movement accurately. After calibration, the Axis 2D object contains the learned movement behavior of the real system. #### Two Movement Inputs The Axis 2D object uses two mapped input values. These values typically represent: * rail / position * pole / lift The values do not need to be metric. They only need to represent the movement along each axis in a stable and repeatable way. Grid Studio normalizes and calibrates these values during the Axis-Pole Calibration workflow. #### Calibrated 3D Movement The Axis 2D object does not only interpolate two flat values. During calibration, Grid Studio learns how the real camera system moves through 3D space. This can include real-world mechanical behavior such as: * a rail that is not perfectly straight * a rail that is slightly twisted along its path * a pole or lift that leans forward or backward at different positions * curved movement paths * mechanical bending * small alignment errors in the physical rig After calibration, these movement characteristics are stored in the Axis 2D object and used to drive the child Camera Object correctly. *** ## Object Structure An Axis 2D setup usually consists of an **Axis 2D** object and a **Camera Object** placed as a child below it. The Axis 2D object handles the calibrated rail / pole movement. The Camera Object handles the camera-specific data such as pan, tilt, zoom, and focus. #### Axis 2D Object The Axis 2D object is created in the Project Tree. It receives the two movement values through a map or multiple maps. These values describe the mechanical state of the rig, for example where the camera is on the rail and how far the pole or lift is extended. #### Camera Object as Child The Camera Object should be placed as a child of the Axis 2D object. This structure allows the Axis 2D object to move the camera through its calibrated 3D movement path, while the Camera Object receives the rotation head and lens values. A typical structure looks like this: ``` Axis 2D Camera Object ``` {% hint style="info" %} The Camera Object should be placed below the Axis 2D object. The Axis 2D object handles the calibrated movement path, while the Camera Object handles rotation head and lens data. {% endhint %} #### Camera Object Data The Camera Object usually receives a separate map for the rotation head and lens values. Typical mapped values are: * pan * tilt * zoom * focus Zoom and focus are used as lens encoder values for lens calibration and lens profile evaluation. *** ## Map Setup The Axis 2D object and the Camera Object usually use different maps. The Axis 2D object receives the rail / pole movement values. The Camera Object receives the rotation head and lens values. #### Axis 2D Map The Axis 2D object has a map for the two movement values. These values are used as the input for the calibrated movement model. The source values can come from a protocol or integration that provides axis-like movement values. Inside the map setup, the required source axes can be selected and assigned to the Axis 2D movement inputs. #### Rail / Position Value The rail / position value describes the position of the camera along the rail or horizontal movement path. This value does not need to be measured in meters. It only needs to change consistently and repeatably as the camera moves along the rail. #### Pole / Lift Value The pole / lift value describes the second movement axis. This could be a pole height, lift position, vertical movement, or another mechanical movement value. This value also does not need to be metric. Grid Studio uses the calibration process to learn how both input values relate to the real 3D movement of the camera. *** ## Camera Object Map The Camera Object below the Axis 2D object receives the tracking data for the rotation head and lens. This is usually done with a normal Camera Object map. #### Rotation Head Data The rotation head data usually contains: * pan * tilt These values describe the orientation of the camera head. #### Lens Encoder Data The Camera Object map should also provide lens encoder values when the workflow needs to calibrate or evaluate a lens profile. The relevant values are usually: * zoom * focus {% hint style="info" %} Iris values are not required for the camera calibration workflows described here. The relevant lens values are usually **Zoom** and **Focus**. {% endhint %} *** ## Axis 2D in the Calibration Object For Axis-Pole Calibration, the Calibration Object needs to reference the Axis 2D setup. The Calibration Object links to the Axis 2D object and uses the mapped data from the Axis 2D object and the child Camera Object during calibration. #### Linking the Axis 2D Object In the Calibration Object, select the Axis 2D object that should be calibrated. \[Screenshot: Calibration Object with Axis 2D object linked] The calibration workflow uses this Axis 2D object as the movement system that should receive the calibrated movement data. #### Maps in the Calibration Object The Calibration Object also needs access to the required maps. This includes: * the map on the Axis 2D object for rail / pole movement values * the map on the Camera Object for pan / tilt / zoom / focus values These maps are selected in the **Maps** section of the Calibration Object. Each map entry can enable the required data using: * **Use Pos** * **Use Rot** * **Use Custom Data** For Axis 2D workflows, movement and encoder values may be handled as Custom Data, depending on the map and source setup. {% hint style="warning" %} Make sure the Calibration Object references the correct Axis 2D object and the correct maps. If the wrong maps are selected, the calibration may use incorrect movement, rotation, or lens values. {% endhint %} *** ## Axis-Pole Calibration The **Axis-Pole Calibration** workflow calibrates the complete camera movement system. It can solve more than just the Axis 2D movement path. Depending on the setup, Axis-Pole Calibration can create: * calibrated Axis 2D movement data * a Lens Profile * an Alignment Profile for the Camera Object * Calibration Screen placement updates, if screen repositioning is enabled This means the workflow can calibrate the complete system in one process. #### Axis 2D Movement Calibration The calibration process writes the learned 3D movement behavior into the Axis 2D object. After calibration, the Axis 2D object can use its two input values to drive the child Camera Object along the calibrated 3D movement path. #### Lens Profile Creation Axis-Pole Calibration can also create a complete Lens Profile. This requires valid zoom and focus values from the Camera Object map. The Lens Profile describes the optical behavior of the lens across the captured zoom and focus positions. #### Alignment Profile Creation Axis-Pole Calibration can create an Alignment Profile for the Camera Object. The Alignment Profile aligns the camera tracking, rotation head, and calibrated movement system with the real camera image. {% hint style="info" %} Axis-Pole Calibration can calibrate the movement model, the lens, and the camera alignment together. This makes it suitable for complete rail / pole / head systems where the full camera behavior needs to be solved as one system. {% endhint %} *** ## Why Calibration Is Required An Axis 2D object cannot accurately drive the camera before it has been calibrated. Before calibration, Grid Studio only knows the input values. It does not yet know how those values correspond to the real camera position in 3D space. #### Before Calibration Before calibration, the Axis 2D object has no accurate movement model. The input values may change correctly, but Grid Studio does not yet know: * where the camera is in 3D space * how the rail is positioned * how the pole or lift behaves * whether the rig is bent, twisted, or curved * how the movement affects the camera position #### After Calibration After calibration, the Axis 2D object has learned the real movement behavior from the captured samples. It can then use the rail / pole input values to calculate the correct camera movement. This calibrated movement is used to drive the child Camera Object. {% hint style="warning" %} Do not expect an Axis 2D object to produce correct camera movement before it has been calibrated. The calibration process is required to create the movement model used by the object. {% endhint %} *** ## Mechanical Imperfections Real camera movement systems are rarely perfect. A rail may not be perfectly straight. A pole may tilt slightly depending on its position. A lift may bend under load. A curved path may not follow a simple mathematical line. Axis 2D calibration is designed to learn these real-world behaviors. #### Rails and Curves The calibrated movement can account for rails that are: * slightly curved * not perfectly straight * not perfectly level * slightly rotated along the movement path #### Pole and Lift Behavior The calibrated movement can also account for pole or lift behavior such as: * forward or backward tilt * bending * non-linear movement * small mechanical offsets #### Why This Matters This is important because the camera image is affected by the real physical movement of the camera. Even small mechanical differences can become visible in AR, virtual production, or camera overlay workflows. By learning the real movement path, Grid Studio can drive the virtual camera more accurately. *** ## Required Setup for Axis-Pole Calibration Before using Axis-Pole Calibration, the required objects, maps, and references must be prepared. #### Required Objects A typical Axis-Pole Calibration setup requires: * an **Axis 2D** object * a **Camera Object** as child of the Axis 2D object * a Calibration Object configured for Axis-Pole Calibration * Calibration Screens #### Required Maps The setup usually requires: * a map on the Axis 2D object for rail / position and pole / lift values * a map on the Camera Object for pan / tilt / zoom / focus values The Calibration Object must reference the required maps in its **Maps** section. #### Required Image Input Axis-Pole Calibration also requires a live camera image. This is provided through a **Media Input** object and selected in the Calibration Object. #### Required Calibration References Axis-Pole Calibration uses Calibration Screens as visual references. The Calibration Screens must be visible in the camera image during the captured samples. *** ## Before Continuing Checklist Before starting Axis-Pole Calibration, check the following: * An **Axis 2D** object has been created. * The Camera Object is placed as a child of the Axis 2D object. * The Axis 2D object receives rail / position and pole / lift values through a map. * The Axis 2D input values change consistently and repeatably. * The input values do not need to be metric, but they must represent the real movement. * The Camera Object receives pan / tilt / zoom / focus values through its own map. * The Calibration Object links to the correct Axis 2D object. * The Calibration Object references the correct maps in the **Maps** section. * A Media Input is selected as the raw camera image source. * Calibration Screens are available and visible to the camera. * Zoom and focus values are available if a Lens Profile should be created. * The workflow is configured to create the required Lens Profile and Alignment Profile.