Library C++ wrapper

The main functionality of the reference library is written in pure C, however, it also offers a C++ wrapper if used with a C++ compiler. This wrapper uses classes and objects as well as reference counting for memory management, making is more suitable choice when using the reference library in a C++ algorithm.

Requirements and building

No additional requirements are necessary for building the wrapper but a C++ compiler.

Documentation

The wrapper is composed of several classes, mostly following the underlying C functions. All the classes are contained in trax namespace.

class Metadata

A wrapper class for tracker metadata structure

Metadata(int region_formats, int image_formats, std::string tracker_name, std::string tracker_description, std::string tracker_family)

Creates a new metadata object.

~Metadata()

int image_formats()

Returns supported image formats as a bit field.

int region_formats()

Returns supported region formats as a bit field.

std::string tracker_name()

Returns tracker name string or empty string.

std::string tracker_description()

Returns tracker description string or empty string.

std::string tracker_family()

Returns tracker family string or empty string.

class Logging

A wrapper class for logging configuration structure

Logging(trax_logging logging)

Logging(trax_logger callback = NULL, void *data = NULL, int flags = 0)

~Logging()

class Bounds

Bounds()

Bounds(trax_bounds bounds)

Bounds(float left, float top, float right, float bottom)

~Bounds()

class Handle

~Handle()

const Metadata metadata()

const bool terminate()

Terminate session by sending quit message. Implicitly called when object is destroyed.

std::string get_error()

Return last error string or empty string if no error has occured in last call to handle.

bool is_alive()

Check if the handle is opened or not.

class Client

Client(int input, int output, Logging logger)

Sets up the protocol for the client side and returns a handle object.

Client(int server, Logging logger, int timeout = -1)

Sets up the protocol for the client side and returns a handle object.

~Client()

int wait(Region &region, Properties &properties)

Waits for a valid protocol message from the server.

int initialize(const Image &image, const Region &region, const Properties &properties)

Sends an initialize message.

int frame(const Image &image, const Properties &properties)

Sends a frame message.

class Server

Server(Configuration configuration, Logging log)

Sets up the protocol for the server side and returns a handle object.

~Server()

int wait(Image &image, Region &region, Properties &properties)

Waits for a valid protocol message from the client.

int reply(const Region &region, const Properties &properties)

Sends a status reply to the client.

class Image

Image()

Image(const Image &original)

static Image create_path(const std::string &path)

Creates a file-system path image description. See trax_image_create_path().

static Image create_url(const std::string &url)

Creates a URL path image description. See trax_image_create_url().

static Image create_memory(int width, int height, int format)

Creates a raw buffer image description.See trax_image_create_memory().

static Image create_buffer(int length, const char *data)

Creates a file buffer image description. See trax_image_create_buffer().

~Image()

Releases image structure, frees allocated memory.

int type() const

Returns a type of the image handle. See trax_image_get_type().

bool empty() const

Checks if image container is empty.

const std::string get_path() const

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.

const std::string get_url() const

Returns a file path from a URL path image description. This function returns a pointer to the internal data which should not be modified.

void get_memory_header(int *width, int *height, int *format) const

Returns the header data of a memory image.

char *write_memory_row(int row)

Returns a pointer for a writeable row in a data array of an image.

const char *get_memory_row(int row) const

Returns a read-only pointer for a row in a data array of an image.

const char *get_buffer(int *length, int *format) const

Returns a file buffer and its length. This function returns a pointer to the internal data which should not be modified.

class Region

Region()

Creates a new empty region.

Region(const Region &original)

Creates a clone of region.

static Region create_special(int code)

Creates a special region object. Only one paramter (region code) required.

static Region create_rectangle(float x, float y, float width, float height)

Creates a rectangle region.

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

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

~Region()

Releases region, frees allocated memory.

int type() const

Returns type identifier of the region object.

bool empty() const

Checks if region container is empty.

void set(int code)

Sets the code of a special region.

int get() const

Returns a code of a special region object.

void set(float x, float y, float width, float height)

Sets the coordinates for a rectangle region.

void get(float *x, float *y, float *width, float *height) const

Retreives coordinate from a rectangle region object.

void set_polygon_point(int index, float x, float y)

Sets coordinates of a given point in the polygon.

void get_polygon_point(int index, float *x, float *y) const

Retrieves the coordinates of a specific point in the polygon.

int get_polygon_count() const

Returns the number of points in the polygon.

void get_mask_header(int *x, int *y, int *width, int *height) const

Returns the header data of a mask region.

char *write_mask_row(int row)

Returns a pointer for a writeable row in a data array of a mask.

const char *get_mask_row(int row) const

Returns a read-only pointer for a row in a data array of a mask.

Bounds bounds() const

Computes bounds of a region.

Region convert(int type) const

Convert region to one of the other types if possible.

float overlap(const Region &region, const Bounds &bounds = Bounds()) const

Calculates the Jaccard index overlap measure for the given regions with optional bounds that limit the calculation area.

class Properties

Properties()

Create a property object.

Properties(const Properties &original)

A copy constructor.

~Properties()

Destroy a properties object and clean up the memory.

int size()

Return the number of elements.

void clear()

Clear a properties object.

void set(const std::string key, const std::string value)

Set a string property (the value string is cloned).

void set(const std::string key, int value)

Set an integer property. The value will be encoded as a string.

void set(const std::string key, float value)

Set an floating point value property. The value will be encoded as a string.

std::string get(const std::string key, const std::string &def)

Get a string property.

int get(const std::string 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.

float get(const std::string key, float def)

Get an floating point value property. A stored string value is converted to an float. If this is not possible or the property does not exist a given default value is returned.

bool get(const std::string key, bool def)

Get an boolean point value property. A stored string value is converted to an integer and checked if it is zero. If this is not possible or the property does not exist a given default value is returned.

void enumerate(Enumerator enumerator, void *object)

Iterate over the property set using a callback function. An optional pointer can be given and is forwarded to the callback.

void from_map(const std::map<std::string, std::string> &m)

Adds values from a dictionary to the properties object.

void to_map(std::map<std::string, std::string> &m)

Copies key-value pairs in the properties object into the given dictionary.

void to_vector(std::vector<std::string> &v)

Copies keys from the properties object into the given vector.

Integration example

In C++ tracker implementations you can use either the C++ wrapper or basic C protocol implementation. The wrapper is more conveninent as it is object-oriented and provides automatic deallocation of resources via reference counting. 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.

#include <iostream>
#include <fstream>

using namescpace std;

int main( int argc, char** argv)
{
    int i;
    FILE* out;
    Rectangle region;
    Image image;
    Tracker tracker;

    ofstream out;
    output.open("trajectory.txt", ofstream::out);

    region = read_bounding_box();
    image = read_image(1);
    region = tracker.initialize(region, image);

    out << region << endl;

    for (i = 2; ; i++)
    {
      image = read_image(i);
      region = tracker.update(image);
      out << region << endl;
    }

    out.close();
    return 0;
}

The code above can be modified to use the TraX protocol by including the C/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.

#include <stdio.h>

// Include TraX library header
#include "trax.h"

using namespace std;

int main( int argc, char** argv)
{
    int run = 1;

    // Initialize protocol
    trax::Server handle(trax::Metadata(TRAX_REGION_RECTANGLE,
                                TRAX_IMAGE_PATH), trax_no_log);

    while(run)
    {
       trax::Image image;
       trax::Region region;
       trax::Properties properties;

       int tr = handle.wait(image, region, properties);

       // There are two important commands. The first one is
       // TRAX_INITIALIZE that tells the tracker how to initialize.
       if (tr == TRAX_INITIALIZE) {

          cv::Rect result = tracker.initialize(
               trax::region_to_rect(region), trax::image_to_mat(image));

          handle.reply(trax::rect_to_region(result), trax::Properties());

       } else
       // The second one is TRAX_FRAME that tells the tracker what to process next.
       if (tr == TRAX_FRAME) {

          cv::Rect result = tracker.update(image_to_mat(image));
          handle.reply(trax::rect_to_region(result), trax::Properties());

       }
       // Any other command is either TRAX_QUIT or illegal, so we exit.
       else {
            run = 0;
       }

    }

    return 0;
}