---
title: "Tracking"
canonical: "https://documentation.chaos.com/space/ARENA/125243176/Tracking"
format: markdown
---
This page provides information about the Tracking tab in Chaos Arena.
## **Overview**
---
A protocol and additional parameters for the protocol describe camera tracking. There are also tracking offsets that specify the center point of the tracking system and the center point of the tracker itself.
The currently supported protocols are:
- **Mo-Sys F4**
- **OpenTrackIO**
- **FreeD**
- **stYpe HF**
- **EZtrack TCD**
- **OptiTrack NatNet**
- **Vicon**
- **LONET 2**
Additionally, a pre-recorded camera movement can be loaded as an Alembic file when the Protocol is set to **File Replay**.
If the camera tracking hardware is not connected to Arena, the protocol can be set to Simulation, which will play out a pre-recorded camera movement that moves the inner frustum.
Apart from the 3D camera position and orientation, the following lens tracking parameters are supported :
**LONET2 -** *sensor width, sensor height, focal length*
**stYpe** - *sensor width, sensor height, FOV*
**Mo-Sys F4** - *FOV, focus distance*
**OpenTrackIO** - *sensor width, sensor height, focal length, focus distance, F-Number*
**EZtrack** - *sensor width, sensor height, FOV, focal length, focus distance, F-Number (from T-stop)*
The tracking origin in the scene is the pivot point of the projection geometry by default. The actual center point on the stage specified by the tracking system may differ. This is defined by the **Tracking Origin Offset** parameters, as determined by the tracking system; offsets relative to the projection geometry can also be specified if needed. The tracking origin node option can also be used to control the origin in the scene.
The tracking system should ideally provide the position of the camera's **entrance pupil** point (often referred to as the lens **nodal point**). The **entrance pupil** is a virtual point that's usually somewhere inside the lens and corresponds with the correct position of the virtual pinhole camera model. However, some tracking systems provide the camera sensor's position instead of some other point relative to the actual tracker on the camera. This can be corrected using the** *****Camera Offset**** *parameters in the configuration. Orientation offsets of the tracker relative to the camera can also be specified if needed*.* Note that for **stYpe** and **EZtrack*** *this offset should not be required.
##
**General**
---
## **Lens Overrides**
---
Override the lens values coming from the camera tracking system or the 3d scene.
By default, the value for the lens override options is 0, which means override is disabled and the value will be taken from the tracking system. If it provides a positive, non-zero value, the value will be used; otherwise, it will be taken from the scene.
**Sensor Width **
**Sensor Height **
**FOV**
**Focal Length **
**Focus Distance**
**F-Number **
**Horizon Shift – **Horizon shift effect applied to the camera’s inner frustum. Similar to a vertical lens shift effect.
## **Lens Mapping**
---
Lens controllers connected over the **stYpe** or **FreeD** protocols stream raw encoder readings instead of physical lens values. The **Lens Mapping** panel calibrates these raw readings into physical **Focus Distance **and** Focal Length**, with each lens parameter calibrated independently under its own tab. This is essential when using tracking protocols that do not provide pre-calibrated lens data, allowing users to create custom lens profiles for any encoder-supported hardware.
### **Lens Profile File**
A lens profile stores the calibration of all lens parameters in a *.json* file, so a calibrated lens can be reused across sessions.
**Lens Profile File** – Displays the path of the currently loaded lens profile.
**Browse** (**...**) – Opens a lens profile *.json* file.
**Save as** – Saves all lens parameters to a *.json* file.
### **Modifiers**
**Active** – Enables the remapping for the lens parameter. When disabled, the remapper outputs *0*.
**Inverse** – Inverts the mapping, reversing the direction of the encoder readings.
**Soft stop** – Enables soft-stop mode for encoders without physical end stops, such as infinite-roll encoders. The values are softly clamped to the configured range, and the **Set** buttons appear next to the **Near** and **Far** values. If the encoder value moves beyond these limits, the entire range "shifts" to follow the new value while maintaining the same total width (span).
### **Range**
The range defines the near and far raw encoder bounds used to normalize the incoming readings.
**Near** – The nearest, often smallest, raw value of the encoder.
**Far** – The farthest, often largest, raw value of the encoder.
**Set** – Captures the current value as the soft-range near or far bound. The **Set** buttons appear only in soft-stop mode.
**Reset** – Resets **Near** to its maximum value and **Far** to its minimum value, so the range readjusts automatically from the incoming encoder readings. Useful for recalibration.
### **Live values**
The live values are read-only and update in real time as the tracking system streams new encoder data.
**Raw** – The raw encoder value, as received from the tracking system.
**Normalized** – The encoder value normalized to the *0.0*–*1.0* range, based on the **Near** and **Far** values.
**Physical** – The current physical lens value, calculated from the mappings and the **Near** and **Far** values.
### **Mapping**
Mappings define the relationship between normalized encoder values and physical lens values. The remapper interpolates between the mapping points to calculate the physical value for any normalized reading.
**Interpolation** – The interpolation type used to map normalized values to physical values.
**Linear** – Interpolates linearly between the mapping points.
**Cubic** – Interpolates along a smooth cubic curve between the mapping points.
**Normalized** – The current normalized value from the live lens data.
**Physical** – The physical value paired with the normalized value.
**Add Mapping** – Adds a new mapping between the current **Normalized** and **Physical** values. The mapping table lists all mapping points, sorted by normalized value, and each row provides a button to remove the mapping point.
> ℹ️ To set up a lens encoders from scratch follow the steps in this guide - [Setting up raw Lens encoder in Chaos Arena](https://docs-chaos.atlassian.net/wiki/spaces/ARENA/pages/924090403)
## **Tracking Origin Offset**
---
Position and rotation offset of the tracking system relative to the current tracking origin in the configuration (the projection geometry or the tracking origin node if specified).
Тhis is the distance between the **Camera Tracking System Origin** (usually somewhere on the floor) on one hand and the **Tracking Origin Node** (if included in the .vrscene containing the geometry of the LED wall) or the pivot point of the wall geometry (if there is no Tracking Origin Node). If the **Tracking Origin Node** matches the actual tracking system origin perfectly, these offsets should be zero.
## **Camera Offset**
---
Position and rotation offset of the camera's *entrance pupil *and its orientation relative to the tracker's center point and orientation.
This is the distance between the lens nodal point (usually located inside the lens, in front of the sensor) and the pivot point of the tracker, which depends on the camera tracking solution (e.g., stYpe, Mo-Sys, Vicon, etc.).
**Auto-Apply***** –*** If enabled, changes to the offsets, FOV, or camera ID are applied immediately during rendering, without requiring the Apply Configuration button to be pressed.
## **Coordinate System**
---
The coordinate system used for all offsets is *(+X right, +Y forward, +Z up)*. Distances are in centimeters. Rotations are described as *(pan, tilt, roll)* in degrees. Positive pan angle corresponds to a pan to the **right**. Positive tilt angle corresponds to an **upward **tilt. A positive roll angle corresponds to a **clockwise **roll when viewed from behind.
The forward direction for the *Camera Offset *is the **forward (look) direction of the camera**.
The forward direction for the *Tracking Origin Offset* is the **forward direction of the tracking system**, which is not always pointing towards the screen. It depends on the tracking system and how it's calibrated.
## **File Replay**
---
Loads a pre-recorded Alembic file with camera movement.
### **Protocol Settings**
- **AlembicFile **–** **Absolute path to the Alembic file containing the camera animation.
- **CameraID **–** **When the Alembic file was not recorded with Arena, use this override to provide an ID for the camera.
- **CameraName **–** **Name of the camera that is saved in the Alembic file, when omitted the first object will be used.
- **MeterScale **– Meter’s scale of the scene i.e. 1.0 = meters, 0.01 = centimeters, 0.001 = milimeters; Will be ignored when working with Alembic files recorded by Arena.
## **Simulation**
---
Plays a pre-recorded camera movement that moves the inner frustum. This option is useful for testing purposes when camera tracking hardware is missing or not connected to Area.
### **Protocol Settings**
- **CameraID **– ID of the camera sending the packets.
- **X/Y/Z **– Tracking origin in centimeters.
- **FPS – **Generation frequency of the camera tracking frames.
- **Speed – **Multiplier for the camera speed simulation.
## **OptiTrack**
---
The OptiTrack integration differs from most others in that it utilizes a third-party library for connecting to a server, typically the OptiTrack Motive application. Most of the other protocols are simply connectionless UDP listeners that open a network port and wait for data to arrive.
Also, OptiTrack is not specifically a camera tracking system; it's a complete motion capture system. There are various types of objects tracked, including skeletons, rigid bodies, force plates, markers, and others. Currently, the objects implemented for camera tracking are **rigid bodies**. Each rigid body has a unique streaming ID assigned by the server. This streaming ID is used as a camera ID.
### **Coordinate System**
There seems to be a convention in OptiTrack that the coordinate system's forward direction** points away from the screen** (backward when standing in front of the LED wall, for example), rather than into the screen, as is the case with most other systems. This usually causes the tilt and roll to be inverted, i.e., an upward tilt is interpreted as a downward tilt. It can be easily corrected by setting Pan 180 degrees for both the Camera Offset and the Tracking Origin Offset. This effectively rotates the entire coordinate system 180 degrees. Note, however, that all other offsets are still relative to the native coordinate system, meaning that the forward direction is looking away from the screen.
### **Protocol Settings**
- **ConnectionType** – Connection type (0 - multicast, 1 - unicast). Default - multicast.
- **ServerCommandPort **– NatNet server command port. Default - 1510.
- **ServerDataPort **– NatNet server data port. Default - 1511.
- **LocalAddress **– IP address of the localhost where the client application is running. Determines the network to use for the connection to the server. Note that having the actual machine IP seems to be very important. Otherwise, it connects to the server but doesn't seem to receive data.
- **ServerAddress **– IP address of the NatNet server application (normally Motive).
- **MulticastAddress **– Multicast IP address, as specified in the NatNet server. Default - "239.255.42.99".
## **Vicon**
---
The Vicon integration is similar to OptiTrack, using a third-party library to connect to a server, typically the Shogun application.
Vicon is also a full motion capture system. The subject names are used as camera IDs.
### **Protocol Settings**
- **ConnectionType **– Connection type (0 - unicast, 1 - multicast). Default - unicast.
- **LocalAddress **– IP address of the localhost where the client application is running. Determines the network to use for the connection to the server. Used for multicast connections.
- **ServerAddress **– IP address of the DataStream server application (normally Shogun).
- **ServerPort **– Port of the Vicon data stream server. Default - 801.
- **MulticastAddress **– IP address of the multicast group.
- **MulticastPort **– Port of the multicast group. Default - 44801.
## **LONET 2 **
---
LONET 2 contains many fields for camera and lens tracking. Currently, Arena uses only the Camera Transform Data, which includes the camera name, position, orientation, and timecode.
The protocol is tested only with the [Lightcraft Jetset](https://lightcraft.pro/jetset/) app.
### Tracking protocol JSON plugin IDs
---
The protocols are implemented as plugins, and the JSON configuration files store the plugin ID of the selected protocol:
JSON plugin IDs:
- "2023120817" – stYpe
- "2023120818" – FreeD
- "2024020512" – EZtrack
- "2024031564" – OptiTrack
- "2024061116" – Vicon
- "2024101562" – LONET 2
## **Example**
---
> Macro (anchor)
In the example below, using the **Vive Mars** tracking system, the center of the tracker is located at the base of the Vive tracker; therefore, the measurements start from there.
In the example below, you can see how the **Tracking Origin Offset** is used.
The Tracking Origin offset is the distance between the **Tracking Origin Node** (if included in the .vrscene file containing the geometry of the LED wall) and the Camera Tracking System Origin (typically located on the floor). This example assumes that the tracking system's forward direction is pointing towards the screen.
