main Module

Main entry point for cat detection and recording system.

This module provides the command-line interface and main monitoring loop for a Raspberry Pi-based cat detection and video recording system. It uses an IR camera (picamera2), YOLOv8 object detection model, and OpenCV for video processing and recording.

The system continuously monitors camera input, detects cats using a pre-trained YOLOv8 model, and automatically records video clips when cats are detected.

Example

Basic usage with default settings::

python3 main.py

With custom output directory::

python3 main.py –output-dir /mnt/nfs

Test camera recording (10 seconds, no detection)::

python3 main.py –test-record

With preview window::

python3 main.py –show-preview

main.parse_resolution(resolution_str: str) → Tuple[int, int]

Parse resolution string in format ‘WIDTHxHEIGHT’.

Converts a resolution string like “640x480” into a tuple of integers. The format is case-insensitive and accepts ‘x’ or ‘X’ as separator.

Parameters:

resolution_str – Resolution string in format ‘WIDTHxHEIGHT’, e.g., ‘640x480’, ‘1920x1080’, or ‘3280x2464’.

Returns:

Tuple of (width, height) as integers.

Raises:

ValueError – If the format is invalid, contains non-numeric values, or if width/height are not positive integers.

Example

>>> parse_resolution("640x480")
(640, 480)
>>> parse_resolution("1920X1080")
(1920, 1080)

main.draw_detections(frame: ndarray, detections: List[Detection]) → None

Draw bounding boxes and labels on frame for detected cats.

Draws green bounding boxes around detected cats and adds a label showing the object class and confidence score. The frame is modified in-place.

Parameters:

• frame – Frame to draw on (BGR numpy array, shape: [height, width, 3]). Must be writable and contiguous.

• detections – List of Detection objects containing bounding box coordinates and confidence scores.

Note

The frame must be writable. If using frames from picamera2, ensure they are converted to writable format using camera._convert_frame().

Example

>>> detections = [Detection(label="cat", confidence=0.85, bbox=(100, 50, 200, 150))]
>>> draw_detections(frame, detections)
# Frame now has green bounding box and label drawn

main.setup_logging(log_level: str = 'INFO') → None

Configure logging for the application.

Sets up Python’s logging module with a standard format that includes timestamp, logger name, level, and message. This is called early in main() to ensure all modules can use logging.

Parameters:

log_level – Logging level string. Must be one of: “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”. Case-insensitive.

Raises:

ValueError – If log_level is not a valid logging level.

Example

>>> setup_logging("DEBUG")
# All modules can now use logging.getLogger(__name__)

main.main() → None

Main entry point and monitoring loop for cat detection system.

This function:

1. Parses command-line arguments (with config file fallback)

2. Initializes camera, detector, and recorder

3. Runs the main monitoring loop: - Continuously reads frames from camera - Detects cats using YOLOv8 model - Starts recording when cats are detected - Records for configured duration

4. Handles cleanup and error conditions

The function supports two modes: - Normal mode: Continuous monitoring with cat detection - Test mode: Record 10 seconds of camera footage (–test-record)

Command-line arguments override values from config.yaml. See –help for all available options.

Exit codes:

0: Normal exit (Ctrl+C or successful completion) 1: Error (camera failure, invalid arguments, etc.)

Raises:

SystemExit – On invalid arguments or critical errors.