Overlays#

Graphical overlays for QVideoScreen.

Each overlay is a pyqtgraph.GraphicsObject subclass that renders analysis results directly on the live video image. A companion QGroupBox widget owns the background worker thread, exposes analysis parameters, and forwards results via a newData signal.

Typical usage:

widget = QTrackpyWidget(parent)   # or QYoloWidget
widget.source = camera_source
screen.addOverlay(widget.overlay)
widget.newData.connect(my_slot)

Trackpy#

QTrackpyWidget detects bright particles in each video frame using the trackpy library, which implements the Crocker–Grier algorithm [CG96]. Detected positions are rendered in real time as a scatter-plot overlay by QTrackpyOverlay. Particle diameter and minimum separation are adjustable from the widget.

[CG96]

J.C. Crocker and D.G. Grier, “Methods of digital video microscopy for colloidal studies”, Journal of Colloid and Interface Science, 179(1):298–310, 1996.

Real-time particle tracking overlay using trackpy.

References

Allan, D. B., Caswell, T., Keim, N. C., van der Wel, C. M., & Verweij, R. W. trackpy: Fast, Friendly Particle Tracking in Python. Zenodo. https://doi.org/10.5281/zenodo.9971

Crocker, J. C., & Grier, D. G. (1996). Methods of digital video microscopy for colloidal studies. Journal of Colloid and Interface Science, 179(1), 298-310. https://doi.org/10.1006/jcis.1996.0217

class QVideo.overlays.trackpy.QTrackpyWidget(parent=None, diameter=11, minmass=100.0, separation=None, noise_size=1, invert=False)[source]#

Bases: QGroupBox

Control widget for the trackpy particle-tracking overlay.

Runs trackpy.locate() in a background thread and renders detected particle positions as a QTrackpyOverlay scatter plot on a QVideoScreen.

Use screen.addOverlay(widget.overlay) to register the overlay graphics item with a screen, and set source to supply video frames.

Parameters:

parent (QtWidgets.QWidget or None) – Parent widget.
diameter (int) – Initial expected particle diameter [pixels]. Must be odd. Default: 11.
minmass (float) – Initial minimum integrated brightness. Default: 100.
separation (float or None) – Minimum separation between particle centers [pixels]. None (default) lets trackpy choose (diameter + 1).
noise_size (int) – Radius of the Gaussian blur applied for noise suppression [pixels]. Default: 1.
invert (bool) – If True, invert the image before locating particles (for dark particles on a bright background). Default: False.

newData#: Emitted for each processed frame with the trackpy.locate() DataFrame, or None on error.

property source#: The QVideoSource being tracked.

property overlay: QTrackpyOverlay#: The QTrackpyOverlay graphics item for this widget.

closeEvent(event)[source]#

Stop the worker thread when the widget is closed.

Return type:: None

class QVideo.overlays.trackpy.QTrackpyOverlay(**kwargs)[source]#

Bases: ScatterPlotItem

Scatter-plot overlay that marks trackpy particle positions.

A pyqtgraph.ScatterPlotItem pre-configured for particle display. Add it to a QVideoScreen via screen.view.addItem(overlay), or use screen.addOverlay(widget.overlay).

setFeatures(features)[source]#

Update scatter positions from a trackpy DataFrame.

Parameters:: features (pandas.DataFrame or None) – DataFrame with x and y columns returned by trackpy.locate(). None or an empty frame clears the overlay.
Return type:: None

YOLO#

QYoloWidget runs a YOLO object-detection model on each video frame. Detected bounding boxes and class labels are rendered in real time by QYoloOverlay. The confidence threshold can be adjusted from the widget; any model supported by the Ultralytics library can be selected at construction time.

Real-time object detection overlay using YOLO.

References

Jocher, G., Chaurasia, A., & Qiu, J. (2023). Ultralytics YOLO. ultralytics/ultralytics

Redmon, J., Divvala, S., Girshick, R., & Farhadi, A. (2016). You only look once: Unified, real-time object detection. Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition, 779-788. https://doi.org/10.1109/CVPR.2016.91

class QVideo.overlays.yolo.QYoloWidget(parent=None, model_name='yolo11n.pt', confidence=0.25)[source]#

Bases: QGroupBox

Control widget for the YOLO object-detection overlay.

Runs YOLO inference in a background thread and renders detected object bounding boxes as a QYoloOverlay on a QVideoScreen.

Use screen.addOverlay(widget.overlay) to register the overlay graphics item with a screen, and set source to supply video frames.

Parameters:

parent (QtWidgets.QWidget or None) – Parent widget.
model_name (str) – YOLO model weights file. Default: 'yolo11n.pt'.
confidence (float) – Initial confidence threshold. Default: 0.25.

newData#: Emitted for each processed frame with the detections DataFrame, or None on error / no detections.

property source#: The QVideoSource being analyzed.

property overlay: QYoloOverlay#: The QYoloOverlay graphics item for this widget.

closeEvent(event)[source]#

Stop the worker thread when the widget is closed.

Return type:: None

class QVideo.overlays.yolo.QYoloOverlay[source]#

Bases: GraphicsObject

Bounding-box overlay that marks YOLO detected objects.

A pyqtgraph.GraphicsObject that draws axis-aligned bounding boxes over detected objects. Add it to a QVideoScreen via screen.addOverlay(widget.overlay).

boundingRect()[source]#

Return type:: QRectF

paint(painter, option, widget=None)[source]#

Draw bounding boxes for all current detections.

Return type:: None

setFeatures(features)[source]#

Update bounding boxes from a YOLO detections DataFrame.

Parameters:: features (pandas.DataFrame or None) – DataFrame with x1, y1, x2, y2 columns returned by _YoloWorker. None or empty clears the overlay.
Return type:: None