Reference C library
The TraX protocol can be implemented using the protocol specification, the protocol is quite easy to implement in many high-level languages. However, a reference C implementation is provided to serve as a practical model of implementation and to make the adoption of the protocol easier.
Requirements and building
The library is built using CMake build tool which generates build instructions for a given platform. The code is written in C89 for maximum portability and the library has no external dependencies apart from the standard C library. For more details on building check out the tutorial on compiling the project.
Documentation
All the public functionality of the library is described in the trax.h
header file, below is a summary of individual functions that are available in the library.
Communication
-
TRAX_ERROR
Value that indicates protocol error
-
TRAX_OK
Value that indicates success of a function call
-
TRAX_HELLO
Value that indicates introduction message
-
TRAX_INITIALIZE
Value that indicates initialization message
-
TRAX_FRAME
Value that indicates frame message
-
TRAX_QUIT
Value that indicates quit message
-
TRAX_STATE
Value that indicates status message
-
type trax_logging
Structure that describes logging handle.
-
type trax_bounds
Structure that describes region bounds.
-
type trax_handle
Structure that describes a protocol state for either client or server.
-
type trax_image
Structure that describes an image.
-
type trax_region
Structure that describes a region.
-
type trax_properties
Structure that contains an key-value dictionary.
-
trax_logging trax_no_log
A constant to indicate that no logging will be done.
-
trax_bounds trax_no_bounds
A constant to indicate that here are no bounds.
-
const char *trax_version()
Returns a string version of the library for debugging purposes. If possible, this version is defined during compilation time and corresponds to Git hash for the current revision.
- Returns:
Version string as a constant character array
-
trax_metadata *trax_metadata_create(int region_formats, int image_formats, int channels, const char *tracker_name, const char *tracker_description, const char *tracker_family)
- Parameters:
region_formats – Supported regions formats bit-set.
image_formats – Supported image formats bit-set.
channels – Required image channels bit-set. If empty then only TRAX_CHANNEL_VISIBLE is assumed.
Create a tracker metadata structure returning its pointer
- Returns:
A pointer to a metadata structure that can be released using
trax_metadata_release()
.
-
void trax_metadata_release(trax_metadata **metadata)
Releases a given metadata structure, clearing its memory.
- Parameters:
metadata – Pointer of a pointer of tracker metadata structure.
-
trax_logging trax_logger_setup(trax_logger callback, void *data, int flags)
A function that can be used to initialize a logging configuration structure.
- Parameters:
callback – Callback function used to process a chunk of log data
data – Additional data passed to the callback function as an argument
flags – Optional flags for logger
- Returns:
A logging structure for the given data
-
trax_logging trax_logger_setup_file(FILE *file)
A handy function to initialize a logging configuration structure for file logging. Internally the function calls
trax_logger_setup()
.- Parameters:
file – File object, opened for writing, can also be
stdout
orstderr
- Returns:
A logging structure for the given file
-
trax_handle *trax_client_setup_file(int input, int output, trax_logging log)
Setups the protocol state object for the client. It is assumed that the tracker process is already running (how this is done is not specified by the protocol). This function tries to parse tracker’s introduction message and fails if it is unable to do so or if the handshake fails (e.g. unsupported format version).
- Parameters:
input – Stream identifier, opened for reading, used to read server output
output – Stream identifier, opened for writing, used to write messages
log – Logging structure
- Returns:
A handle object used for further communication or
NULL
if initialization was unsuccessful
-
trax_handle *trax_client_setup_socket(int server, int timeout, trax_logging log)
Setups the protocol state object for the client using a bi-directional socket. It is assumed that the connection was already established (how this is done is not specified by the protocol). This function tries to parse tracker’s introduction message and fails if it is unable to do so or if the handshake fails (e.g. unsupported format version).
- Parameters:
server – Socket identifier, used to read communcate with tracker
log – Logging structure
- Returns:
A handle object used for further communication or
NULL
if initialization was unsuccessful
-
int trax_client_wait(trax_handle *client, trax_region **region, trax_properties *properties)
Waits for a valid protocol message from the server.
- Parameters:
client – Client state object
region – Pointer to current region for an object, set if the response is
TRAX_STATE
, otherwiseNULL
properties – Additional properties
- Returns:
Integer value indicating status, can be either
TRAX_STATE
,TRAX_QUIT
, orTRAX_ERROR
-
int trax_client_initialize(trax_handle *client, trax_image *image, trax_region *region, trax_properties *properties)
Sends an initialize message to server.
- Parameters:
client – Client state object
image – Image frame data
region – Initialization region
properties – Additional properties object
- Returns:
Integer value indicating status, can be either
TRAX_OK
orTRAX_ERROR
-
int trax_client_frame(trax_handle *client, trax_image *image, trax_properties *properties)
Sends a frame message to server.
- Parameters:
client – Client state object
image – Image frame data
properties – Additional properties
- Returns:
Integer value indicating status, can be either
TRAX_OK
orTRAX_ERROR
-
trax_handle *trax_server_setup(trax_metadata *metadata, trax_logging log)
Setups the protocol for the server side and returns a handle object.
- Parameters:
metadata – Tracker metadata
log – Logging structure
- Returns:
A handle object used for further communication or
NULL
if initialization was unsuccessful
-
trax_handle *trax_server_setup_file(trax_metadata *metadata, int input, int output, trax_logging log)
Setups the protocol for the server side based on input and output stream and returns a handle object.
- Parameters:
metadata – Tracker metadata
input – Stream identifier, opened for reading, used to read client output
output – Stream identifier, opened for writing, used to write messages
log – Logging structure
- Returns:
A handle object used for further communication or
NULL
if initialization was unsuccessful
-
int trax_server_wait(trax_handle *server, trax_image **image, trax_region **region, trax_properties *properties)
Waits for a valid protocol message from the client.
- Parameters:
server – Server state object
image – Pointer to image frame data, set if the response is not
TRAX_QUIT
orTRAX_ERROR
, otherwiseNULL
region – Pointer to initialization region, set if the response is
TRAX_INITIALIZE
, otherwiseNULL
properties – Additional properties
- Returns:
Integer value indicating status, can be either
TRAX_INITIALIZE
,TRAX_FRAME
,TRAX_QUIT
, orTRAX_ERROR
-
int trax_server_reply(trax_handle *server, trax_region *region, trax_properties *properties)
Sends a status reply to the client.
- Parameters:
server – Server state object
region – Current region of an object
properties – Additional properties
- Returns:
Integer value indicating status, can be either
TRAX_OK
orTRAX_ERROR
-
int trax_terminate(trax_handle *handle)
Used in client and server. Closes communication, sends quit message if needed. This function is implicitly called in
trax_cleanup()
.- Parameters:
handle – Server or client state object
- Returns:
Integer value indicating status, can be either
TRAX_OK
orTRAX_ERROR
-
int trax_cleanup(trax_handle **handle)
Used in client and server. Closes communication, sends quit message if needed. Releases the handle structure.
- Parameters:
handle – Pointer to state object pointer
- Returns:
Integer value indicating status, can be either
TRAX_OK
orTRAX_ERROR
-
const char *trax_get_error(trax_handle *handle)
Retrieve last error message encountered by the server or client.
- Parameters:
handle – Pointer to state object
- Returns:
Returns NULL if no error occured.
-
int trax_is_alive(trax_handle *handle)
Check if the handle has been terminated.
- Parameters:
handle – Pointer to state object
- Returns:
Returns zero if handle is not alive and non-zero if it is.
-
int trax_set_parameter(trax_handle *handle, int id, int value)
Sets the parameter of the client or server instance.
-
int trax_get_parameter(trax_handle *handle, int id, int *value)
Gets the parameter of the client or server instance.
ImageList
-
TRAX_CHANNEL_VISIBLE
Visible light channel identifier.
-
TRAX_CHANNEL_DEPTH
Depth channel identifier.
-
TRAX_CHANNEL_IR
IR channel identifier.
-
TRAX_CHANNELS
Number of available channels.
-
TRAX_CHANNEL_INDEX(I)
Convert channel identifier into index.
-
TRAX_CHANNEL_ID(I)
Convert channel index into identifier.
-
trax_image_list *trax_image_list_create()
Create an emptry image list
- Returns:
Pointer to image list container
-
void trax_image_list_release(trax_image_list **list)
Release image list structure, does not release any channel images
- Parameters:
list – Image list container pointer
-
void trax_image_list_clear(trax_image_list *list)
Cleans image list, releases all allocated channel images
- Parameters:
list – Image list container pointer
-
trax_image *trax_image_list_get(const trax_image_list *list, int channel)
Get image for a specific channel
- Parameters:
list – Image list structure pointer
channel – Channel idenfifier
- Returns:
Image structure pointer
-
void trax_image_list_set(trax_image_list *list, trax_image *image, int channel)
Set image for a specific channel
- Parameters:
list – Image list structure pointer
image – Image structure pointer
channel – Channel idenfifier
- Returns:
Pointer to null-terminated character array
-
int trax_image_list_count(int channels)
Count available channels in provided bit-set
- Parameters:
channels – Bit-set of channel identifiers
- Returns:
Number of on bits.
Image
-
TRAX_IMAGE_EMPTY
Empty image type, not usable in any way but to signify that there is no data.
-
TRAX_IMAGE_PATH
Image data is provided in a file on a file system. Only a path is provided.
-
TRAX_IMAGE_URL
Image data is provided in a local or remote resource. Only a URL is provided.
-
TRAX_IMAGE_MEMORY
Image data is provided in a memory buffer and can be accessed directly.
-
TRAX_IMAGE_BUFFER
Image data is provided in a memory buffer but has to be decoded first.
-
TRAX_IMAGE_BUFFER_ILLEGAL
Image buffer is of an unknown data type.
-
TRAX_IMAGE_BUFFER_PNG
Image data is encoded as PNG image.
-
TRAX_IMAGE_BUFFER_JPEG
Image data is encoded as JPEG image.
-
TRAX_IMAGE_MEMORY_ILLEGAL
Image data is available in an unknown format.
-
TRAX_IMAGE_MEMORY_GRAY8
Image data is available in 8 bit per pixel format.
-
TRAX_IMAGE_MEMORY_GRAY16
Image data is available in 16 bit per pixel format.
-
TRAX_IMAGE_MEMORY_RGB
Image data is available in RGB format with three bytes per pixel.
-
void trax_image_release(trax_image **image)
Releases image structure, frees allocated memory.
- Parameters:
image – Pointer to image structure pointer (the pointer is set to
NULL
if the structure is destroyed successfuly)
-
trax_image *trax_image_create_path(const char *path)
Creates a file-system path image description.
- Parameters:
url – File path string, it is copied internally
- Returns:
Image structure pointer
-
trax_image *trax_image_create_url(const char *url)
Creates a URL path image description.
- Parameters:
url – URL string, it is copied internally
- Returns:
Image structure pointer
-
trax_image *trax_image_create_memory(int width, int height, int format)
Creates a raw in-memory buffer image description. The memory is not initialized, you have do this manually.
- Parameters:
width – Image width
height – Image height
format – Image format, see format type constants for options
- Returns:
Image structure pointer
-
trax_image *trax_image_create_buffer(int length, const char *data)
Creates a file buffer image description.
- Parameters:
length – Length of the buffer
data – Character array with data, the buffer is copied
- Returns:
Image structure pointer
-
int trax_image_get_type(const trax_image *image)
Returns a type of the image handle.
- Parameters:
image – Image structure pointer
- Returns:
Image type code, see image type constants for more details
-
const char *trax_image_get_path(const trax_image *image)
Returns a file path from a file-system path image description. This function returns a pointer to the internal data which should not be modified.
- Parameters:
image – Image structure pointer
- Returns:
Pointer to null-terminated character array
-
const char *trax_image_get_url(const trax_image *image)
Returns a file path from a URL path image description. This function returns a pointer to the internal data which should not be modified.
- Parameters:
image – Image structure pointer
- Returns:
Pointer to null-terminated character array
-
void trax_image_get_memory_header(const trax_image *image, int *width, int *height, int *format)
Returns the header data of a memory image.
- Parameters:
image – Image structure pointer
width – Pointer to variable that is populated with width of the image
height – Pointer to variable that is populated with height of the image
format – Pointer to variable that is populated with format of the image, see format constants for options
-
char *trax_image_write_memory_row(trax_image *image, int row)
Returns a pointer for a writeable row in a data array of an image.
- Parameters:
image – Image structure pointer
row – Number of row
- Returns:
Pointer to character array of the line
-
const char *trax_image_get_memory_row(const trax_image *image, int row)
Returns a read-only pointer for a row in a data array of an image.
- Parameters:
image – Image structure pointer
row – Number of row
- Returns:
Pointer to character array of the line
-
const char *trax_image_get_buffer(const trax_image *image, int *length, int *format)
Returns a file buffer and its length. This function returns a pointer to the internal data which should not be modified.
- Parameters:
image – Image structure pointer
length – Pointer to variable that is populated with buffer length
format – Pointer to variable that is populated with buffer format code
- Returns:
Pointer to character array
Region
-
TRAX_REGION_EMPTY
Empty region type, not usable in any way but to signify that there is no data.
-
TRAX_REGION_SPECIAL
Special code region type, only one value avalable that can have a defined meaning.
-
TRAX_REGION_RECTANGLE
Rectangle region type. Left, top, width and height values available.
-
TRAX_REGION_POLYGON
Polygon region type. Three or more points available with x and y coordinates.
-
TRAX_REGION_MASK
Mask region type. A per-pixel binary mask.
-
TRAX_REGION_ANY
Any region type, a shortcut to specify that any supported region type can be used.
-
void trax_region_release(trax_region **region)
Releases region structure, frees allocated memory.
- Parameters:
region – Pointer to region structure pointer (the pointer is set to
NULL
if the structure is destroyed successfuly)
-
int trax_region_get_type(const trax_region *region)
Returns type identifier of the region object.
- Parameters:
region – Region structure pointer
- Returns:
One of the region type constants
-
trax_region *trax_region_create_special(int code)
Creates a special region object.
- Parameters:
code – A numerical value that is contained in the region type
- Returns:
A pointer to the region object
-
void trax_region_set_special(trax_region *region, int code)
Sets the code of a special region.
- Parameters:
region – Region structure pointer
code – The new numerical value
-
int trax_region_get_special(const trax_region *region)
Returns a code of a special region object if the region is of special type.
- Parameters:
region – Region structure pointer
- Returns:
The numerical value
-
trax_region *trax_region_create_rectangle(float x, float y, float width, float height)
Creates a rectangle region.
- Parameters:
x – Left offset
y – Top offset
width – Width of rectangle
height – Height of rectangle
- Returns:
A pointer to the region object
-
void trax_region_set_rectangle(trax_region *region, float x, float y, float width, float height)
Sets the coordinates for a rectangle region.
- Parameters:
region – A pointer to the region object
x – Left offset
y – Top offset
width – Width of rectangle
height – Height of rectangle
-
void trax_region_get_rectangle(const trax_region *region, float *x, float *y, float *width, float *height)
Retreives coordinate from a rectangle region object.
- Parameters:
region – A pointer to the region object
x – Pointer to left offset value variable
y – Pointer to top offset value variable
width – Pointer to width value variable
height – Pointer to height value variable
-
trax_region *trax_region_create_polygon(int count)
Creates a polygon region object for a given amout of points. Note that the coordinates of the points are arbitrary and have to be set after allocation.
- Parameters:
code – The number of points in the polygon
- Returns:
A pointer to the region object
-
void trax_region_set_polygon_point(trax_region *region, int index, float x, float y)
Sets coordinates of a given point in the polygon.
- Parameters:
region – A pointer to the region object
index – Index of point
x – Horizontal coordinate
y – Vertical coordinate
-
void trax_region_get_polygon_point(const trax_region *region, int index, float *x, float *y)
Retrieves the coordinates of a specific point in the polygon.
- Parameters:
region – A pointer to the region object
index – Index of point
x – Pointer to horizontal coordinate value variable
y – Pointer to vertical coordinate value variable
-
int trax_region_get_polygon_count(const trax_region *region)
Returns the number of points in the polygon.
- Parameters:
region – A pointer to the region object
- Returns:
Number of points
-
trax_region *trax_region_create_mask(int x, int y, int width, int height)
Creates a mask region object of given size. Note that the mask data is not initialized.
- Parameters:
x – Left offset
y – Top offset
width – Mask width
height – Mask height
- Returns:
A pointer to the region object
-
void trax_region_get_mask_header(const trax_region *region, int *x, int *y, int *width, int *height)
Returns the header data of a mask region.
- Parameters:
region – A pointer to the region object
x – Pointer to left offset value variable
y – Pointer to top offset value variable
width – Pointer to width value variable
height – Pointer to height value variable
-
char *trax_region_write_mask_row(trax_region *region, int row)
Returns a pointer for a writeable row in a data array of a mask.
- Parameters:
region – Region structure pointer
row – Number of row
- Returns:
Pointer to character array of the line
-
const char *trax_region_get_mask_row(const trax_region *region, int row)
Returns a read-only pointer for a row in a data array of a mask.
- Parameters:
region – Region structure pointer
row – Number of row
- Returns:
Pointer to character array of the line
-
trax_bounds trax_region_bounds(const trax_region *region)
Calculates a bounding box region that bounds the input region.
- Parameters:
region – A pointer to the region object
- Returns:
A bounding box structure that contains values for left, top, right, and bottom
-
trax_region *trax_region_clone(const trax_region *region)
Clones a region object.
- Parameters:
region – A pointer to the region object
- Returns:
A cloned region object pointer
-
trax_region *trax_region_convert(const trax_region *region, int format)
Converts region between different formats (if possible).
- Parameters:
region – A pointer to the region object
format – One of the format type constants
- Returns:
A converted region object pointer
-
float trax_region_contains(const trax_region *region, float x, float y)
Calculates if the region contains a given point.
- Parameters:
region – A pointer to the region object
x – X coordinate of the point
y – Y coordinate of the point
- Returns:
Returns zero if the point is not in the region or one if it is
-
float trax_region_overlap(const trax_region *a, const trax_region *b, const trax_bounds bounds)
Calculates the spatial Jaccard index for two regions (overlap).
- Parameters:
a – A pointer to the region object
b – A pointer to the region object
- Returns:
A bounds structure to contain only overlap within bounds or
trax_no_bounds
if no bounds are specified
-
char *trax_region_encode(const trax_region *region)
Encodes a region object to a string representation.
- Parameters:
region – A pointer to the region object
- Returns:
A character array with textual representation of the region data
-
trax_region *trax_region_decode(const char *data)
Decodes string representation of a region to an object.
- Parameters:
region – A character array with textual representation of the region data
- Returns:
A pointer to the region object or
NULL
if string does not contain valid region data
Properties
-
trax_properties *trax_properties_create()
Create an empty properties dictionary.
- Returns:
A pointer to a properties object
-
void trax_properties_release(trax_properties **properties)
Destroy a properties object and clean up the memory.
- Parameters:
properties – A pointer to a properties object pointer
-
void trax_properties_clear(trax_properties *properties)
Clears a properties dictionary making it empty.
- Parameters:
properties – A pointer to a properties object
-
void trax_properties_set(trax_properties *properties, const char *key, const char *value)
Set a string property for a given key. The value string is cloned.
- Parameters:
properties – A pointer to a properties object
key – A key for the property, only keys valid according to the protocol are accepted
value – The value for the property, the string is cloned internally
-
void trax_properties_set_int(trax_properties *properties, const char *key, int value)
Set an integer property. The value will be encoded as a string.
- Parameters:
properties – A pointer to a properties object
key – A key for the property, only keys valid according to the protocol are accepted
value – The value for the property
-
void trax_properties_set_float(trax_properties *properties, const char *key, float value)
Set an floating point value property. The value will be encoded as a string.
- Parameters:
properties – A pointer to a properties object
key – A key for the property, only keys valid according to the protocol are accepted
value – The value for the property
-
char *trax_properties_get(const trax_properties *properties, const char *key)
Get a string property. The resulting string is a clone of the one stored so it should be released when not needed anymore.
- Parameters:
properties – A pointer to a properties object
key – A key for the property
- Returns:
The value for the property or
NULL
if there is no value associated with the key
-
int trax_properties_get_int(const trax_properties *properties, const char *key, int def)
Get an integer property. A stored string value is converted to an integer. If this is not possible or the property does not exist a given default value is returned.
- Parameters:
properties – A pointer to a properties object
key – A key for the property
def – Default value for the property
- Returns:
The value for the property or default value if there is no value associated with the key or conversion from string is impossible
-
float trax_properties_get_float(const trax_properties *properties, const char *key, float def)
Get an floating point value property. A stored string value is converted to an integer. If this is not possible or the property does not exist a given default value is returned.
- Parameters:
properties – A pointer to a properties object
key – A key for the property
def – Default value for the property
- Returns:
The value for the property or default value if there is no value associated with the key or conversion from string is impossible
-
int trax_properties_count(const trax_properties *properties)
Get a number of all pairs in the properties object.
- Parameters:
properties – A pointer to a properties object
- Returns:
Number of key-value pairs in the properties object
-
void trax_properties_enumerate(trax_properties *properties, trax_enumerator enumerator, const void *object)
Iterate over the property set using a callback function. An optional pointer can be given and is forwarded to the callback.
- Parameters:
properties – A pointer to a properties object
enumerator – A pointer to the enumerator function that is called for every key-value pair
object – A pointer to additional data for the enumerator function
Integration example
The library can be easily integrated into C and C++ code (although a C++ wrapper also exists) and can be also linked into other programming languages that enable linking of C libraries. Below is an sripped-down example of a C tracker skeleton with a typical tracking loop. Note that this is not a complete example and servers only as a demonstration of a typical tracker on a tracking-loop level.
1#include <stdio.h>
2
3int main( int argc, char** argv)
4{
5 int i;
6 FILE* out;
7 rectangle_type region;
8 image_type image;
9
10 out = fopen("trajectory.txt", "w");
11
12 region = read_bounding_box();
13 image = read_image(1);
14 region = initialize_tracker(region, image);
15
16 write_frame(out, region);
17
18 for (i = 2; ; i++)
19 {
20 image = read_image(i);
21 region = update_tracker(image);
22 write_frame(out, region);
23 }
24
25 fclose(out);
26 return 0;
27}
The code above can be modified to use the TraX protocol by including the C library header and changing the tracking loop to accept frames from the protocol insead of directly reading them from the filesystem. It also requires linking the protocol library (libtrax
) when building the tracker executable.
1#include <stdio.h>
2
3// Include TraX library header
4#include "trax.h"
5
6int main( int argc, char** argv)
7{
8 int run = 1;
9 trax_image_list* img = NULL;
10 trax_region* reg = NULL;
11
12 // Call trax_server_setup at the beginning
13 trax_handle* handle;
14 trax_metadata* meta = trax_metadata_create(TRAX_REGION_RECTANGLE, TRAX_IMAGE_PATH, TRAX_CHANNEL_VISIBLE, "Name", NULL, NULL);
15
16 handle = trax_server_setup(meta, trax_no_log);
17
18 trax_metadata_release(&meta);
19
20 while(run)
21 {
22 int tr = trax_server_wait(handle, &img, ®, NULL);
23
24 // There are two important commands. The first one is
25 // TRAX_INITIALIZE that tells the tracker how to initialize.
26 if (tr == TRAX_INITIALIZE) {
27
28 rectangle_type region = initialize_tracker(
29 region_to_rectangle(reg), load_image(img));
30 trax_server_reply(handle, rectangle_to_region(region), NULL);
31
32 } else
33 // The second one is TRAX_FRAME that tells the tracker what to process next.
34 if (tr == TRAX_FRAME) {
35
36 rectangle_type region = update_tracker(load_image(trax_image_list_get(img, TRAX_CHANNEL_VISIBLE)));
37 trax_server_reply(handle, rectangle_to_region(region), NULL);
38
39 }
40 // Any other command is either TRAX_QUIT or illegal, so we exit.
41 else {
42 run = 0;
43 }
44
45 if (img) {
46 trax_image_list_clear(img); // Also delete individual images
47 trax_image_list_release(&img);
48 }
49 if (reg) trax_region_release(®);
50
51 }
52
53 // TraX: Call trax_cleanup at the end
54 trax_cleanup(&handle);
55
56 return 0;
57}