Skip to main content

​
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
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:
  1. Visit opencv-python-cuda-wheels releases
  2. 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)
  3. 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/
  1. 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" }
  1. 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:
1

Create model directory

mkdir -p model
2

Download YOLOv4 weights

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

Download YOLOv4 config

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

Download COCO class names

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

​
Model Files Reference

FileSizeDescription
yolov4.weights~245 MBPre-trained YOLOv4 model weights
yolov4.cfg~12 KBYOLOv4 network architecture configuration
coco.names~1 KBCOCO 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:
  1. Verify NVIDIA drivers: nvidia-smi
  2. Check CUDA installation: nvcc --version
  3. Ensure OpenCV CUDA wheels are installed (not the CPU-only version)
  4. 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:
  1. Verify files exist in the model/ directory
  2. Check file permissions: ls -la model/
  3. Re-download corrupted files
  4. 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