Python wrapper

Requirements and support

The Python wrapper requires only core Python libraries and numpy for handling mask data. The Python code itself is a CTypes wrapper arround the trax C library.

Documentation

Python bindings for the TraX protocol, main module.

class trax.BufferImage(internal)

Image encoded in a memory buffer stored in JPEG or PNG file format.

buffer()

Get image buffer

Returns:

A memory buffer containing the encoded image.

static create(data: bytes)

Create image from a memory buffer

Args:

data: A memory buffer containing the encoded image.

type()

Get image type

class trax.ConsoleLogger

Logger that prints all messages to standard output.

handle(message)

Handle message by printing it to standard output.

Args:

message (str): message to handle

class trax.FileImage(internal)

Image saved in a local file

static create(path=None)

path()

type()

Get image type

class trax.FileLogger(filename: str)

Logger that writes all messages to a file.

handle(message: str)

Handle message by writing it to a file.

Args:

message (str): message to handle

class trax.HandleWrapper(reference, owner=True)

Wrapper for trax_handle_t structure.

class trax.Image(internal)

Image description class.

BUFFER = buffer

Image saved in memory as a numpy array

MEMORY = memory

PATH = path

URL = url

static decode_list(intcode)

Decode a list of image formats from an integer code.

Args:

intcode (int): Integer code.

static encode(strcode)

static encode_list(list)

Encode a list of image formats into an integer code.

Args:

list (list): List of image formats.

Returns:

int: Integer code.

property reference

Get reference to the internal object.

Returns:

c_void_p: Reference to the internal object.

abstract type()

Get image type

static wrap(internal)

class trax.ImageChannel

Image channel identifier.

COLOR = color

DEPTH = depth

IR = ir

static decode(intcode: int)

Decode an image channel from an integer code.

Args:

intcode (int): Integer code.

static decode_list(intcode: int)

Decode a list of image channels from an integer code.

Args:

intcode (int): Integer code.

static encode(strcode)

Encode an image channel into an integer code.

static encode_list(list)

Encode a list of image channels into an integer code.

Args:

list (list): List of image channels.

Returns:

int: Integer code.

class trax.ImageListWrapper(reference, owner=True)

Wrapper for trax_image_list_t structure.

class trax.ImageWrapper(reference, owner=True)

Wrapper for trax_image_t structure.

class trax.Logger

Base class for all TraX loggers, subclasses should implement handle() method.

handle(message: str)

Handle message, should be implemented in subclasses.

Args:

message (str): message to handle

property interrupted

Returns True if logger was interrupted by KeyboardInterrupt, False otherwise.

class trax.Mask(internal)

Mask region wrapper.

array(normalize=False)

Returns the mask region object as a numpy array. If normalize is True, the mask is padded with zeros for the offset.

Args:

normalize (bool, optional): whether to normalize the mask by adding the offset. Defaults to False.

Returns:

numpy.ndarray: mask region object as a numpy array

static create(source, x=0, y=0)

Creates a new mask region object

Args:

source (numpy.ndarray): source image x (int, optional): horizontal offset. Defaults to 0. y (int, optional): vertical offset. Defaults to 0.

Returns:

Mask: mask region object

get(i)

Returns the i-th point of the mask region object

Args:

i (int): index of the point

offset()

Returns the offset of the mask region object

Returns:

tuple: offset of the mask region object

size()

Returns the size of the mask region object

Returns:

tuple: size of the mask region object

property type

Returns the type of the region object

Returns:

int: type of the region object

class trax.MemoryImage(internal)

Image saved in memory as a numpy array

array()

static create(image: numpy.ndarray)

Create a new memory image resource.

Args:

image (np.ndarray): Image data.

type()

Get image type

class trax.ObjectListWrapper(reference, owner=True)

Wrapper for trax_object_list_t structure.

class trax.OwnerRef(owner, item, callback)

Weak reference that calls a finalizer when the object goes away.

class trax.Polygon(internal)

Polygon region

static create(points)

Constructor

Args:

points: list of points in the polygon

get(i: int)

Get point at index i

Args:

i (int): index of the point

Returns:

tuple: point at index i

size()

Number of points in the polygon

Returns:

int: number of points in the polygon

property type

Type of the region

Returns:

int: type of the region

class trax.Properties(data=None, owner=True)

Wrapper for properties structure. Supports a dictionary-like interface.

copy(source: Properties)

Copy properties from another properties structure.

Args:

source (Properties): source properties structure

dict()

Return a dictionary of properties. The dictionary is a copy of the internal structure entries.

get(key: str, default: str = None)

Get a property value.

Args:

key (str): property key default (str): default value if the property is not found

Returns:

str: property value

property reference

Get a reference to the internal C structure.

Returns:

c_void_p: reference of the internal C structure

set(key: str, value: str)

Set a property value.

Args:

key (str): property key value (str): property value

class trax.PropertiesWrapper(reference, owner=True)

Wrapper for trax_properties_t structure.

class trax.ProxyLogger(callback: callable)

Logger that proxies all messages to a callback function.

handle(message)

Handle message by calling callback function.

Args:

message (str): message to handle

class trax.Rectangle(internal)

Rectangle region description

bounds()

Bounding box of the region.

Returns:

tuple: Bounding box of the region.

static create(x=0, y=0, width=0, height=0)

Constructor

Args:

x (float): X coordinate of the top left corner. y (float): Y coordinate of the top left corner. width (float): Width of the rectangle. height (float): Height of the rectangle.

Returns:

Rectangle: Rectangle region description.

property type

Region type.

Returns:

str: Region type.

class trax.Region(internal)

Base class for region descriptions.

MASK = mask

POLYGON = polygon

RECTANGLE = rectangle

SPECIAL = special

static decode_list(intcode)

Decode region format from integer code.

Args:

intcode (int): Integer code.

Returns:

[list]: List of region format names.

static encode(strcode)

Encode region format to integer code.

Args:

strcode (str): Region format name.

static encode_list(list)

Encode region format list to integer code.

Args:

list (list): List of region format names.

property reference

Internal region pointer.

abstract type()

Region type.

static wrap(internal)

Wrap internal region pointer into a region object.

class trax.RegionWrapper(reference, owner=True)

Wrapper for trax_region_t structure.

class trax.Server(region_formats, image_formats, image_channels=['color'], tracker_name='', tracker_description='', tracker_family='', metadata=None, log=False, multiobject=False)

TraX server.

quit(reason=None)

Sends quit message and end terminates communication.

status(objects, properties=None)

Reply to client with a status region and optional properties.

Parameters:

• objects (List[Region, Mapping]) – Resulting status of tracked objects.

• properties (dict) – Optional arguments as a dictionary.

wait()

Wait for client message request. Recognize it and parse them when received .

Returns:

A request structure

Return type:

trax.server.Request

class trax.Special(internal)

Special region

property code

static create(code: int)

Constructor

Args:

code (int): Special region code.

property type

Region type.

Returns:

str: Region type.

exception trax.TraxException

Base class for all TraX related exceptions

class trax.TraxStatus

TraX status codes wrapper class

ERROR = error

FRAME = frame

HELLO = hello

INITIALIZE = initialize

OK = ok

QUIT = quit

STATE = state

static decode(intcode)

Decode integer status code to string

Args:

intcode (int): integer status code

Returns:

str: string status code

class trax.URLImage(internal)

Image saved in a local or remote resource

static create(url: str = None)

Create a new URL image resource.

Args:

url (str): URL of the resource.

type()

Get image type

Returns:

str: Image type

url()

Get image URL

Returns:

str: Image URL

class trax.Wrapper(ctype, reference, finalizer)

Base class for all TraX wrappers, subclasses should implement reference property.

property reference

Returns reference to the wrapped structure.

Returns:

c_void_p: reference to the wrapped structure

class trax.struct_trax_handle

Structure base class

class trax.struct_trax_image

Structure base class

class trax.struct_trax_image_list

Structure base class

class trax.struct_trax_object_list

Structure base class

class trax.struct_trax_properties

Structure base class

trax.trax_cleanup

trax.trax_image_list_p

trax.trax_image_list_release

trax.trax_image_p

trax.trax_image_release

trax.trax_object_list

trax.trax_object_list_p

trax.trax_object_list_release

trax.trax_properties_create

trax.trax_properties_get

trax.trax_properties_p

trax.trax_properties_release

trax.trax_properties_set

trax.trax_region_p

trax.trax_region_release

trax.wrap_image_list(list)

Wrap image list internal C structure into a dictionary of images.

Args:

list (c_void_p): image list to wrap

trax.wrap_images(images)

Wrap dictionary of images into image list internal C structure.

Args:

images (dict): dictionary of images

trax.wrap_object_list(list)

Wrap object list internal C structure into a list of regions.

Args:

list (c_void_p): object list to wrap

trax.wrap_objects(objects)

Wrap list of regions into object list internal C structure.

Args:

objects (list): list of regions

Integration example

Below is a simple example of a Python code skeleton for a tracker, exposing its tracking loop but hidding all tracker-specific details to keep things clear.

tracker = Tracker()
trajectory = [];
i = 1

rectangle = read_bounding_box()
image = read_image(i)
rectangle = tracker.initialize(rectangle, image)

trajectory.append(rectangle)

while True:
  i = i + 1
  image = read_image(i)
  rectangle = tracker.update(image)
  trajectory.append(rectangle)

write_trajectory(trajectory)

To make the tracker work with the TraX protocol you have to modify the above code in the following way and also make sure that the trax module will be available at runtime.

import trax.server
import trax.region
import trax.image
import time

tracker = Tracker()

with trax.server.Server(trax.region.RECTANGLE, trax.image.PATH) as server:
  while True:
    request = server.wait()
    if request.type in ["quit", "error"]:
      break
    if request.type == "initialize":
      rectangle = tracker.initialize(get_rectangle(request.region),
            load_image(request.image))
    else:
      rectangle = tracker.update(load_image(request.image))

    server.status(get_region(rectangle))