DOCSEARCHbyAlgolia
Submit Docs

OpenCvSharp Documentation

repository·main·Indexed 27 days ago

https://github.com/shimat/opencvsharp

A cross-platform .NET wrapper for OpenCV providing image processing and computer vision functionality. It offers two parallel package families: OpenCvSharp5 for .NET 8+ (OpenCV 5.0.x) and OpenCvSharp4 for .NET Framework 4.6.1+, .NET Standard 2.0/2.1, or .NET 8+ (OpenCV 4.13.0). Supports Windows, Linux, macOS, and WebAssembly with specialized profiles including headless and slim versions for different deployment environments.

Tokens
37.9K
Snippets
91
Records
178
Agent score
91%

What's inside OpenCvSharp

  1. Identify supported platforms for OpenCvSharp5

    main

    OpenCvSharp5 targets .NET 8 or later and provides runtime packages for the following platforms:

    • Windows: x64 and ARM64
    • Linux: x64 and ARM64
    • macOS: x64 and Apple Silicon
    • WebAssembly

    Note: If your application requires .NET Framework or .NET Standard, you must use OpenCvSharp4.

  2. Understand the relationship between OpenCV C++, Python, and OpenCvSharp

    main

    OpenCvSharp is a .NET wrapper designed to stay close to the native OpenCV C++ API. While Python (cv2) often uses NumPy arrays and returns output images as function return values, OpenCvSharp uses managed types like Mat and typically requires the caller to provide a destination object as an argument (mirroring C++ behavior).

    ConceptOpenCV C++Python (cv2)OpenCvSharp
    Free functioncv::GaussianBlurcv2.GaussianBlurCv2.GaussianBlur
    Submodule functioncv::dnn::readNetFromONNXcv2.dnn.readNetFromONNXCv2.Dnn.ReadNetFromONNX
    Image containercv::Matnumpy.ndarrayMat
    Image sizecv::Size(width, height) tupleSize
    Coordinatecv::Point(x, y) tuplePoint
    Color conversion enumcv::COLOR_BGR2GRAYcv2.COLOR_BGR2GRAYColorConversionCodes.BGR2GRAY
    Output imageCaller-owned cv::Mat argumentFunction return valueCaller-owned Mat argument
    Native failurecv::Exceptioncv2.errorOpenCVException
    LifetimeRAII / Reference countingPython / NumPy ownershipIDisposable / using

  3. Getting started with OpenCvSharp

    main

    New users should follow this learning path to effectively use OpenCvSharp:

    1. Package Selection: Choose the correct version and package for your environment.
    2. Installation: Install the necessary OpenCvSharp packages.
    3. First Application: Build a basic application to verify the setup.
    4. Mat Fundamentals: Learn the core Mat data model.
    5. Resource Management: Understand how to manage native resources to prevent memory leaks.
    6. Advanced Memory & Arrays: Learn about array proxies, in-place processing, and how to control copies and native memory for performance.

  5. Limit histogram calculation to a specific region using a mask

    main

    To calculate a histogram for a specific area of interest (ROI) rather than the entire image, provide a mask to Cv2.CalcHist. The mask must be an 8-bit single-channel (CV_8UC1) matrix with the same dimensions as the source image. Non-zero pixels in the mask determine which source pixels are included in the calculation.

    using var mask = new Mat(source.Size(), MatType.CV_8UC1, Scalar.Black);
Cv2.Rectangle(
    mask,
    new Rect(50, 40, 200, 150),
    Scalar.White,
    thickness: -1);

using var regionHistogram = new Mat();
Cv2.CalcHist(
    images: [source],
    channels: [0],
    mask: mask,
    hist: regionHistogram,
    dims: 1,
    histSize: [256],
    ranges: [new Rangef(0, 256)]);

  6. Process an IFormFile in an ASP.NET Core controller

    main

    When handling image uploads in ASP.NET Core, you must convert the IFormFile into a contiguous buffer (like a MemoryStream) before calling Cv2.ImDecode, as OpenCV cannot decode an incremental .NET Stream.

    Best Practices:

    • Use MemoryStream.GetBuffer().AsSpan(...) to avoid the extra array copy performed by ToArray().
    • Validate file length before processing to prevent oversized uploads.
    • Use [RequestSizeLimit] on the controller action to set the maximum allowed request size.
    • Do not rely on IFormFile.FileName or ContentType for decoding; decode the actual bytes and choose your own output format.
    [HttpPost("grayscale")]
[RequestSizeLimit(MaxRequestBytes)]
public async Task<IActionResult> Grayscale(IFormFile file, CancellationToken cancellationToken)
{
    if (file.Length is <= 0 or > MaxFileBytes) return BadRequest("...");

    using var encoded = new MemoryStream(capacity: checked((int)file.Length));
    await file.CopyToAsync(encoded, cancellationToken);

    Mat source;
    try
    {
        source = Cv2.ImDecode(
            encoded.GetBuffer().AsSpan(start: 0, length: checked((int)encoded.Length)),
            ImreadModes.Color);
    }
    catch (OpenCVException)
    {
        return BadRequest("The upload could not be decoded.");
    }

    using (source)
    {
        if (source.Empty()) return BadRequest("...");
        // ... process Mat ...
        if (!Cv2.ImEncode(".png", grayscale, out byte[] png))
        {
            return StatusCode(500, "Could not encode the result.");
        }
        return File(png, "image/png");
    }
}

  7. Install OpenCvSharp on Linux x64

    main

    Choose between a full desktop runtime or a headless runtime for services/containers.

    • Desktop (with GUI support): Requires GTK3. On Ubuntu/Debian, run sudo apt-get install libgtk-3-0.
    • Headless (no GUI): Use this if you do not need Cv2.ImShow, Cv2.WaitKey, or other highgui APIs. This is ideal for containers.

    Note: Official Linux x64 packages require glibc 2.28 or later.

    # Desktop application (requires GTK3)
dotnet add package OpenCvSharp5
dotnet add package OpenCvSharp5.official.runtime.linux-x64

# Service/Container (no highgui APIs)
dotnet add package OpenCvSharp5
dotnet add package OpenCvSharp5.official.runtime.linux-x64.headless

  8. Build OpenCvSharp on Ubuntu (vcpkg method)

    main

    The recommended way to build on Ubuntu is using vcpkg to manage dependencies like Tesseract and image libraries. This ensures consistency with the Windows build process.

    1. Clone the repository with submodules.
    2. Install dependencies via vcpkg using the x64-linux-static triplet.
    3. Build OpenCV and the native wrapper using CMake.
    # 1. Clone
git clone --recursive https://github.com/shimat/opencvsharp.git
cd opencvsharp

# 2. Install dependencies
/path/to/vcpkg/vcpkg install --triplet x64-linux-static --overlay-triplets cmake/triplets

# 3. Build OpenCV and OpenCvSharpExtern
cmake -C cmake/opencv_build_options.cmake \
      -S opencv -B opencv/build \
      -D OPENCV_EXTRA_MODULES_PATH=$PWD/opencv_contrib/modules \
      -D CMAKE_INSTALL_PREFIX=$PWD/opencv_artifacts \
      -D CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake \
      -D VCPKG_TARGET_TRIPLET=x64-linux-static
cmake --build opencv/build -j$(nproc)
cmake --install opencv/build

cmake -S src -B src/build \
      -D CMAKE_BUILD_TYPE=Release \
      -D CMAKE_PREFIX_PATH=$PWD/opencv_artifacts \
      -D CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake \
      -D VCPKG_TARGET_TRIPLET=x64-linux-static
cmake --build src/build -j$(nproc)

# 4. Build managed library
dotnet build src/OpenCvSharp/OpenCvSharp.csproj -c Release

  9. Migrate GDI+ extensions from OpenCvSharp4 to OpenCvSharp5

    main

    In OpenCvSharp5, the OpenCvSharp.Extensions package has been split. If you use BitmapConverter (for System.Drawing.Bitmap ⇄ Mat interop), you must switch to the new package and namespace.

    Migration Steps:

    1. Replace package OpenCvSharp4.Extensions with OpenCvSharp5.GdipExtensions.
    2. Change using OpenCvSharp.Extensions; to using OpenCvSharp.GdipExtensions;.

  11. Convert between Mat and System.Drawing.Bitmap (GDI+)

    main

    To convert between Mat and System.Drawing.Bitmap on Windows, install the OpenCvSharp5.GdipExtensions or OpenCvSharp5.Windows package and import OpenCvSharp.GdipExtensions.

    Conversions copy pixel data into independently owned objects, so you must dispose of both the Bitmap and the Mat. This conversion does not make System.Drawing.Common cross-platform.

    using System.Drawing;
using OpenCvSharp;
using OpenCvSharp.GdipExtensions;

using var image = Cv2.ImRead("input.jpg", ImreadModes.Color);
if (image.Empty())
{
    throw new IOException("Could not read input.jpg.");
}

using Bitmap bitmap = image.ToBitmap();
using Mat roundTrip = bitmap.ToMat();

  12. Install OpenCvSharp5 on Linux / Ubuntu

    main

    The official Linux runtime is built on manylinux_2_28 and works on Ubuntu 20.04+, Debian 10+, RHEL/AlmaLinux 8+, and other distributions with glibc 2.28+.

    Standard Installation (includes GTK3 for GUI support):

    dotnet add package OpenCvSharp5
dotnet add package OpenCvSharp5.official.runtime.linux-x64

    Headless Profile (Full module set, no GTK3/X11 dependency): Use this for containerized services that need modules like videoio or dnn but do not need GUI functions (e.g., Cv2.ImShow).

    dotnet add package OpenCvSharp5.official.runtime.linux-x64.headless

    Slim Profile (Reduced module set, no GUI dependency): Use this for the smallest possible footprint. It disables contrib, dnn, videoio, and highgui.

    dotnet add package OpenCvSharp5.official.runtime.linux-x64.slim
    dotnet add package OpenCvSharp5
dotnet add package OpenCvSharp5.official.runtime.linux-x64