Tracker module

This module contains the base classes for trackers and the registry of known trackers.

class vot.tracker.FrameResult(objects, time): Tuple-like immutable container for per-frame tracker output.

class vot.tracker.ObjectQuery(state, properties, offset): Tuple-like immutable container for an object query.

class vot.tracker.ObjectStatus(region, properties): Tuple-like immutable container for an object state.

class vot.tracker.OnlineTrackerRuntime(tracker: Tracker)

Base class for online tracker runtime implementations.

Tracker runtime is responsible for running the tracker executable and communicating with it.

abstract initialize(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Initializes the tracker runtime with specified frame and objects. Returns the initial objects and the time it took to initialize the tracker.

Parameters

frame – The frame to initialize the tracker with.
new – The objects to initialize the tracker with.

Returns

Tuple[Objects, float] – The initial objects and the time it took to initialize the tracker.

property multiobject: Returns True if the tracker supports multiple objects, False otherwise.

abstract restart(): Restarts the tracker runtime, usually stars a new process.

run(frames: List[Frame], queries: List[ObjectQuery]) → RunResult

Runs the tracker on the given frames and queries. Returns the tracker output as a RunStatus namedtuple. The online tracker runtime uses the interface defined by the initialize and update methods to run the tracker on the given frames and queries.

Parameters

frames – The frames to run the tracker on.
queries – The queries to run the tracker on.

abstract stop(): Stops the tracker runtime.

property tracker: Tracker: Returns the tracker instance associated with this runtime.

abstract update(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Updates the tracker runtime with specified frame and objects. Returns the updated objects and the time it took to update the tracker.

Parameters

frame – The frame to update the tracker with.
new – The objects to update the tracker with.

Returns

Tuple[Objects, float] – The updated objects and the time it took to update the tracker.

class vot.tracker.RealtimeTrackerRuntime(runtime: TrackerRuntime, grace: int = 1, interval: float = 0.1)

Base class for realtime tracker runtime implementations.

Realtime tracker runtime is responsible for running the tracker executable and communicating with it while simulating given real-time constraints.

initialize(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Initializes the tracker runtime with specified frame and objects. Returns the initial objects and the time it took to initialize the tracker.

Parameters

frame – The frame to initialize the tracker with.
new – The objects to initialize the tracker with.

Returns

Tuple[Objects, float] – The initial objects and the time it took to initialize the tracker.

property multiobject: Returns True if the tracker supports multiple objects, False otherwise.

restart(): Restarts the tracker runtime, usually stars a new process.

stop(): Stops the tracker runtime.

update(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Updates the tracker runtime with specified frame and objects. Returns the updated objects and the time it took to update the tracker.

Note that adding new objects is not supported in realtime tracker runtime, as a frame may be skipped if the tracker fails to update within the specified interval.

Parameters

frame – The frame to update the tracker with.
new – The objects to update the tracker with. Setting new objects is not supported in realtime tracker and will raise an assertion error.

Returns

Tuple[Objects, float] – The updated objects and the time it took to update the tracker.

class vot.tracker.Registry(directories, root='/home/docs/checkouts/readthedocs.org/user_builds/vot-toolkit/checkouts/latest/docs')

Repository of known trackers.

Trackers are loaded from a manifest files in one or more directories.

identifiers()

Returns a list of all tracker identifiers.

Returns: List of tracker identifiers.
Return type: list

references()

Returns a list of all tracker references.

Returns: List of tracker references.
Return type: list

resolve(*references, storage=None, skip_unknown=True, resolve_plural=True)

Resolves the references to trackers.

Parameters

storage (_type_, optional) – Storage to use for resolving references. Defaults to None.
skip_unknown (bool, optional) – Skip unknown trackers. Defaults to True.
resolve_plural (bool, optional) – Resolve plural references. Defaults to True.

Raises

ToolkitException – When a reference cannot be resolved.

Returns

Resolved trackers.

Return type

list

class vot.tracker.RunResult(objects, times): Tuple-like immutable container for full-run tracker output.

class vot.tracker.Tracker(_identifier, _source, command, protocol=None, label=None, version=None, tags=None, storage=None, **kwargs)

Tracker definition class.

describe()

Returns a dictionary containing the tracker description.

Returns: Dictionary containing the tracker description.
Return type: dict

property identifier: str: Returns the identifier of the tracker.

property label

Returns the label of the tracker. If the version is specified, the label will contain the version as well.

Returns: Label of the tracker.
Return type: str

metadata(key): Returns the metadata value for specified key.

property protocol: str

Returns the communication protocol used by this tracker.

Returns: Communication protocol
Return type: str

property reference: str

Returns the reference of the tracker. If the version is specified, the reference will contain the version as well.

Returns: Reference of the tracker.
Return type: str

reversion(version=None) → Tracker

Creates a new tracker instance for specified version.

version {[type]} – New version (default: {None})

Returns: Tracker – [description]

runtime(log=False) → TrackerRuntime: Creates a new runtime instance for this tracker instance.

property source: Returns the source of the tracker.

property storage: Storage: Returns the storage of the tracker results.

tagged(tag)

Returns true if the tracker is tagged with specified tag.

Parameters: tag (str) – The tag to check.
Returns: True if the tracker is tagged with specified tag, False otherwise.
Return type: bool

property version: str

Returns the version of the tracker. If the version is not specified, None is returned.

Returns: Version of the tracker.
Return type: str

exception vot.tracker.TrackerException(*args, tracker, tracker_log=None)

Base class for all tracker related exceptions.

property log: str

Returns the log message of the tracker.

Returns: Log message of the tracker.
Return type: sts

property tracker: Returns the tracker that caused the exception.

class vot.tracker.TrackerRuntime(tracker: Tracker)

Base class for tracker runtime implementations.

Tracker runtime is responsible for running the tracker executable and communicating with it.

property multiobject: Returns True if the tracker supports multiple objects, False otherwise.

run(frames: List[Frame], queries: List[ObjectQuery]) → RunResult

Runs the tracker on the specified frames and queries. Returns a dictionary containing the objects for each query.

Parameters

frames (List[Frame]) – The frames to run the tracker on.
queries (Dict[str, ObjectQuery]) – The queries to run the tracker on.

Returns

A run result containing the objects and times for each query.

Return type

RunResult

abstract stop(): Stops the tracker runtime.

property tracker: Tracker: Returns the tracker instance associated with this runtime.

exception vot.tracker.TrackerTimeoutException(*args, tracker, tracker_log=None): Exception raised when the tracker communication times out.

vot.tracker.is_valid_identifier(identifier)

Checks if the identifier is valid.

Parameters: identifier (str) – The identifier to check.
Returns: True if the identifier is valid, False otherwise.
Return type: bool

vot.tracker.is_valid_reference(reference)

Checks if the reference is valid.

Parameters: reference (str) – The reference to check.
Returns: True if the reference is valid, False otherwise.
Return type: bool

vot.tracker.parse_reference(reference)

Parses the reference into identifier and version.

Parameters: reference (str) – The reference to parse.
Returns: A tuple containing the identifier and the version.
Return type: tuple
Raises: ValueError – If the reference is not valid.

vot.tracker.register_runtime_protocol(protocol, constructor)

Registers a runtime protocol with the given constructor.

Parameters

protocol (str) – The name of the protocol.
constructor (callable) – The constructor for the runtime protocol.

TraX protocol module

TraX protocol implementation for the toolkit.

TraX is a communication protocol for visual object tracking. It enables communication between a tracker and a client. The protocol was originally developed for the VOT challenge to address the need for a unified communication interface between trackers and benchmarking tools.

class vot.tracker.trax.ColorizedOutput: Colorized output for the tracker.

class vot.tracker.trax.LogAggregator: Aggregates log messages from the tracker.

class vot.tracker.trax.PythonCrashHelper: Helper class for detecting Python crashes in the tracker.

class vot.tracker.trax.TestRasterMethods(methodName='runTest')

Tests for the raster methods.

test_convert_region(): Tests the conversion of regions.

test_convert_traxregion(): Tests the conversion of Trax regions.

class vot.tracker.trax.TrackerProcess(command: str, envvars=None, timeout=30, log=False, socket=False)

A tracker process.

This class is used to run trackers in a separate process and handles starting, stopping and communication with the process.

property alive: Whether the tracker process is alive.

property has_vot_wrapper

Whether the tracker has a VOT wrapper.

VOT wrapper limits TraX functionality and injects a property at handshake to let the client know this.

initialize(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Initializes the tracker. This method is used to initialize the tracker with the first frame. It returns the initial state of the tracker.

Parameters

frame – The first frame.
new – The initial state of the tracker.

Returns

The initial state of the tracker.

Raises

TraxException – If the tracker is not alive.

property interrupted: Whether the tracker process was interrupted.

property multiobject: Whether the tracker supports multiple objects.

property returncode: The return code of the tracker process.

terminate()

Terminates the tracker.

This method is used to terminate the tracker. It closes the connection to the tracker and terminates the tracker process.

update(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Updates the tracker with a new frame. This method is used to update the tracker with a new frame. It returns the new state of the tracker.

Parameters

frame – The new frame.
new – The new state of the tracker.

Returns

The new state of the tracker.

Raises

TraxException – If the tracker is not alive.

wait()

Waits for the tracker to terminate.

This method is used to wait for the tracker to terminate. It waits until the tracker process terminates.

property workdir: The working directory of the tracker process.

class vot.tracker.trax.TraxMatlabAdapter

Adapter for running a tracker using the TraX protocol in Matlab.

It only adds the bypass to use socket communication on Windows, which is required for Matlab to work properly.

class vot.tracker.trax.TraxTrackerRuntime(tracker: Tracker, command: str, log: bool = False, timeout: int = 30, linkpaths=None, envvars=None, arguments=None, socket=False, restart=False, onerror=None)

The TraX tracker runtime.

This class is used to run a tracker using the TraX protocol.

initialize(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None, properties: dict = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Initializes the tracker. This method is used to initialize the tracker. It starts the tracker process if it is not running yet.

Parameters

frame – The initial frame.
new – The initial objects.
properties – The initial properties.

Returns

A tuple containing the initial objects and the initial score.

property multiobject: Whether the tracker supports multiple objects.

restart()

Restarts the tracker.

This method is used to restart the tracker. It stops the tracker process and starts it again.

stop()

Stops the tracker.

This method is used to stop the tracker. It stops the tracker process.

property tracker: Tracker: The associated tracker object.

update(frame: Frame, new: Optional[Union[List[ObjectStatus], ObjectStatus]] = None, properties: dict = None) → Tuple[Optional[Union[List[ObjectStatus], ObjectStatus]], float]

Updates the tracker. This method is used to update the tracker state with a new frame.

Parameters

frame – The current frame.
new – The current objects.
properties – The current properties.

Returns

A tuple containing the updated objects and the updated score.

vot.tracker.trax.convert_frame(frame: Frame, channels: list) → dict

Converts a frame to a dictionary of Trax images.

Parameters

frame – The frame to be converted.
channels – The list of channels to be converted.

Returns

A dictionary of Trax images.

vot.tracker.trax.convert_objects(objects: Optional[Union[List[ObjectStatus], ObjectStatus]]) → Region

Converts a list of objects to a Trax region.

Parameters: objects – The list of objects to be converted.
Returns: A Trax region.

vot.tracker.trax.convert_region(region: Region) → Region

Converts a region to a Trax region.

Parameters: region – The region to be converted.
Returns: A Trax region.

vot.tracker.trax.convert_traxobjects(region: Region) → Region

Converts a Trax region to a region.

Parameters: region – The Trax region to be converted.
Returns: A region.

vot.tracker.trax.convert_traxregion(region: Region) → Region

Converts a Trax region to a region.

Parameters: region – The Trax region to be converted.
Returns: A region.

vot.tracker.trax.normalize_paths(paths, tracker): Normalizes a list of paths relative to the tracker source.

vot.tracker.trax.open_local_port(port: int): Opens a local port for listening.

Results module

Results module for storing and retrieving tracker results.

class vot.tracker.results.Results(storage: vot.workspace.Storage)

Generic results interface for storing and retrieving results.

exists(name)

Returns true if the given file exists in the results storage.

Parameters: name (str) – File name
Returns: True if the file exists
Return type: bool

find(pattern)

Returns a list of files matching the given pattern in the results storage.

Parameters: pattern (str) – Pattern
Returns: List of files
Return type: list

read(name)

Returns a file handle for reading the given file from the results storage.

Parameters: name (str) – File name
Returns: File handle
Return type: file

write(name: str)

Returns a file handle for writing the given file to the results storage.

Parameters: name (str) – File name
Returns: File handle
Return type: file

class vot.tracker.results.Trajectory(length: int)

Trajectory class for storing and retrieving tracker trajectories.

equals(trajectory: Trajectory, check_properties: bool = False, overlap_threshold: float = 0.99999)

Returns true if the trajectories are equal.

Parameters

trajectory (Trajectory) – _description_
check_properties (bool, optional) – _description_. Defaults to False.
overlap_threshold (float, optional) – _description_. Defaults to 0.99999.

Returns

_description_

Return type

_type_

classmethod exists(results: Results, name: str) → bool

Returns true if the trajectory exists in the results storage.

Parameters

results (Results) – Results storage
name (str) – Trajectory name (without extension)

Returns

True if the trajectory exists

Return type

bool

classmethod gather(results: Results, name: str) → list

Returns a list of files that are part of the trajectory.

Parameters

results (Results) – Results storage
name (str) – Trajectory name (without extension)

Returns

List of files

Return type

list

properties(frame: int = None) → dict

Returns the properties for the given frame or all properties if frame is None.

Parameters: frame (int, optional) – Frame index. Defaults to None.
Raises: IndexError – Frame index out of bounds
Returns: Properties
Return type: dict

classmethod read(results: Results, name: str) → Trajectory

Reads a trajectory from the results storage.

Parameters

results (Results) – Results storage
name (str) – Trajectory name (without extension)

Returns

Trajectory

Return type

Trajectory

region(frame: int) → Region

Returns the region for the given frame.

Parameters: frame (int) – Frame index
Raises: IndexError – Frame index out of bounds
Returns: Region
Return type: Region

regions() → List[Region]

Returns the list of regions.

Returns: List of regions
Return type: List[Region]

set(frame: int, region: Region, properties: dict = None)

Sets the region for the given frame.

Parameters

frame (int) – Frame index
region (Region) – Region
properties (dict, optional) – Frame properties. Defaults to None.

Raises

IndexError – Frame index out of bounds

write(results: Results, name: str)

Writes the trajectory to the results storage.

Parameters

results (Results) – Results storage
name (str) – Trajectory name (without extension)