Documentation Center

Tracking Hub Administrator Guide

Version 1.7 | Published January 16, 2024 ©

Description of the XML protocol description file format

Like most tracking formats the XML description can be used to send an arbitrary number of axes to Tracking Hub. It is possible to define a checksum and the default connection parameters, which is then set in Studio Manager, when the protocol is selected from the User.

Setting the connection parameters is optional. The definition starts with:

<?xml version="1.0" encoding="utf-8"?>

Start Element “vizth_xml_tracking”

A tracking definition must define this element with the attribute “title”:

<vizth_xml_tracking title="name">

In Studio Manager, the title attribute is used in the list of tracking systems. It should be unique.

Checksum Element

The checksum element defines the length of the packet and the method of the checksum calculation. The attribute “pkglen” is mandatory and must match the size of the complete package including header and checksum. It is given in bytes.

The attribute “checksum” is optional. If not given no checksum is calculated. If it is bigger than zero the following calculations are done:

  • 1: 0x40 - sum of all bytes (same as Freed protocol)


Sum = 0x40u - Sum;
return ((Sum & 0xFF) == value of last byte of the package excluding checksum byte


  • 2: sum of all bytes


Sum= sum of all bytes
return ((Sum & 0xFF) == value of last byte of the package excluding checksum byte


  • 3: inverted sum of all bytes


Sum = (WORD)(~Sum);
return ((Sum & 0xFF) == value of last byte of the package excluding checksum byte


The checksum byte is always the last byte in the tracking package.

Extraction

The element “extraction” is mandatory and defines with the attribute “count” the amount of axes in the tracking package. Optional you can define separator, if you keep it empty, it is not used. If you define this separator, the tracking package departs first before the values are calculated. It also contains the “axis” elements which define the axis values, the type, the position in the package, the length, the byte order and the calculation method.

Axis Element

The “axis” elements are part of the “extraction” element. The amount of axes elements must match the attribute “count”.

Axis Attributes

  • name: Defines the name of the axis and this also defines how the axis is displayed in Studio Manager. Every axis name must be unique for the actual extraction element.

  • start: Defines the byte position in the package.

  • len: Defines the length of the axis in bytes.

  • order: Defines the byte order of the numeric value. This attribute can have the following values.

    • “bigendian”

    • “littleendian”

    • “ascii” If ascii is given the bytes are interpreted as string.

  • value: Defines the numeric encoding of the axis. Valid values are:

    • “INT32”

    • “UINT32”

    • “FLOAT”

  • calc: Defines the mathematical operation which is needed to calculate the axis value in Tracking Hub units. For angle values, Tracking Hub uses Euler angles. For distance or position centimeters are used. The value of this attribute is a string which starts with a mathematical operator, a white space and a number. Allowed operators are:

    • “+” Addition

    • “-“ Subtraction

    • “/” Division

    • “*” Multiplication

    • Any other character is ignored.

  • Tickcount values and Offsets are handled outside this description, and can set on the standard places like for other protocols.

<?xml version="1.0" encoding="utf-8"?>
<vizth_xml_tracking title="xml_freed">
<checksum pkglen="29" calculation="1" />
<extraction separator="">
<axis name="rotx" start="5" len="3" order="bigendian" value="INT32" calc="/ "></axis>
<axis name="roty" start="2" len="3" order="bigendian" value="INT32" calc="/ "></axis>
<axis name="rotz" start="8" len="3" order="bigendian" value="INT32" calc="/ "></axis>
<axis name="posx" start="11" len="3" order="bigendian" value="INT32" calc="/ "></axis>
<axis name="posy" start="14" len="3" order="bigendian" value="INT32" calc="/ "></axis>
<axis name="posz" start="17" len="3" order="bigendian" value="INT32" calc="/ "></axis>
<axis name="zoom" start="20" len="3" order="bigendian" value="INT32" calc="- "></axis>
<axis name="focus" start="23" len="3" order="bigendian" value="INT32" calc="- "></axis>
<axis name="iris" calc="!"></axis>
</extraction>
</vizth_xml_tracking>
<?xml version="1.0" encoding="utf-8"?>
<vizth_xml_tracking title=”kuper”>
<checksum pkglen="0" calculation="0" />
<extraction separator="," >
<axis name="tilt" field="1" order="ascii" value="FLOAT" calc="/" />
<axis name="pan" field="2" order="ascii" value="FLOAT" calc="/" />
<axis name="zoom" field="3" order="ascii" value="UINT32" calc="/" />
<axis name="focus" field="4" order="ascii" value="UINT32" calc="/" />
</extraction>
</vizth_xml_tracking>