Welcome to PyFastTrack’s documentation!

Introduction

PyFastTrack is a Python library that provides an easy-to-use solution to integrate the FastTrack software tracking technology in Python projects. The tracking configuration and results will be entirely compatible with FastTrack.

Installation

pip install pyfasttrack

Examples

 1from pyfasttrack.ft_detector import FtDetector
 2from pyfasttrack.tracker import Tracker
 3from pyfasttrack.data import Result
 4import data as dat
 5import cv2
 6import os
 7
 8example_folder_path = os.path.dirname(os.path.abspath(__file__))
 9
10# Load configuration
11config = dat.Configuration()
12params = config.read_toml(
13    "{}/test/data/images/Groundtruth/Tracking_Result/cfg.toml".format(example_folder_path))
14
15# Data saver
16saver = Result("{}/test/data/images/".format(example_folder_path))
17
18# Set up detector
19detector = FtDetector(params)
20detector.set_background(cv2.imread(
21    "{}/test/data/images/Groundtruth/Tracking_Result/background.pgm".format(example_folder_path), cv2.IMREAD_GRAYSCALE))
22
23# Set up tracker
24tracker = Tracker(params)
25tracker.set_params(params)
26tracker.set_detector(detector)
27
28camera = cv2.VideoCapture(
29    "{}/test/data/images/frame_%06d.pgm".format(example_folder_path))
30dat = tracker.initialize(cv2.cvtColor(camera.read()[1], cv2.COLOR_BGR2GRAY))
31saver.add_data(dat)
32
33ret = True
34while (ret):
35    ret, frame = camera.read()
36    if ret:
37        frame = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
38        dat = tracker.process(frame)
39        saver.add_data(dat)
40
41camera.release()

 1from pyfasttrack.yolo_detector import YoloDetector
 2from pyfasttrack.tracker import Tracker
 3from pyfasttrack.data import Result
 4import cv2
 5import os
 6
 7example_folder_path = os.path.dirname(os.path.abspath(__file__))
 8
 9# Data saver
10saver = Result("{}/test/data/images/".format(example_folder_path))
11
12# Set up detector
13# See https://github.com/ultralytics/ultralytics/blob/44c7c3514d87a5e05cfb14dba5a3eeb6eb860e70/ultralytics/datasets/coco.yaml for equivalence between coco labels and indexes
14yolo_params = {"model": "yolov8l-seg.pt", "classes": [2], "conf": 0.5}
15detector = YoloDetector(yolo_params)
16
17# Set up tracker
18params = {"spot": 2, "normDist": 1, "normAngle": 2,
19          "normArea": 1, "normPerim": 1, "maxDist": 500, "maxTime": 100}
20tracker = Tracker()
21tracker.set_params(params)
22tracker.set_detector(detector)
23
24camera = cv2.VideoCapture(
25    "{}/test/data/images/Nascar.mp4".format(example_folder_path))
26dat = tracker.initialize(camera.read()[1])
27saver.add_data(dat)
28
29ret = True
30while (ret):
31    ret, frame = camera.read()
32    if ret:
33        dat = tracker.process(frame)
34        saver.add_data(dat)
35
36camera.release()

PyFastTrack package

Detector

class pyfasttrack.base_detector.BaseDetector

Bases: object

Abstract class to implement an objects detector.

abstract detect(image)

Abstract method to be implemented.

This method will take a full image with all the objects to detect and will return a list of tuples (mask, left_corner_coordinate [x, y]) with one object by mask, the object represented by non-zero pixels and the background by zero pixels.

Parameters

imagendarray

The full image.

Returns

dict

List of (mask, left_corner_coord).

get_direction(mask, features)

Get the object direction.

The object orientation is updated with the correct direction.

Parameters

maskndarray

Mask of one object.

featuresdict

Object features.

Returns

bool

Is object left oriented.

ndarray

Rotated mask.

ndarray

Rotation matrix.

get_features(mask)

Get the object features using equivalent ellipse.

Parameters

maskndarray

Mask of one object.

static modulo(angle)

Provide the mathematical 2pi modulo.

Parameters

maskfloat

Angle in radian.

Returns

float

Angle between 0->2pi

process(image)

Process one image.

Parameters

imagendarray

The full image.

Returns

list

List of detected objects and their features.

class pyfasttrack.ft_detector.FtDetector(params)

Bases: BaseDetector

Implement the classic FastTrack detector.

detect(image)

Detect objects

Parameters

imagendarray

Image as GRAYSCALE.

Returns

list

List of masks as [(mask, left_corner), …].

set_background(image)

Set the background image.

Parameters

imagendarray

Background image.

class pyfasttrack.yolo_detector.YoloDetector(params)

Bases: BaseDetector

detect(image)

Detect objects

Parameters

imagendarray

Image as BGR.

Returns

list

List of masks as [(mask, left_corner), …].

Tracker

class pyfasttrack.tracker.Tracker(params=None, detector=None)

Bases: object

Tracker class to determine assignment from previous and current coordinates.

static angle_difference(a, b)

Get the minimal difference, a-b), between two angles.

Parameters

afloat

First angle.

bfloat

Second angle.

Returns

float

a-b.

assign(prev, current)

Find the optimal assignent.

Parameters

prevlist

List of dict. Each dict is one object with 4 key “0”, “1”, “2”, “3”. 0,1,2 is the {center, orientation} of the head, tail and body respectively. 3 is {area, perim} of the object.

currentlist

List of dict. Each dict is one object with 4 key “0”, “1”, “2”, “3”. 0,1,2 is the {center, orientation} of the head, tail and body respectively. 3 is {area, perim} of the object.

Returns

list

Assignment.

clean(current, counter, lost, idty)

Delete objects that were lost. Only counter is copied in this function. Other lists act as pointer.

Parameters

currentlist

List to clean.

counterlist

Counter of losses.

lostlist

Lost objects.

idtylist

Objects’ identity

Returns

list

Cleaned list.

list

Updated counter.

compute_cost(var, norm)

Compute the cost.

Parameters

varList

List of variable.

normlist

Normalization coefficient associated to var.

Returns

float

Cost.

static div(a, b)

Division by zero, a/0=0.

Parameters

afloat

Dividend.

bfloat

Divisor.

Returns

float

a/b.

find_lost(assignment)

Find object lost at previous step.

Parameters

assignmentlist

Assignment indexes.

Returns

list

Indexes of lost objects.

initialize(image)

Initialize the tracker.

Parameters

imagendarray

Image, channels depending on the detector.

Returns

list

List of detected objects as dict.

process(image)

Process an image.

Parameters

imagendarray

Image, channels depending on the detector.

Returns

list

List of detected objects as dict.

reassign(past, current, order)

Reassign current based on order.

Parameters

prevlist

List of dict of previous detections.

currentlist

List of dict of current detections.

orderlist

Reassingment

Returns

list

Reordered current.

set_detector(detector)

Set the detector.

Parameters

detectorBaseDetector

Detector that is an implementation of the BaseDetector.

set_params(params)

Set the parameters.

Parameters

paramsdict

Parameters.

Data

class pyfasttrack.data.Configuration

Bases: object

Class to read and write configuration files compatible with FastTrack.

get_key(key)

Get a parameter from its key.

Parameters

keystr

Key.

Returns

Any

Parameter.

get_keys(keys)

Get parameters from their keys.

Parameters

keyslist

List of keys.

Returns

List

Parameters.

read_db(path)

Read a configuration file from database.

Parameters

pathstr

Path pointing to the sqlite database.

Returns

Dict

Parameters.

read_toml(path)

Read a configuration file from text file.

Parameters

pathstr

Path pointing to the toml file.

Returns

Dict

Parameters.

write_toml(path)

Write a configuration file.

Parameters

pathstr

Path pointing to the toml file.

class pyfasttrack.data.Result(path)

Bases: object

Class to write result files compatible with FastTrack.

add_data(dat)

Append data in the database.

Parameters

datdict or list of dicts

Data.