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 position of the encoder wheels) to calibrated lens values.

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

Some tracking systems deliver the lens values directly, which means that they have a lens file in 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 like distortion, center offset, nodal offset and focus distance are not always present.

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

We can also override lens values in, for example, Stype using a lens file in Pixotope. All values will replace the corresponding values in the incoming tracking. Tracking often comes with a nodal offset baked into the camera position. 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. Meta contains information about the lens and file; the most important parameter is distortionModel. 

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 psuedo-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.

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",
        "name": "J11ex4.5B_WASF_20814539.lcb",
        "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;"
        }, 
    ]
}
JS

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