Lambdatracker Config Lua API

This document describes the config file API for the lambdatracker. Configuration is acheived by creating a Lua config file and passing it as the single argument to the lambdatracker executable. An embedded lua interpreter parses and executes the commands within the file in order to correctly set up the cameras and define device patterns. The configuration functions are within the "LT" namespace. Those functions are listed below:

Device Configuration

These functions define tracked device patterns. Devices are defined by three patterns, one base and two alternates. Alternate patterns are associated with states of the device. For example, a device with "button 1" pressed might illuminate its first alternate pattern, with "button 2" pressed, it might illuminate its second alternate pattern, and with no buttons pressed, it would illuminate its base pattern. These patterns are translated into states for the device. Vertecies in the patterns are referred to in the API as "blips." (I know, It's silly.)

devref = add_device()

Adds a new device.

Returns:

devref: a handle to the new device

add_base_blip(devref, blip_x, blip_y)

Adds a new vertex to the base pattern of the device. Any number of vertecies can be used to define a pattern, however for performance and reliability, it is best to stick with unique 3 vertex patterns.

Arguments:

devref: handle to the device
blip_x, blip_y: coordinates of the vertex

add_alt[12]_blip(devref, blip_x, blip_y)

Adds a new vertex to an alternate pattern of the device (either add_alt1_blip or add_alt2_blip). Any number of vertecies can be used to define a pattern, however for performance and reliability, it is best to stick with unique 3 vertex patterns.

Arguments:

devref: handle to the device
blip_x, blip_y: coordinates of the vertex

Camera Configuration

These functions define the camera model that is used in the tracker for each camera. The purpose is to generate a unified camera coordinate space in which each camera's pixel buffer is corrected for distortion and correctly transformed relative to the root camera. The lower left pixel of the root camera's buffer sits at 0, 0 in this coordinate space.

Currently the root camera is defined as the first camera instantiated by the tracker at runtime (not necessarily the first camera defined in the config script. Instead this will be the first camera on the bus of the root node of the tracking cluster.)

camref = add_camera(width, height, snum, hostname)

Adds a new camera.

Arguments:

width: camera buffer width in pixels
height: camera buffer height in pixels
snum: serial number of the camera
hostname: hostname of the machine to which the camera is attached

Returns:

camref: a handle to the new camera

set_camera_flen(camref, flen)

Sets the focal length for a camera.

Arguments:

camref: handle to camera
flen: focal length of camera

set_camera_axis(camref, x, y)

Sets the line perpendicular to the focal plane of the camera along which the center of projection lies.

Arguments:

camref: handle to camera
x, y: center of projection coordinates

set_camera_coef(camref, k2, k4)

Sets the radial distortion coefficients for the camera.

Arguments:

camref: handle to camera
k2, k4: distortion coefficients

set_camera_emat(camref, matrix)

Sets the extrinsic calibration matrix for a camera. This is a transformation matrix that defines the position of this camera relative to the root camera. Currently the root camera is defined as the first camera instantiated by the tracker at runtime (not necessarily the first camera defined in the config script. Instead this will be the first camera on the bus of the root node of the tracking cluster.) In practice, the matrix should be automatically generated by the calibration application and copied over into the config file.

Arguments:

camref: handle to camera
matrix: A table of 9 numerical elements defining a 3x3 matrix

Mapping configuration

These functions define a mapping from unified camera coordinates to table coordinates.

set_map_from(from)

Defines the control vertecies in unified camera coordinates from which the mapping to table coordinates will be performed.

Arguments:

from: A one dimensional table of numbers, grouped into xy coordinate pairs. There should be twice the number of table entries as there are verticies in unified camera coordinate space. The length of this table should match the table length supplied to set_map_to.

set_map_to(to)

Defines the control vertecies in table coordinates to which the mapping from unified camera coordinates will be performed.

Arguments:

to: A one dimensional table of numbers, grouped into xy coordinate pairs. There should be twice the number of table entries as there are verticies in table coordinate space. The length of this table should match the table length supplied to set_map_from.

set_map_faces(faces)

Defines a tessellation of the mapping area by assigning the verticies of the to and from lists to triangular faces.

Arguments:

faces: a list of indecies into the tables supplied to set_map_to and set_map_from grouped into triplets. There should be three times the number of table entries as there are faces in the tessellation. Each index supplied refers to the corresponding element in both the to and from tables.

Network configuration

add_client(address, port)

Adds a client to receive the stream of UDP tracking messags. Only one client should be added as multiple clients have not been implemented. (I'm not sure that there is any reason to either)

Arguments:

address: a string with the host address of the client
port: a numerical port

Example Lua configuration file


-- set up devices

devices = {
    -- device 1 (apple mouse)
    {{ 616.88, 520.15}, { 629.91, 503.29}, { 587.81, 503.19}, },
    {{ 601.44, 518.78}, { 629.82, 503.40}, { 587.66, 503.31}, },
    {},
    -- device 2 (circular puck 1)
    {{ 496.72, 474.79}, { 519.67, 463.90}, { 474.58, 460.77}, },
    {},
    {},
}

for i = 1, table.getn(devices) - 1, 3 do
    local dev = LT.add_device()

    for j, blip in pairs(devices[i]) do
	LT.add_base_blip(dev, blip[1], blip[2])
    end

    for j, blip in pairs(devices[i+1]) do
	LT.add_alt1_blip(dev, blip[1], blip[2])
    end

    for j, blip in pairs(devices[i+2]) do
	LT.add_alt2_blip(dev, blip[1], blip[2])
    end
end

-- set up cameras

cam1 = LT.add_camera(1024, 768, 6314092, "teiburu4-10")
cam2 = LT.add_camera(1024, 768, 6262010, "teiburu4-10")
cam3 = LT.add_camera(1024, 768, 6262011, "teiburu5-10")
cam4 = LT.add_camera(1024, 768, 6262017, "teiburu5-10")

LT.set_camera_flen(cam1, 1976)
LT.set_camera_flen(cam2, 1976)
LT.set_camera_flen(cam3, 1976)
LT.set_camera_flen(cam4, 1976)

LT.set_camera_axis(cam1, 544, 398)
LT.set_camera_axis(cam2, 544, 398)
LT.set_camera_axis(cam3, 544, 398)
LT.set_camera_axis(cam4, 544, 398)

LT.set_camera_coef(cam1, -0.13654, 0.91328)
LT.set_camera_coef(cam2, -0.13654, 0.91328)
LT.set_camera_coef(cam3, -0.13654, 0.91328)
LT.set_camera_coef(cam4, -0.13654, 0.91328)

emats = {
	{ 1.00,  0.00,    0.00,  0.00, 1.00,   0.00, 0.00, 0.00, 1.00, },
	{ 0.99, -0.01,    0.58,  0.01, 0.99, 579.65, 0.00, 0.00, 1.00, },
	{ 0.97,  0.02,  945.39, -0.02, 0.97,   9.92, 0.00, 0.00, 1.00, },
	{ 0.93, -0.00, 1003.53,  0.00, 0.93, 556.44, 0.00, 0.00, 1.00, },
}

LT.set_camera_emat(cam1, emats[1])
LT.set_camera_emat(cam2, emats[2])
LT.set_camera_emat(cam3, emats[3])
LT.set_camera_emat(cam4, emats[4])

-- setup mapping

mapfrom = {
      -769.35,   158.61,
       -48.90,   183.04,
       -45.91,   622.30,
      -783.69,   610.07,
}

mapto = { 
    0.00+0.025, 0.00+0.05,
    0.33-0.025, 0.00+0.05,
    0.33-0.025, 0.50-0.05,
    0.00+0.025, 0.50-0.05,
}

mapfaces = { 
    0,  1,  2,  2,  3,  0,
    4,  5,  6,  6,  7,  4,
    8,  9,  10, 10, 11, 8,
    12, 13, 14, 14, 15, 12,
    16, 17, 18, 18, 19, 16,
    20, 21, 22, 22, 23, 20,
}

LT.set_map_from (mapfrom);
LT.set_map_to   (mapto);
LT.set_map_faces(mapfaces);

-- setup networking

LT.add_client("10.0.8.10", 7000)

Acknowledgements

Thanks Robert Kooima for showing me how effective and simple embedded lua can be, and for the excellent example that is Electro.