📷 RustCV

English | 简体中文

RustCV: A Modern, OpenCV-Compatible Vision Framework for the Rust Era

🔗 Join the Discord

RustCV is the spiritual successor to OpenCV in the Rust ecosystem. It provides a unified Facade layer, allowing you to enjoy Rust's memory safety and zero-copy performance using the familiar classical API style.

📖 Introduction

RustCV is a high-performance, native Rust computer vision library aimed at solving ecosystem fragmentation. It is not a simple FFI binding, but a ground-up pure Rust implementation.

• OpenCV Parity: Provides familiar APIs such as VideoCapture, Mat, and imshow, significantly reducing migration costs for developers coming from C++.
• Hidden Complexity: The backend is powered by a Tokio-based asynchronous driver, while exposing a clean, synchronous blocking interface. You get the performance of async I/O without the boilerplate of async/await.
• Out-of-the-box: Intelligently identifies the target_os statically and links the absolute best native camera drivers dynamically. Zero-configuration cross-platform support.

✨ Key Features

• 🦀 Rust Native: Written entirely in Rust. Say goodbye to C++ shared library "dependency hell" and complex CMake configurations.
• ⚡ Extreme Performance:
  • Integrated Lazy Global Runtime for automatic management of asynchronous hardware interactions.
  • Supports Stride memory layout, allowing direct mapping of hardware buffers. Built-in zero-bounds-checking copies and SIMD-ready iterators guarantee max FPS even in debug builds.
• 🎨 Full Native Driver Architecture:
  • Linux: Native V4L2 driver integration.
  • macOS: Native AVFoundation driver integration (Features efficient 32BGRA rendering and strictly bounded GCD queues).
  • Windows: Native MediaFoundation (MSMF) driver integration.
• 🛠️ Dynamic Hot-Reloading & Strong Types: No more "magic numbers." Use ergonomic APIs like cap.set_resolution(1280, 720) to hot-swap hardware resolution on the fly without dropping camera handles.

🖥️ Platform Support

The project has successfully completed the core backend driver adaptation for all three major desktop operating systems:

📦 Installation

Add RustCV to your Cargo.toml:

[dependencies]
rustcv = "0.1"

# Optional: Enable high-speed hardware-level JPEG decoding
# rustcv = { version= "0.1", features = ["turbojpeg"] }

Note: The library automatically pulls in the correct underlying dependencies (rustcv-backend-v4l2, rustcv-backend-avf, etc.) based on the current target_os during compilation. No manual feature configuration is requisite!

🚀 Quick Start

This is the most exciting part. See how clean the code is. Below is a complete, practical example featuring dynamic resolution hot-reloading and FPS monitoring:

use anyhow::Result;
use rustcv::{
    highgui,    // Windowing and Event Loop
    imgproc,    // Image Processing and Drawing Primitives
    prelude::*, // Auto-import VideoCapture, Mat, etc.
};
use std::time::Instant;

fn main() -> Result<()> {
    // 1. Open the default camera (index 0)
    // The hidden Async Runtime starts automatically in the background
    println!("Opening camera...");
    let mut cap = VideoCapture::new(0)?;

    // 2. Configure initial hardware resolution (Synchronous blocking call)
    cap.set_resolution(640, 480)?;
    
    // Pre-allocate the memory matrix for image frames
    let mut frame = Mat::empty();
    let mut high_res_mode = false;

    // FPS Tracker
    let mut last_time = Instant::now();
    let mut frame_count = 0;
    let mut fps = 0.0;

    println!("Start capturing... Press SPACE to toggle resolution. Press ESC to exit.");

    // 3. Classic OpenCV-style main read loop
    while cap.read(&mut frame)? {
        if frame.is_empty() { continue; }

        // --- Image Processing (Zero-Copy / In-place modification) ---
        // Draw a static tracking rectangle
        imgproc::rectangle(
            &mut frame,
            imgproc::Rect::new(200, 150, 240, 240),
            imgproc::Scalar::new(0, 255, 0), // Green (BGR)
            2,
        );

        // Update calculated FPS every 10 frames
        frame_count += 1;
        if frame_count % 10 == 0 {
            fps = 10.0 / last_time.elapsed().as_secs_f64();
            last_time = Instant::now();
            frame_count = 0;
        }

        // Render HUD Text (Red)
        let hud_text = format!("FPS: {:.1}  Res: {}x{}", fps, frame.cols, frame.rows);
        imgproc::put_text(
            &mut frame,
            &hud_text,
            imgproc::Point::new(10, 30),
            1.0, 
            imgproc::Scalar::new(0, 0, 255), 
        );

        // --- Cross-Platform Window Display ---
        highgui::imshow("RustCV Camera Pipeline", &frame)?;

        // --- Keyboard Events & Dynamic Control ---
        let key = highgui::wait_key(1)?;
        if key == 27 { // ESC to exit
            break;
        }

        // Spacebar: Dynamically change hardware capture resolution (Hot reloading)
        if key == 32 {
            high_res_mode = !high_res_mode;
            let (w, h) = if high_res_mode { (1280, 720) } else { (640, 480) };
            println!("🔄 Hot Reloading hardware resolution to {}x{}...", w, h);
            
            if let Err(e) = cap.set_resolution(w, h) {
                eprintln!("❌ Failed to reload: {}", e);
            }
        }
    }

    // 4. Cleanup resources (The underlying pipeline Drops automatically, explicit call is cleaner)
    highgui::destroy_all_windows()?;
    Ok(())
}

Run the example:

cargo run --example camera_demo -p rustcv

🏗️ Architecture

RustCV is designed around the Facade Pattern. The backend is highly modular while the frontend remains completely unified. It enforces the inclusion of the correct implementation backend at compile time using OS macros, ensuring absolute reliability across multiple platforms.

graph TD
    User[User Application] --> RustCV[Crate: rustcv]

    subgraph "RustCV Facade"
        API[Unified API]
        RT[Implicit Tokio Runtime]
        Mat[Mat Owned/Strided]
    end

    RustCV --> API
    API <--> RT

    subgraph "Core Layer"
        Core[rustcv-core]
        Traits[Traits: Driver, Stream]
    end

    RT --> Core

    subgraph "Hardware Backends (Compile-Time OS Gates)"
        V4L2[rustcv-backend-v4l2]
        AVF[rustcv-backend-avf]
        MSMF[rustcv-backend-msmf]
    end

    Core --> V4L2
    Core --> AVF
    Core --> MSMF

    style User fill:#f9f,stroke:#333,stroke-width:2px
    style RustCV fill:#bbf,stroke:#333,stroke-width:2px

🤝 Contributing

We welcome all forms of contribution! Whether it's reporting an Issue, completing code tests, or porting entirely new vision algorithms, you are very welcome!

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

📄 License

Distributed under the MIT License. See LICENSE for more information.