detector Module

Object detection wrapper using YOLOv8 for cat detection.

This module provides a CatDetector class that wraps the Ultralytics YOLOv8 model for detecting cats in video frames. It uses the pre-trained YOLOv8n (nano) model optimized for CPU inference on Raspberry Pi.

The detector filters detections to only return cats (COCO class ID 15) above a configurable confidence threshold.

Example

Basic usage::: detector = CatDetector() detections = detector.detect_cats(frame, threshold=0.5) for det in detections:

print(f”Cat detected with confidence {det.confidence}”)

class detector.Detection(label: str, confidence: float, bbox: Tuple[float, float, float, float])[source]

Bases: object

Represents a detected cat with bounding box and confidence.

label

Object class label (always “cat” for this detector).

Type:: str

confidence

Detection confidence score (0.0 to 1.0).

Type:: float

bbox

Bounding box coordinates as (x1, y1, x2, y2) where: - x1, y1: Top-left corner coordinates - x2, y2: Bottom-right corner coordinates All coordinates are in pixel values relative to the frame.

Type:: Tuple[float, float, float, float]

Example

>>> det = Detection(label="cat", confidence=0.85, bbox=(100, 50, 200, 150))
>>> x1, y1, x2, y2 = det.bbox
>>> print(f"Cat at ({x1}, {y1}) to ({x2}, {y2}) with {det.confidence:.0%} confidence")

label: str

confidence: float

bbox: Tuple[float, float, float, float]

__init__(label: str, confidence: float, bbox: Tuple[float, float, float, float]) → None

class detector.CatDetector(model_path: str = None, device: str = 'cpu')[source]

Bases: object

Wrapper for YOLOv8 model optimized for cat detection on CPU.

Uses the Ultralytics YOLOv8n (nano) model, which is lightweight enough for real-time inference on Raspberry Pi CPU. Filters detections to only return cats (COCO class ID 15) above the confidence threshold.

model: Loaded YOLOv8 model instance.

imgsz: Input image size for the model (from config, typically 640).

Example

>>> detector = CatDetector()
>>> detections = detector.detect_cats(frame, threshold=0.5)
>>> if detections:
...     print(f"Found {len(detections)} cat(s)")

__init__(model_path: str = None, device: str = 'cpu')[source]

Initialize the detector with YOLOv8 model.

Parameters:

model_path – Path to YOLO model file (will download if not exists). If None, uses value from config file.
device – Device to run inference on (‘cpu’ or ‘cuda’)

detect_cats(frame: ndarray, threshold: float = None) → List[Detection][source]

Detect cats in a frame.

Parameters:

frame – BGR image as numpy array (OpenCV format)
threshold – Minimum confidence threshold for detections. If None, uses value from config file.

Returns:

List of Detection objects for cats above the threshold