Detections Module

The detections module provides functionality for detecting objects in imagery and managing detection data.

Core Classes

detector.Detector

Collection of detection points from a detection algorithm or manual creation.

Detection Algorithms

VISTA provides several detection algorithms:

• Threshold Detection: Simple intensity-based detection

• CFAR Detection: Constant False Alarm Rate detection for adaptive thresholding

See Object Detection for detailed information on each algorithm.

Basic Usage

Creating a Detector

from vista.detections import Detector

# Create a detector instance
detector = Detector(name="My Detector")

# Add detection parameters
detector.threshold = 10.0

Running Detection

from vista.algorithms.detectors.threshold import simple_threshold_detector

# Run detection on imagery
detections = simple_threshold_detector(
    imagery.data,
    threshold=10.0,
    min_area=5
)

Module Reference

class vista.detections.detector.Detector(name, frames, rows, columns, sensor, description='', color='r', marker='o', marker_size=10, line_thickness=2, visible=True, complete=False, labels=<factory>)

Bases: object

Collection of detection points from a detection algorithm or manual creation.

A Detector represents a set of detected objects or points of interest across multiple frames. Unlike Tracks, detections are unassociated points without temporal continuity. Each detection point can have its own set of labels.

Parameters:

• name (str) – Unique identifier for this detector

• frames (NDArray[np.int_]) – Frame numbers where detections occur

• rows (NDArray[np.float64]) – Row (vertical) pixel coordinates for each detection

• columns (NDArray[np.float64]) – Column (horizontal) pixel coordinates for each detection

• sensor (Sensor) – Sensor object associated with these detections

• description (str, optional) – Description of detection algorithm or method, by default “”

color

Color for detection markers, by default ‘r’ (red)

Type:

str, optional

marker

Marker style (‘o’, ‘s’, ‘t’, ‘d’, ‘+’, ‘x’, ‘star’), by default ‘o’ (circle)

Type:

str, optional

marker_size

Size of detection markers, by default 10

Type:

int, optional

line_thickness

Thickness of marker outline, by default 2

Type:

int, optional

visible

Whether detections are visible in viewer, by default True

Type:

bool, optional

labels

List of label sets, one set per detection point, by default empty list

Type:

list[set[str]], optional

__getitem__(slice)

Slice detector by index or boolean mask

from_dataframe(df, sensor, name)

Create Detector from pandas DataFrame

copy()

Create a deep copy of the detector

to_csv(file)

Save detector to CSV file

to_dataframe()

Convert detector to pandas DataFrame

get_unique_labels()

Get all unique labels across all detections

Notes

• Detections are unassociated points (unlike tracks which represent trajectories)

• Multiple detections can exist at the same frame

• Labels are per-detection, allowing individual detection categorization

• Detection coordinates are always in pixel space (row/column)

name: str

frames: ndarray[tuple[Any, ...], dtype[int64]]

rows: ndarray[tuple[Any, ...], dtype[float64]]

columns: ndarray[tuple[Any, ...], dtype[float64]]

sensor: Sensor

description: str = ''

color: str = 'r'

marker: str = 'o'

marker_size: int = 10

line_thickness: int = 2

visible: bool = True

complete: bool = False

labels: list[set[str]]

uuid: str = None

get_detections_at_frame(frame_num)

Get detection coordinates at a specific frame using O(1) cached lookup.

Parameters:

frame_num (int) – Frame number to query

Returns:

• rows (NDArray) – Row coordinates of detections at this frame

• cols (NDArray) – Column coordinates of detections at this frame

invalidate_caches()

Invalidate cached data structures when detector data changes.

get_pen(width=None, **kwargs)

Get cached PyQtGraph pen object, creating only if parameters changed.

Parameters:

width (int, optional) – Line width override, uses self.line_thickness if None

Returns:

PyQtGraph pen object

Return type:

pg.mkPen

classmethod from_dataframe(df, sensor, name=None)

Create Detector from pandas DataFrame.

Parameters:

• df (pd.DataFrame) – DataFrame containing detection data with required columns: “Detector”, “Frames”, “Rows”, “Columns”

• sensor (Sensor) – Sensor object for these detections

• name (str, optional) – Detector name, by default taken from df[“Detector”]

Returns:

New Detector object

Return type:

Detector

Notes

Optional styling columns: “Color”, “Marker”, “Marker Size”, “Line Thickness”, “Visible”, “Labels”

Labels should be comma-separated strings in the “Labels” column.

copy()

Create a deep copy of this detector object.

Returns:

New Detector object with copied arrays and styling attributes

Return type:

Detector

to_csv(file)

to_dataframe()

get_unique_labels()

Get all unique labels across all detections in this detector.

Returns:

Set of all unique label strings used by any detection point

Return type:

set[str]

__init__(name, frames, rows, columns, sensor, description='', color='r', marker='o', marker_size=10, line_thickness=2, visible=True, complete=False, labels=<factory>)