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 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 ®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.
-
-
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.
-
-
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.
-
-
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.
-
-
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | #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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | #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;
}
|