Configuration File - RTSP Human Capture

Overview

RTSP Human Capture uses an INI-style configuration file (default: config.cfg) to specify paths, detection parameters, and processing settings. Command-line flags override individual config values when provided.

File Format

The configuration file uses standard INI syntax with sections denoted by [section_name] and key-value pairs:

[paths]
model_dir = model
output_dir = output

[detection]
confidence_threshold = 0.5
person_area_threshold = 1000
frame_skip = 15

Configuration Sections

[paths]

File system paths for model files and output directories.

string

default:"model"

Directory containing YOLO model files (yolov4.weights, yolov4.cfg, coco.names).Required files:

yolov4.weights or yolov3.weights - Model weights
yolov4.cfg or yolov3.cfg - Model configuration
coco.names - Class labels (80 COCO classes)

Download sources:

Fallback behavior: If YOLO files are not found, the system automatically falls back to OpenCV’s built-in HOG (Histogram of Oriented Gradients) person detector.Example:

[paths]
model_dir = /opt/models/yolo

string

default:"output"

Base directory where captured images or video clips are saved.Directory structure:

Single stream: Files saved directly to output_dir/
Multiple streams: Files saved to output_dir/stream_{id}/

Filename formats:

Images: person_entry_{count}_{timestamp}_{unix_time}.jpg
Videos: person_clip_{count}_{timestamp}_{unix_time}.mp4

Example:

[paths]
output_dir = /var/captures/persons

Note: Directories are created automatically if they don’t exist.

[detection]

Person detection parameters and processing settings.

float

default:"0.5"

Minimum confidence score (0.0 to 1.0) for a detection to be considered valid.Valid range: Must be between 0.0 (exclusive) and 1.0 (exclusive).Validation: Raises ValueError if outside valid range.Behavior:

Lower values (0.3-0.5): More detections, more false positives
Medium values (0.5-0.7): Balanced accuracy
Higher values (0.7-0.9): Fewer false positives, may miss some people

Example:

[detection]
confidence_threshold = 0.6

Override: Use --confidence CLI flag to override this value.

integer

default:"1000"

Minimum bounding box area in pixels (width × height) for a detection to be considered valid.Valid range: Must be >= 0.Validation: Raises ValueError if negative.Purpose: Filters out very small detections which are often:

Distant persons (too far to be useful)
Partial detections
False positives

Calculation example:

A 50×50 pixel box = 2,500 pixels (passes default threshold)
A 30×30 pixel box = 900 pixels (rejected by default threshold)

Recommended values:

Close-range cameras: 500-1000 pixels
Medium-range cameras: 1000-2000 pixels
Long-range cameras: 2000-5000 pixels

Example:

[detection]
person_area_threshold = 1500

Override: Use --area-threshold CLI flag to override this value.

integer

default:"15"

Process every Nth frame from the video stream. Frames in between are still captured for video recording but not analyzed for person detection.Valid range: Must be >= 1.Validation: Raises ValueError if less than 1.Performance impact:

frame_skip = 1: Analyze every frame (slowest, highest accuracy)
frame_skip = 15: ~2 detections/second on 30fps stream (recommended)
frame_skip = 30: ~1 detection/second on 30fps stream (faster)
frame_skip = 60: ~0.5 detections/second on 30fps stream (fastest)

Additional throttling: Detection is also limited to run at most once every 0.5 seconds (see stream_processor.py:113 and stream_processor.py:303).Example:

[detection]
frame_skip = 20

Override: Use --frame-skip CLI flag to override this value.

Complete Configuration Example

# RTSP Human Capture Configuration
# This file controls model paths, output locations, and detection parameters

[paths]
# Directory containing YOLO model files
model_dir = model

# Directory where person captures are saved
output_dir = output

[detection]
# Minimum confidence for person detection (0.0 - 1.0)
# Higher = fewer false positives, but may miss some people
confidence_threshold = 0.5

# Minimum bounding box area in pixels
# Filters out very small/distant detections
person_area_threshold = 1000

# Process every Nth frame (higher = faster but may miss brief appearances)
# At 30fps, frame_skip=15 means ~2 detections per second
frame_skip = 15

Loading Configuration

Configuration is loaded using the load_config() function from the config module:

from config import load_config, DEFAULT_CONFIG_PATH

# Load default config.cfg from current directory
cfg = load_config()

# Load custom config file
cfg = load_config("production.cfg")

# Access configuration values
print(f"Model directory: {cfg.model_dir}")
print(f"Output directory: {cfg.output_dir}")
print(f"Confidence threshold: {cfg.confidence_threshold}")

Configuration Object

The loaded configuration is returned as an AppConfig dataclass:

dataclass

Show fields

str

Path to model directory (from [paths] model_dir)

str

Path to output directory (from [paths] output_dir)

float

Confidence threshold (from [detection] confidence_threshold)

int

Minimum person area (from [detection] person_area_threshold)

int

Frame skip interval (from [detection] frame_skip)

Validation Rules

The configuration loader validates all values and raises exceptions for invalid data:

Confidence Threshold Validation

if not 0.0 < confidence_threshold < 1.0:
    raise ValueError(
        f"confidence_threshold must be between 0 and 1, got {confidence_threshold}"
    )

Valid: 0.1, 0.5, 0.9
Invalid: 0.0, 1.0, 1.5, -0.1

Person Area Threshold Validation

if person_area_threshold < 0:
    raise ValueError(
        f"person_area_threshold must be >= 0, got {person_area_threshold}"
    )

Valid: 0, 1000, 5000
Invalid: -1, -1000

Frame Skip Validation

if frame_skip < 1:
    raise ValueError(f"frame_skip must be >= 1, got {frame_skip}")

Valid: 1, 15, 30
Invalid: 0, -1

Error Handling

Missing Configuration File

If the specified config file doesn’t exist:

raise FileNotFoundError(
    f"Config file not found: '{path}'. "
    f"Create one or copy the default config.cfg."
)

CLI output:

Error: Config file not found: 'config.cfg'. Create one or copy the default config.cfg.

Invalid Configuration Values

If validation fails:

raise ValueError("confidence_threshold must be between 0 and 1, got 1.5")

CLI output:

Config error: confidence_threshold must be between 0 and 1, got 1.5

Default Fallback Values

If a key is missing from the config file, the system uses these defaults:

Section	Key	Default Value
`[paths]`	`model_dir`	`"model"`
`[paths]`	`output_dir`	`"person"`
`[detection]`	`confidence_threshold`	`0.5`
`[detection]`	`person_area_threshold`	`1000`
`[detection]`	`frame_skip`	`15`

This means a minimal config file can contain just the values you want to change:

[detection]
confidence_threshold = 0.7

All other values will use defaults.

Override Hierarchy

Configuration values can be overridden in this order (highest priority first):

CLI flags - --confidence, --area-threshold, --frame-skip
Config file - Values from config.cfg or custom path
Default values - Hardcoded fallbacks in config.py

Example:

# Config file has confidence_threshold = 0.5
# This command uses 0.7 instead
python main.py --config custom.cfg --rtsp 'rtsp://cam.com' --confidence 0.7 --save image

Implementation Reference

Configuration loading is implemented in config.py:30-77. The load_config() function uses Python’s configparser module with fallback values for all keys.

​Overview

​File Format

​Configuration Sections

​[paths]

​[detection]

​Complete Configuration Example

​Loading Configuration

​Configuration Object

​Validation Rules

​Confidence Threshold Validation

​Person Area Threshold Validation

​Frame Skip Validation

​Error Handling

​Missing Configuration File

​Invalid Configuration Values

​Default Fallback Values

​Override Hierarchy

​Implementation Reference

Overview

File Format

Configuration Sections

[paths]

[detection]

Complete Configuration Example

Loading Configuration

Configuration Object

Validation Rules

Confidence Threshold Validation

Person Area Threshold Validation

Frame Skip Validation

Error Handling

Missing Configuration File

Invalid Configuration Values

Default Fallback Values

Override Hierarchy

Implementation Reference