Trackers

Centroid

Centroid of a tracked object: x, y.

Bounds

Bounds of a frame: x_min, x_max, y_min, y_max.

class ROI(size, init_mode='manual', scale=1)

Region of interest.

Region that can be tracked by the algorithms throughout the sequence of image frames.

Parameters:

  • size (tuple[float, float]) –

    Size of the region of interest.

    If both tuple’s values are grater than 1 then they are rounded and taken as pixels. Otherwise, if both values are less than 1, the size is taken relative to the video frame size.

  • init_mode (str, optional) –

    ROI’s initialization mode, by default ‘manual’.

    Defines the way ROI initial position is setted.

    The init_mode parameter can be manual or center. These modes are stored in ROI.MANUAL_INIT_MODE and ROI.CENTER_INIT_MODE.

  • scale (float, optional) – Scale of the sample frame to set ROI initial position if init_method is set to 'manual', by default 1.

width

Width of the ROI.

If the width value is between 0 and 1 then this is taken relative to the frames. Otherwise it is a rounded value and taken as pixels.

Type:

float

height

Height of the ROI.

If the height value is between 0 and 1 then this is taken relative to the frames. Otherwise it is a rounded value and taken as pixels.

Type:

float

init_mode

ROI’s initialization mode.

Type:

str

scale

Scale of the sample frame to set ROI initial position if init_method is set to 'manual'.

Type:

float

Examples

>>> ROI((120, 120), ROI.MANUAL_INIT_MODE)
ROI: size=(120, 120) init_mode=manual scale=1
Raises:

  • ValueError – If any size value is negative.

  • ValueError – If one of the size value is grater than 1 and the other is less than 1.

  • ValueError – If ROI initialization mode is neither 'manual' or 'center'.

Parameters:

  • size (tuple[float, float])

  • init_mode (str)

  • scale (float)

MANUAL_INIT_MODE = 'manual'

Manual initialization mode for the ROI

CENTER_INIT_MODE = 'center'

Center initialization mode for the ROI

class ObjectTracker(name, algorithm, roi, preprocessing=None)

Tracks an object inside a ROI according to a tracking algorithm.

Parameters:

  • name (str) – Name of the tracked object.

  • algorithm (TrackingAlgorithm) – Algorithm used to track the object.

  • roi (ROI) – Region of interest where the object will be tracked.

  • preprocessing (Callable[[np.ndarray], np.ndarray], optional) – Preprocessing function aplied to the frame before being used by the algorithm.

name

Name of the tracked object.

Type:

str

algorithm

Algorithm used to track the object.

Type:

TrackingAlgorithm

roi

Region of interest where the object will be tracked.

Type:

ROI

history

ROI’s position in every frame of the video.

Type:

list[Centroid]

preprocessing

Preprocessing function aplied to the frame before being used by the algorithm.

Type:

Callable[[np.ndarray], np.ndarray] | None

class CameraTracker(roi)

Tracks the camera movement.

Parameters:

roi (ROI) – Region of interest where the background changes will be detected.

roi

Region of interest where the background changes will be detected.

Type:

ROI

affine_params_history

History of all the affine parameters

Type:

list[AffineParams]

class TrackingScenario(object_trackers, camera_tracker=None, undistorter=None, preview_scale=1, auto_mode=True)

Controls all the tracking process along the video.

Parameters:

  • object_trackers (list) – Trackers of all the objects.

  • camera_tracker (CameraTracker) – Tracker used to detect camera movements, by default None.

  • undistorter (Undistorter) – Undistorted used to correct each video frame, by default None.

  • preview_scale (float) – Scale of the video preview, by default 1.0.

  • auto_mode (bool) –

    If True the video is processed auomtically otherwise it’s processed manually, by default True.

    If the video is processed manually, pressing ENTER key is necessary in every frame to continue.

    This mode can be changed in the middle of the processing by pressing M key.

object_trackers

Trackers of all the objects

Type:

list

camera_tracker

Tracker used to detect camera movements.

Type:

CameraTracker

undistorter

Undistorted used to correct each video frame.

Type:

Undistorter

preview_scale

Scale of the video preview.

Type:

float

auto_mode

If True the video is processed auomtically otherwise it’s processed manually, by default True.

If the video is processed manually, pressing Enter key is necessary in every frame to continue.

This mode can be changed in the middle of the processing by pressing M key.

Type:

bool

track(video_path, start_frame=0, end_frame=None, pix_per_m=1)

Starts the tracking process.

Parameters:

  • video_path (str) – Path of the video used to track the objects.

  • start_frame (int, optional) – Initial frame in which starts the processing, by default 0.

  • end_frame (int | None) – Last frame being processed, if nothing is passed all frames until the end of the video will be processed, by default None.

  • pix_per_m (int, optional) –

    Pixel per meters, by default 1.

    This value is used to readjuts the trajectories points to a real scale.

Returns:

  • bool – Whether or not the tracking process ended succefully.

  • list[Trajectory] – List of all the trajectories extracted in the tracking process.

Return type:

tuple[bool, list[Trajectory] | None]