Lens files in Pixotope

How lens files are applied

Here we define the term "lens values" as values describing the lens properties Field of View (FOV), distortion, center offset, nodal offset and focus distance.

Lens files convert physical lens information (the rotation of the zoom and focus rings on the lens barrel) to calibrated lens values. The position is generated by encoder wheels, either internally within the lens, or using external lens encoder wheels.

The lens file is created by performing a lens calibration procedure.

Some tracking systems deliver all the lens values directly, which means that they have a lens file within their system (e.g. Stype, Ncam, Mo-Sys, SMT Trackman, Trackmen X-Cito). Be aware that not all lens files contain the same information. Most lens files have Field of View (FOV) values; values for distortion, center offset, nodal offset and focus distance are not always present.

Other tracking protocols such as FreeD only deliver lens encoder values, which means that a lens file is required somewhere else in the tracking pipeline to generate lens data. When using FreeD, we must apply a lens file in Pixotope in order to convert the zoom/focus encoder values in the FreeD stream into lens values.

We can also override lens values in the tracking data stream, for example, Stype, by selecting a lens file in Pixotope. By doing this, the values in the tracking stream will be replaced by values read from the lens file in Pixotope.

Tracking data may come with a nodal offset baked into the camera position e.g. Ncam. In this case, the nodal offset from the lens file must not be applied on top of that.

Pixotope lens file format

The lens file is a json file with two sections, meta and curves. The filename ends with .cts.

Meta

The meta section exists to provide general information about the lens file. The tracking server will read the following parameters.

• distortionModel, a string naming the distortion model to set when applying the lens file.
• encoderLimits, when present these can be used as default values for encoder limits. Within the encoderLimits object the recognized limits are ZoomEncoderOut, ZoomEncoderIn, FocusEncoderFar, FocusEncoderNear. The example below has all of these limits present.

Curves

Curves contains the actual lens data. It is an array of objects that each have the keys type, header and data. Type specifies the interpolation mode, header what the numbers in the data represent and data is the actual lens data. If two curves of the same value are added, the latter overwrites the first when the file is used by the tracking server.

The data portion of the curve is encoded in a pseudo-csv format. It is a string with data points which are separated by semicolons (;), and values for a point are separated by commas (,). See below for an example.

"ENCODER_A1,ENCODER_B1,VALUE1;ENCODER_A2,ENCODER_B2,VALUE2;ENCODER_A3,ENCODER_B3,VALUE3;..."

Starting from CTS released with Pixotope 1.3, it is also possible to encode the data as pure json arrays of arrays. The same data would then be:

[[ENCODER_A1, ENCODER_B1, VALUE1], [ENCODER_A2, ENCODER_B2, VALUE2], [ENCODER_A3, ENCODER_B3, VALUE3], ... ]

Encoder values in the lens file are normalized between 0.0 and 1.0, which correspond to the outer limits of the lens movement. By normalization we refer to reducing the raw encoder values to fractional position between the encoder limits. For this the lower limit is zoom-wide or focus-far, and the upper limit is zoom-tele or focus-near. As an example, focus encoder position 15 in a lens with focus far at focus encoder 5 and focus encoder near at 105 gives a normalized focus encoder value of 0.1.

Curve type can be CONSTANT, LINEAR, or BILINEAR, depending on whether they are using zero, one or two encoder values. Below is an example lens file with a mixture of curves.

{
    "meta":
    {
        "version" : "1.0",
        "distortionModel": "opencv",
        "encoderLimits": {
            "ZoomEncoderOut": 0,
            "ZoomEncoderIn": 65536,
            "FocusEncoderFar": 0,
            "FocusEncoderNear": 65536
        },
        "name": "J11ex4.5B_WASF_20814539.xml",
        "serial number" : "12345678",
        "created with camera":
        {
            "name": "Sony HDC 2400",
            "ccd width mm": "9.6",
            "ccd height mm": "5.4"
        },       
        "date": "25.06.2019",
        "creator": "Name Nameson",
        "Notes": "Unverified nodal offset. No focus curve",
    },
    "curves":
    [
        {
            "type": "LINEAR",
            "header": "ZOOM_ENCODER, FOVV",
            "data": "0.00000,37.71900;0.05874,34.10060;0.11748,30.53390;0.17622,26.97050;0.23496,23.56210;0.29370,20.35990;0.35244,17.39980;0.41118,14.69850;0.46992,12.27150;0.52866,10.13430;0.58740,8.39720;0.64615,6.83372;0.70488,5.50513;0.76363,4.39923;0.82237,3.65276;0.88111,2.97513;0.93985,2.42054;0.99859,2.03200"
        },
        {
            "type": "LINEAR",
            "header": "ZOOM_ENCODER, NODAL_OFFSET",
            "data": "0.0,16.764;0.2945,11.43;0.5449,2.54;0.7476,-6.8580000000000005;1.0,-22.86"
        },
        {
            "type": "LINEAR",
            "header": "FOCUS_ENCODER, FOCUS_DISTANCE",
            "data": "0.00000,59.7408;0.04762,65.6685504;0.09524,69.3133488;0.14286,72.9581472;0.19048,77.234796;0.23810,81.5464968;0.28571,87.0780072;0.33333,93.1572432;0.38095,100.1255808;0.42857,107.3575704;0.47619,118.7601384;0.52381,131.9476152;0.57143,145.819368;0.61905,166.6762224;0.66667,193.8378648;0.71429,227.10038400000002;0.76190,275.9549472;0.80952,376.1774544;0.85714,599.2386288;0.90476,864.6883392;0.95238,1332.9489216000002;1.00000,3048.0"
        },
        {
            "type": "LINEAR",
            "header": "ZOOM_ENCODER, K1",
            "data": "0.00000,-0.04950;0.00166,-0.04950;0.19823,-0.10960;0.34812,-0.08570;0.63760,-0.08570;0.78470,-0.00000;1.00000,-0.00000"
        },
        {
            "type": "LINEAR",
            "header": "ZOOM_ENCODER, K2",
            "data": "0.00000,0.25390;0.19406,-0.00000;0.34812,0.04460;0.48043,0.05050;0.63760,0.05050;0.78470,-0.03370;0.88382,-0.00000;1.00000,-0.00000"
        },
        {
            "type": "CONSTANT",
            "header": "FOCUS_DISTANCE",
            "data": "300"
        }, 
        {
            "header": "ZOOM_ENCODER, FOCUS_ENCODER, FOVH", 
            "type": "BILINEAR", 
            "data": "0.0,0.0,68.04;0.0,1.0,71.63;0.0992673992674,0.0,51;0.0992673992674,1.0,50.83;0.200366300366,0.0,39.05;0.200366300366,1.0,39.07;0.323443223443,0.0,29.49;0.323443223443,1.0,29.06;0.473626373626,0.0,19.4;0.473626373626,1.0,20.65;0.610622710623,0.0,14.91;0.610622710623,1.0,14.34;0.765201465201,0.0,8.12;0.765201465201,1.0, 9.115407347949546;0.999633699634,0.0,3.88;0.999633699634,1.0, 4.882818845174979;"
        }, 
    ]
}

Interpolation types

• CONSTANT
  • Encoder value not used.
• LINEAR
  • Either the focus or zoom encoder is used.
• BILINEAR
  
  • Points must form a perfect grid.
  • Focus and zoom encoder values are used.

Recognized keys

These keys (names) are recognized by CTS when reading lens files. Some parameters may be ignored by the selected lens distortion model.

• ZOOM_ENCODER
• FOCUS_ENCODER
• FOVH
  • degrees
• FOVV
  • degrees
• FOCUS_DISTANCE
  • cm
• K1
• K2
• K3
• P1
• P2
• DISTORTED_FOCAL
• PROJECTION_AREA_WIDTH
• PROJECTION_ASPECT_RATIO
• DCX
• DCY
• NODAL_OFFSET
  • cm
  • positive is in front of camera