Algorithms

Bounds

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

class BackgroundEstimator

This class provides static methods to determine the background in image sequences. It estimates the temporal median of the sequence.

static from_video(video_path, samples, start_in=0)

This method takes a video indicated by video_path and uniformely take a number of image samples according to the parameter samples. Then, it computes the temporal median of the images in order to determine de background.

Parameters:

  • video_path (str) – Path to the video file

  • samples (int) – Number of samples to get from the video.

  • start_in (int, optional) – If passed, the method will start sampling after the frame indicated by this value, by default 0.

Returns:

Median image of the samples taken from the video.

Return type:

np.ndarray

class TrackingAlgorithm

Abstract class to model a Tracking Algorithm. Classes inheriting from this class should implement detect method.

get_centroid(bin_img)

Computes the centroid of a binary image using cv2.moments.

Parameters:

bin_img (np.ndarray) – Binary image used to compute a centroid

Returns:

x, y coordinates of the centroid. None if no object was detected.

Return type:

tuple [int, int] | None

preprocess(frame, roi_bound=None, preprocessing=None)

Preprocesses a frame.

Parameters:

  • frame (np.ndarray) – Frame to preprocess

  • roi_bound (Bounds | None) – If passed, the method will crop the frame to the region of interest defined by the tuple.

  • preprocessing (Callable[[np.ndarray], np.ndarray] | None) – If passed, the method will apply the preprocessing function to the frame.

Returns:

Preprocessed frame

Return type:

np.ndarray

abstract detect(frame, roi_bound=None, preprocessing=None)

Abstract method that is implemented on inheriting classes. It should compute the location (in the image frame) of the object being tracked.

Parameters:

  • frame (np.ndarray) – Image where the algorithm must identify the object

  • roi_bound (Bounds | None) – Coordinates of the region of interest of the frame. The expected format if a tuple with the form (xmin, xmax, ymin, ymax). If passed the algorithm will crop this region of the frame and will proceed only in this region, providing the estimations refered to this region instead of the whole image, by default None.

  • Callable[[np.ndarray] (preprocessing =) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • None (np.ndarray] |) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • preprocessing (Callable[[ndarray], ndarray] | None)

Return type:

tuple[ndarray | None, tuple[int, int] | None]

class ColorMatching(lower_bound=(0, 0, 0), upper_bound=(255, 255, 255), color_space='BGR', max_pixels=None)

Identifies the position of an object by thresholding pixel color values in the pre-defined ranges.

Parameters:

  • lower_bound (tuple, optional) – Minimum value of pixel color to be considered as part of the object, by default (0,0,0)

  • upper_bound (tuple, optional) – Maximum value of pixel color to be considered as part of the object, by default (255,255,255)

  • color_space (str, optional) – Color space to be used before thresholding with the given bounds. The image will be automatically converted to this color space, by default ‘BGR’.

  • max_pixels (int, optional) – If this parameter is passed, the algoritm will stop searching for candidate pixels after reaching a count equal to this value, by default None.

detect(frame, roi_bound=None, preprocessing=None)

Identifies the tracked object in the image frame by thresholding it using the bound parameters defined when the object was constructed.

Parameters:

  • frame (np.ndarray) – Image containing the object to be tracked

  • roi_bound (Bounds | None) – Coordinates of the region of interest of the frame. The expected format if a tuple with the form (xmin, xmax, ymin, ymax). If passed the algorithm will crop this region of the frame and will proceed only in this region, providing the estimations refered to this region instead of the whole image, by default None.

  • Callable[[np.ndarray] (preprocessing =) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • None (np.ndarray] |) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • preprocessing (Callable[[ndarray], ndarray] | None)

Returns:

  • np.ndarray | None – A binary version of frame where elements with value 0 indicate the absence of object and 1 the precense of the object.

  • tuple[int, int] | None – x, y coordinates of the centroid of the object in the image.

Return type:

tuple[ndarray | None, tuple[int, int] | None]

class FrameDifferencing(frame_diff_threshold=1)

Identifies the position of an object by comparison between consecutive frames

Parameters:

frame_diff_threshold (int, optional) – Minimum difference (in terms of pixel intensity) among current and previous image to consider that pixel as part of a moving object, by default 1.

detect(frame, roi_bound=None, preprocessing=None)

Identifies the tracked object in the image frame by comparing the difference with the previous frames. All the pixels differing by more than frame_diff_threshold will be considered part of the moving object.

Parameters:

  • frame (np.ndarray) – Image containing the object to be tracked

  • roi_bound (Bounds | None) – Coordinates of the region of interest of the frame. The expected format if a tuple with the form (xmin, xmax, ymin, ymax). If passed the algorithm will crop this region of the frame and will proceed only in this region, providing the estimations refered to this region instead of the whole image, by default None.

  • Callable[[np.ndarray] (preprocessing =) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • None (np.ndarray] |) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • preprocessing (Callable[[ndarray], ndarray] | None)

Returns:

  • np.ndarray | None – A binary version of frame where elements with value 0 indicate the absence of object and 1 the precense of the object.

  • Otional[tuple[int, int]] – x, y coordinates of the centroid of the object in the image.

Return type:

tuple[ndarray | None, tuple[int, int] | None]

class BackgroundSubtraction(background, background_threshold)

Identifies the position of an object by subtracting a known background.

Parameters:

  • background (np.ndarray) – Image containing the actual background of the scene where the images were taken. This algorithm will detect as an object of interest everything that differs from the background.

  • background_threshold (int, optional) – Minimum difference (in terms of pixel intensity) among current image and background to consider that pixel as part of a moving object, by default 1.

detect(frame, roi_bound=None, preprocessing=None)

Identifies the tracked object in the image frame by comparing the difference with the background. All the pixels differing by more than background_threshold will be considered part of the moving object.

Parameters:

  • frame (np.ndarray) – Image containing the object to be tracked

  • roi_bound (Bounds | None) – Coordinates of the region of interest of the frame. The expected format if a tuple with the form (xmin, xmax, ymin, ymax). If passed the algorithm will crop this region of the frame and will proceed only in this region, providing the estimations refered to this region instead of the whole image, by default None.

  • Callable[[np.ndarray] (preprocessing =) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • None (np.ndarray] |) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • preprocessing (Callable[[ndarray], ndarray] | None)

Returns:

  • np.ndarray | None – A binary version of frame where elements with value 0 indicate the absence of object and 1 the precense of the object.

  • tuple[int, int] | None – x, y coordinates of the centroid of the object in the image.

Return type:

tuple[ndarray | None, tuple[int, int] | None]

class TemplateMatching(template, threshold)

Identifies the position of an object by correlating with a template.

Parameters:

  • template (np.ndarray) – Image containing a template of a tipical image of the object being tracked. This algorithm will detect as an object of interest the point with higher correlation between the template and the image.

  • threshold (float, optional) – Minimum value of correlation to be considered as a match, by default 0.8.

detect(frame, roi_bound=None, preprocessing=None)

Identifies the tracked object in the image frame by comparing each region with a template. The region with higher correlation will be selected as the current position of the object.

Parameters:

  • frame (np.ndarray) – Image containing the object to be tracked

  • roi_bound (Bounds | None) – Coordinates of the region of interest of the frame. The expected format if a tuple with the form (xmin, xmax, ymin, ymax). If passed the algorithm will crop this region of the frame and will proceed only in this region, providing the estimations refered to this region instead of the whole image, by default None.

  • preprocessing (Callable[[np.ndarray], np.ndarray] | None) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

Returns:

  • np.ndarray | None – A binary version of frame where elements with value 0 indicate the absence of object and 1 the precense of the object.

  • tuple[int, int] | None – x, y coordinates of the centroid of the object in the image.

Return type:

tuple[ndarray | None, tuple[int, int] | None]

class OpticalFlow(threshold, buffer_size=1)

This class implements optical flow based on Gunner Farneback’s algorithm. A section of the frame is selected and tracked using dense optical flow.

Parameters:

  • threshold (float) – Minimum value for the magnitude of optical flow to be considered part of the motion.

  • buffer_size (int, optional) – Indicates how many frames in the past the algorithm is going to look before computing the optical flow, by default 1.

detect(frame, roi_bound=None, preprocessing=None)

Identifies the tracked object in the image frame by tracking the motion of a region using optical flow.

Parameters:

  • frame (np.ndarray) – Image containing the object to be tracked

  • roi_bound (Bounds | None) – Coordinates of the region of interest of the frame. The expected format if a tuple with the form (xmin, xmax, ymin, ymax). If passed the algorithm will crop this region of the frame and will proceed only in this region, providing the estimations refered to this region instead of the whole image, by default None.

  • Callable[[np.ndarray] (preprocessing =) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • None (np.ndarray] |) – A function to be applied to the frame (Or cropped version of it if roi_bound is passed) before detecting the object on it, by default None.

  • preprocessing (Callable[[ndarray], ndarray] | None)

Returns:

  • np.ndarray – A binary version of frame where elements with value 0 indicate the absence of object and 1 the precense of the object.

  • tuple[int, int] | None – x, y coordinates of the centroid of the object in the image.

Return type:

tuple[ndarray | None, tuple[int, int] | None]