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.
-
Metadata(int region_formats, int image_formats, std::string tracker_name, std::string tracker_description, std::string tracker_family)
-
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()
-
Logging(trax_logging logging)
-
class Bounds
-
Bounds()
-
Bounds(trax_bounds bounds)
-
Bounds(float left, float top, float right, float bottom)
-
~Bounds()
-
Bounds()
-
class Handle
-
~Handle()
-
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.
-
~Handle()
-
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 ®ion, Properties &properties)
Waits for a valid protocol message from the server.
-
int initialize(const Image &image, const Region ®ion, const Properties &properties)
Sends an initialize message.
-
int frame(const Image &image, const Properties &properties)
Sends a frame message.
-
Client(int input, int output, Logging logger)
-
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 ®ion, Properties &properties)
Waits for a valid protocol message from the client.
-
int reply(const Region ®ion, const Properties &properties)
Sends a status reply to the client.
-
Server(Configuration configuration, Logging log)
-
class Image
-
Image()
-
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.
-
Image()
-
class Region
-
Region()
Creates a new empty 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.
-
Region()
-
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.
-
Properties()
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.
1#include <iostream>
2#include <fstream>
3
4using namescpace std;
5
6int main( int argc, char** argv)
7{
8 int i;
9 FILE* out;
10 Rectangle region;
11 Image image;
12 Tracker tracker;
13
14 ofstream out;
15 output.open("trajectory.txt", ofstream::out);
16
17 region = read_bounding_box();
18 image = read_image(1);
19 region = tracker.initialize(region, image);
20
21 out << region << endl;
22
23 for (i = 2; ; i++)
24 {
25 image = read_image(i);
26 region = tracker.update(image);
27 out << region << endl;
28 }
29
30 out.close();
31 return 0;
32}
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.
1#include <stdio.h>
2
3// Include TraX library header
4#include "trax.h"
5
6using namespace std;
7
8int main( int argc, char** argv)
9{
10 int run = 1;
11
12 // Initialize protocol
13 trax::Server handle(trax::Metadata(TRAX_REGION_RECTANGLE,
14 TRAX_IMAGE_PATH), trax_no_log);
15
16 while(run)
17 {
18 trax::Image image;
19 trax::Region region;
20 trax::Properties properties;
21
22 int tr = handle.wait(image, region, properties);
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 cv::Rect result = tracker.initialize(
29 trax::region_to_rect(region), trax::image_to_mat(image));
30
31 handle.reply(trax::rect_to_region(result), trax::Properties());
32
33 } else
34 // The second one is TRAX_FRAME that tells the tracker what to process next.
35 if (tr == TRAX_FRAME) {
36
37 cv::Rect result = tracker.update(image_to_mat(image));
38 handle.reply(trax::rect_to_region(result), trax::Properties());
39
40 }
41 // Any other command is either TRAX_QUIT or illegal, so we exit.
42 else {
43 run = 0;
44 }
45
46 }
47
48 return 0;
49}