Installation

Prerequisites

Python 3.12+

RTSP Human Capture requires Python 3.12 or higher. Check your Python version:

python --version

If you need to install or upgrade Python, visit python.org.

uv Package Manager

This project uses uv for fast, reliable dependency management.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Verify the installation:

uv --version

Clone the Repository

Clone the RTSP Human Capture repository:

git clone https://github.com/itsyourap/rtsp-human-capture
cd rtsp-human-capture

Install Dependencies

Install all required dependencies using uv:

uv sync

This command reads pyproject.toml and installs:

numpy>=2.4.3
opencv-contrib-python (from local CUDA wheels if available)

The uv sync command creates a virtual environment automatically and installs all dependencies in one step.

Fallback for CPU-Only Systems

If uv sync fails due to missing OpenCV CUDA wheels, install the CPU-only version:

uv pip install opencv-python

The CPU-only version will work but won’t benefit from GPU acceleration. For best performance, use the CUDA-enabled wheels.

Optional: CUDA GPU Acceleration

For hardware-accelerated inference on NVIDIA GPUs:

1. Verify CUDA Installation

Check if CUDA is available on your system:

nvidia-smi

If this command fails, install NVIDIA CUDA Toolkit.

2. Install OpenCV CUDA Wheels

Download the appropriate CUDA-enabled OpenCV wheel for your platform:

Visit opencv-python-cuda-wheels releases
Download the opencv_contrib_python-*.whl file matching your:
- Python version (e.g., cp312 for Python 3.12)
- Platform (e.g., win_amd64, linux_x86_64)
- CUDA version (e.g., cuda12x)
Create a deps/ directory and place the wheel file there:

mkdir -p deps
# Move your downloaded wheel to deps/
mv opencv_contrib_python-*.whl deps/

Update pyproject.toml to reference your specific wheel:

[tool.uv.sources]
opencv-contrib-python = { path = "deps/opencv_contrib_python-4.13.0.90-cp312-cp312-linux_x86_64.whl" }

Reinstall dependencies:

uv sync --reinstall

The application will automatically detect CUDA at runtime and use GPU acceleration if available. No code changes needed!

Download Model Files

For YOLOv4 detection (recommended), download these files:

Create model directory

mkdir -p model

Download YOLOv4 weights

cd model
wget https://github.com/AlexeyAB/darknet/releases/download/darknet_yolo_v3_optimal/yolov4.weights

Download YOLOv4 config

wget https://raw.githubusercontent.com/AlexeyAB/darknet/master/cfg/yolov4.cfg

Download COCO class names

wget https://raw.githubusercontent.com/AlexeyAB/darknet/master/data/coco.names
cd ..

Model Files Reference

File	Size	Description
`yolov4.weights`	~245 MB	Pre-trained YOLOv4 model weights
`yolov4.cfg`	~12 KB	YOLOv4 network architecture configuration
`coco.names`	~1 KB	COCO dataset class labels (80 classes)

Model files are optional! If not provided, the tool automatically falls back to OpenCV’s built-in HOG person detector. YOLOv3 files are also supported as a fallback before HOG.

Verify Installation

Verify that everything is installed correctly:

uv run main.py --help

You should see the command-line help output:

usage: main.py [-h] [--config CONFIG] [--rtsp RTSP] [--rtsp-list RTSP_LIST [RTSP_LIST ...]]
               [--rtsp-file RTSP_FILE] [--test-image TEST_IMAGE] [--confidence CONFIDENCE]
               [--area-threshold AREA_THRESHOLD] [--frame-skip FRAME_SKIP] [--no-display]
               [--display] --save {image,video}

RTSP Human Capture - Supports multiple streams, configurable thresholds, and display options.

Project Structure

After installation, your directory should look like this:

rtsp-human-capture/
├── main.py                 # CLI entry point
├── config.py               # Config loader
├── config.cfg              # Default configuration
├── person_detector.py      # Detection engine
├── display_manager.py      # Display handling
├── stream_processor.py     # Stream processing
├── multi_stream_manager.py # Multi-stream orchestration
├── pyproject.toml          # Project dependencies
├── uv.lock                 # Dependency lock file
├── model/                  # Model files (after download)
│   ├── yolov4.weights
│   ├── yolov4.cfg
│   └── coco.names
├── deps/                   # Optional CUDA wheels
│   └── opencv_contrib_python-*.whl
└── output/                 # Generated captures (created on first run)

Troubleshooting

CUDA Not Detected

If you have a NVIDIA GPU but CUDA is not detected:

Verify NVIDIA drivers: nvidia-smi
Check CUDA installation: nvcc --version
Ensure OpenCV CUDA wheels are installed (not the CPU-only version)
The application will print “CUDA available, using GPU” or “CUDA not available, using CPU” at startup

Import Errors

If you see ModuleNotFoundError:

# Reinstall dependencies
uv sync --reinstall

# Or activate the virtual environment manually
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

Model Loading Errors

If model files fail to load:

Verify files exist in the model/ directory
Check file permissions: ls -la model/
Re-download corrupted files
The tool will automatically fall back to HOG detection

Next Steps

Quick Start Guide

Get your first detection working in 5 minutes with a test image and RTSP stream

Get Started

Guides

Examples

Prerequisites

Python 3.12+

uv Package Manager

Clone the Repository

Install Dependencies

Fallback for CPU-Only Systems

Optional: CUDA GPU Acceleration

1. Verify CUDA Installation

2. Install OpenCV CUDA Wheels

Download Model Files

Model Files Reference

Verify Installation

Project Structure

Troubleshooting

CUDA Not Detected

Import Errors

Model Loading Errors

Next Steps

Quick Start Guide

​Prerequisites

​Python 3.12+

​uv Package Manager

​Clone the Repository

​Install Dependencies

​Fallback for CPU-Only Systems

​Optional: CUDA GPU Acceleration

​1. Verify CUDA Installation

​2. Install OpenCV CUDA Wheels

​Download Model Files

​Model Files Reference

​Verify Installation

​Project Structure

​Troubleshooting

​CUDA Not Detected

​Import Errors

​Model Loading Errors

​Next Steps

Quick Start Guide

Prerequisites

Python 3.12+

uv Package Manager

Clone the Repository

Install Dependencies

Fallback for CPU-Only Systems

Optional: CUDA GPU Acceleration

1. Verify CUDA Installation

2. Install OpenCV CUDA Wheels

Download Model Files

Model Files Reference

Verify Installation

Project Structure

Troubleshooting

CUDA Not Detected

Import Errors

Model Loading Errors

Next Steps