Home

📖 Welcome to the OpenCV5Sharp Wiki!

Welcome to the documentation hub for OpenCV5Sharp — the high-performance, automatic C# wrapper suite for OpenCV 5.0.0 featuring CUDA/cuDNN GPU acceleration and robust memory cleanup models.

This Wiki serves as the technical reference manual for installing, compiling, deploying, and troubleshooting the library across Windows, Linux, macOS, Android, and iOS.

---

🧭 Documentation Portal

Use the links below to navigate the technical guides:

🚀 Getting Started

• Installation Guide — Install package variations via NuGet.
• Quick Start Example — Write your first edge detection pipeline in 5 minutes.
• Supported Types & Mapping — How C++ types (cv::Mat, cv::Size) map to C# structs.

⚡ GPU & Native Compilation

• CUDA & cuDNN Setup — Configure prerequisites for OpenCV5Sharp.Gpu.
• Natively Compiling the Bridge — Build opencv5sharp_native from source using CMake/Docker.
• Isolating Multi-Platform Builds — Managing dual Windows/Linux native compilation folders.

📱 Advanced Features & Deployment

• Memory Ownership & Disposal — Deep dive into the DisposableOpenCVObject pattern.
• Mobile Deployment (MAUI) — Packing Android/iOS assemblies and stripping native payloads.
• Thread Safety Guidelines — Safely manipulating matrices across threads.

🔧 Diagnostics & Maintenance

• Troubleshooting & Diagnostics — Handle DLL load errors and unmanaged exception boundaries.
• Assembly Signing & Integrity — Verify SHA256 DLL checksums and package signing.

---

📐 Architecture Overview

OpenCV5Sharp bridges managed .NET assemblies with unmanaged C++ OpenCV modules via a highly optimized P/Invoke boundary:

graph TD
    App[.NET App: Console, Blazor, MAUI] --> SDK[OpenCV5Sharp.dll]
    subgraph "Managed Assembly (SDK)"
        SDK --> Types[Managed Structs: Size, Point, Scalar]
        SDK --> Disposable[DisposableOpenCVObject Wrapper]
        SDK --> PInvoke[P/Invoke NativeMethods Layer]
    end
    PInvoke --> NativeBridge[opencv5sharp_native.dll / .so / .dylib]
    subgraph "Unmanaged Bridge"
        NativeBridge --> ExGuard[Exception Boundary Guard]
        NativeBridge --> OpenCV[OpenCV 5 Core/Imgproc/DNN/CUDA Modules]
    end

Loading

Key Pillars:

1. Exception Protection: The native C++ bridge catches all unmanaged cv::Exception and standard exceptions, mapping them back to a managed thread-local error state. This guarantees zero hard application crashes.
2. Thread-Safe Dispose: Double-dispose or race conditions between finalizers and explicit calls are handled atomically using Interlocked.Exchange-based handle tracking.

---

💻 Minimal Quick Start

Here is a copy-pasteable console example doing Canny Edge Detection:

using System;
using OpenCV5Sharp;

class Program
{
    static void Main()
    {
        // 1. Read input image (BGR color)
        using var src = Cv2.Imread("input.jpg", (int)ImreadModes.Color);
        if (src == null || src.Handle == IntPtr.Zero)
        {
            Console.WriteLine("Error: Could not load image.");
            return;
        }

        using var gray = new Mat();
        using var blurred = new Mat();
        using var edges = new Mat();

        // 2. Perform conversions and filters
        Cv2.CvtColor(src, gray, (int)ColorConversionCodes.Bgr2gray, 0, AlgorithmHint.Default);
        Cv2.GaussianBlur(gray, blurred, new Size(5, 5), 1.5, 1.5, (int)BorderTypes.Default, AlgorithmHint.Default);
        Cv2.Canny(blurred, edges, 50, 150, 3, false);

        // 3. Save output
        Cv2.Imwrite("output_edges.jpg", edges, IntPtr.Zero);
        Console.WriteLine("Edge detection completed successfully!");
    }
}

---

🤝 Community & Support

• Got a bug or a compile issue? Open a Bug Report.
• Have a question or general inquiry? Start a thread in our Discussions space.