Expand OpenCvSharp usage guides

Author: shimat

README.md

@@ -4,7 +4,9 @@
 
 [![GitHub Actions Windows Status](https://github.com/shimat/opencvsharp/actions/workflows/windows.yml/badge.svg)](https://github.com/shimat/opencvsharp/actions/workflows/windows.yml)  [![GitHub Actions Docker Test Status](https://github.com/shimat/opencvsharp/actions/workflows/docker-test-ubuntu.yml/badge.svg)](https://github.com/shimat/opencvsharp/actions/workflows/docker-test-ubuntu.yml)  [![GitHub Actions manylinux Status](https://github.com/shimat/opencvsharp/actions/workflows/manylinux.yml/badge.svg)](https://github.com/shimat/opencvsharp/actions/workflows/manylinux.yml)  [![GitHub Actions Wasm Status](https://github.com/shimat/opencvsharp/actions/workflows/wasm.yml/badge.svg)](https://github.com/shimat/opencvsharp/actions/workflows/wasm.yml) [![GitHub Actions macOS Status](https://github.com/shimat/opencvsharp/actions/workflows/macos.yml/badge.svg)](https://github.com/shimat/opencvsharp/actions/workflows/macos.yml) [![GitHub license](https://img.shields.io/github/license/shimat/opencvsharp.svg)](https://github.com/shimat/opencvsharp/blob/master/LICENSE) 
 
-OpenCvSharp is a cross-platform .NET wrapper for OpenCV, providing a rich set of image processing and computer vision functionality.
+OpenCvSharp is a cross-platform .NET wrapper for OpenCV, providing a rich set of image processing and computer vision functionality. Its API is intentionally designed to stay as close as practical to the native OpenCV C++ API so that OpenCV concepts, documentation, and code can be transferred to .NET with minimal friction, while still using C# conventions such as typed enums, exceptions, and deterministic disposal.
+
+See [OpenCV C++, OpenCV-Python, and OpenCvSharp](https://shimat.github.io/opencvsharp/articles/getting-started/opencv-api-comparison.html) for the main API and data-model differences.
 
 ## 🚀 [Try the Live Demo](https://shimat.github.io/opencvsharp_blazor_sample/)
 
@@ -58,7 +60,7 @@ dotnet add package OpenCvSharp5.runtime.osx.arm64
 For more installation options, see the [Installation](#installation) section below, or the full [NuGet package list](#nuget).
 
 ## Features
-* OpenCvSharp is modeled on the native OpenCV C/C++ API style as much as possible.
+* OpenCvSharp is modeled on the native OpenCV C++ API as closely as practical.
 * Many classes of OpenCvSharp implement IDisposable. Unsafe resources are managed automatically. 
 * OpenCvSharp does not force object-oriented programming style on you. You can also call native-style OpenCV functions.
 * OpenCvSharp provides functions for converting from `Mat` to `Bitmap` (GDI+) or `WriteableBitmap` (WPF).

docs/docfx/articles/getting-started/opencv-api-comparison.md

@@ -0,0 +1,161 @@
+# OpenCV C++, OpenCV-Python, and OpenCvSharp
+
+OpenCvSharp exposes OpenCV to .NET applications. Its API is intentionally designed to stay as close as practical to the native OpenCV C++ API so that OpenCV concepts, documentation, and code transfer naturally to .NET. Most computer vision concepts, algorithm behavior, and parameter constraints come directly from OpenCV, while the managed surface also follows C# conventions and cannot be translated mechanically from every C++ or Python example.
+
+Use the official OpenCV documentation for algorithm theory and native parameter requirements. Use the OpenCvSharp guides and API reference for .NET package selection, managed types, overloads, resource ownership, and application integration.
+
+## How the three APIs relate
+
+OpenCV is implemented primarily in C++. Its C++ API is therefore the closest description of the native functions that OpenCvSharp eventually calls.
+
+OpenCV-Python is an official generated binding over the same native implementation. Images are normally presented as NumPy arrays, and the binding adapts many C++ output parameters into Python return values.
+
+OpenCvSharp is a .NET wrapper with a managed API and a native bridge. It preserves many OpenCV names and concepts while representing them with .NET classes, enums, arrays, spans, exceptions, and `IDisposable`.
+
+| Concept | OpenCV C++ | OpenCV-Python | OpenCvSharp |
+|---|---|---|---|
+| Free function | `cv::GaussianBlur` | `cv.GaussianBlur` | `Cv2.GaussianBlur` |
+| Submodule function | `cv::dnn::readNetFromONNX` | `cv.dnn.readNetFromONNX` | `Cv2.Dnn.ReadNetFromONNX` |
+| Image container | `cv::Mat` | `numpy.ndarray` or `cv.Mat` | `Mat` |
+| Image size | `cv::Size` | `(width, height)` tuple | `Size` |
+| Coordinate | `cv::Point` | `(x, y)` tuple | `Point` |
+| Color conversion enum and value | `cv::ColorConversionCodes` and `cv::COLOR_BGR2GRAY` | `cv.COLOR_BGR2GRAY` | `ColorConversionCodes.BGR2GRAY` |
+| Output image | `OutputArray dst` argument | Usually a return value | Usually a caller-owned `Mat` argument |
+| Native failure | `cv::Exception` | `cv2.error` | `OpenCVException` |
+| Lifetime | RAII and reference counting | Python and NumPy ownership | `IDisposable` and `using` |
+
+The correspondence is deliberately recognizable, but it is not a promise that every native overload has an identical managed overload.
+
+## The same operation in three languages
+
+The following examples all load a color image, validate it, and convert it to grayscale.
+
+### C++
+
+```cpp
+cv::Mat source = cv::imread("input.jpg", cv::IMREAD_COLOR);
+if (source.empty())
+{
+    throw std::runtime_error("Could not read input.jpg.");
+}
+
+cv::Mat grayscale;
+cv::cvtColor(source, grayscale, cv::COLOR_BGR2GRAY);
+```
+
+### Python
+
+```python
+import cv2 as cv
+
+source = cv.imread("input.jpg", cv.IMREAD_COLOR)
+if source is None:
+    raise RuntimeError("Could not read input.jpg.")
+
+grayscale = cv.cvtColor(source, cv.COLOR_BGR2GRAY)
+```
+
+### OpenCvSharp
+
+```csharp
+using var source = Cv2.ImRead("input.jpg", ImreadModes.Color);
+if (source.Empty())
+{
+    throw new InvalidOperationException("Could not read input.jpg.");
+}
+
+using var grayscale = new Mat();
+Cv2.CvtColor(source, grayscale, ColorConversionCodes.BGR2GRAY);
+```
+
+The OpenCvSharp example resembles the C++ API because `grayscale` is an explicit destination. It also adds deterministic disposal because both managed objects own native resources.
+
+## Translating names from C++
+
+Most free functions in the `cv` namespace are static methods on `Cv2`, with .NET-style capitalization:
+
+| C++ | OpenCvSharp |
+|---|---|
+| `cv::imread` | `Cv2.ImRead` |
+| `cv::cvtColor` | `Cv2.CvtColor` |
+| `cv::findContours` | `Cv2.FindContours` |
+| `cv::warpPerspective` | `Cv2.WarpPerspective` |
+
+Functions in an OpenCV submodule normally use a nested `Cv2` class. For example, `cv::dnn` maps to `Cv2.Dnn`, while wrapper object types remain in namespaces such as `OpenCvSharp.Dnn`.
+
+OpenCvSharp enum types generally mirror named enums declared by the native C++ API. For example, OpenCV declares the unscoped enum `cv::ColorConversionCodes`; because its enumerators are injected into the enclosing `cv` namespace, C++ code normally writes `cv::COLOR_BGR2GRAY` without mentioning the enum type. OpenCvSharp exposes the same grouping through the scoped C# expression `ColorConversionCodes.BGR2GRAY`.
+
+Apply the same rule when translating names such as `cv::INTER_AREA` or `cv::THRESH_OTSU`: identify the native enum declaration or inspect the parameter type, then use the corresponding OpenCvSharp enum member.
+
+## Translating Python examples
+
+Python tutorials are valuable explanations of OpenCV algorithms, but NumPy operations need special attention.
+
+### NumPy arrays are not OpenCvSharp Mat objects
+
+A Python image commonly exposes shape, data type, channels, slicing, broadcasting, and arithmetic through NumPy. OpenCvSharp keeps the native `cv::Mat` model instead:
+
+| Python and NumPy | OpenCvSharp |
+|---|---|
+| `image.shape` | `image.Rows`, `image.Cols`, and `image.Channels()` |
+| `image.dtype` | `image.Depth()` or `image.Type()` |
+| `image[y, x]` | `image.At<T>(y, x)` or span-based access |
+| `image[y1:y2, x1:x2]` | A `Mat` region of interest |
+| NumPy vectorized expression | A corresponding `Cv2` operation, matrix expression, or span loop |
+
+Do not translate a NumPy loop or slice one token at a time. First identify whether the operation is a native OpenCV function. Native operations usually express intent more clearly and avoid repeated managed-to-native calls.
+
+See [Mat Basics](../guides/mat-basics.md) and [Pixel Access](../guides/pixel-access.md) for the OpenCvSharp data model.
+
+### Python often returns C++ output arguments
+
+The generated Python binding turns many C++ `OutputArray` arguments into return values. For example, Python thresholding returns both the selected threshold and the output image:
+
+```python
+selected_threshold, binary = cv.threshold(
+    grayscale, 0, 255, cv.THRESH_BINARY | cv.THRESH_OTSU)
+```
+
+OpenCvSharp keeps the destination as an argument and returns the scalar result:
+
+```csharp
+using var binary = new Mat();
+double selectedThreshold = Cv2.Threshold(
+    grayscale, binary, 0, 255, ThresholdTypes.Binary | ThresholdTypes.Otsu);
+```
+
+Functions with several Python return values may instead use `out` parameters, arrays, tuples, or result objects in OpenCvSharp. Check the managed signature rather than assuming the Python return shape.
+
+## Resource ownership is a .NET concern
+
+OpenCvSharp objects that own native resources must be disposed. This includes `Mat`, `VideoCapture`, `VideoWriter`, `Net`, feature detectors, and many other wrappers.
+
+Use `using` declarations for local ownership and document ownership when returning an OpenCvSharp object from a method. Garbage collection does not provide timely accounting for native image buffers.
+
+Read [Resource Management](../guides/resource-management.md) before translating a long-running Python application or a C++ pipeline that relies on scope-based RAII.
+
+## Find the corresponding OpenCvSharp API
+
+When starting from an OpenCV C++ or Python page:
+
+1. Identify the C++ function and its module in the official OpenCV reference.
+2. Map `cv::functionName` to `Cv2.FunctionName`, or `cv::module::functionName` to `Cv2.Module.FunctionName`.
+3. Replace global constants with the enum type accepted by the OpenCvSharp parameter.
+4. Search the [OpenCvSharp API reference](../../api/index.md) for the managed overload.
+5. Check whether returned images or algorithm objects need disposal.
+6. Confirm that the OpenCvSharp and OpenCV versions provide the same module and behavior.
+
+If a direct mapping is missing, search the [issue tracker](https://github.com/shimat/opencvsharp/issues) before assuming that the native feature is unavailable.
+
+## Version and package differences
+
+This documentation describes OpenCvSharp5 and OpenCV 5.x. OpenCvSharp4 wraps the OpenCV 4.x line and targets older .NET applications. Some module names, APIs, data types, and package requirements differ between the two major versions.
+
+See [Choose a Version and Package](package-selection.md) before combining code or documentation from different OpenCV generations.
+
+## Official OpenCV references
+
+- [OpenCV 5 documentation](https://docs.opencv.org/5.0/index.html)
+- [OpenCV 5 tutorials](https://docs.opencv.org/5.0/tutorials/tutorials.html)
+- [OpenCV-Python tutorials](https://docs.opencv.org/5.0/py_tutorials/py_tutorials.html)
+- [How OpenCV-Python bindings work](https://docs.opencv.org/5.0/py_tutorials/py_bindings/py_bindings_basics/py_bindings_basics.html)

docs/docfx/articles/guides/contours-shape-analysis.md

@@ -0,0 +1,140 @@
+# Contours and Shape Analysis
+
+Contours describe object boundaries in a binary image. They are useful for measuring area, locating bounding boxes, approximating shapes, and drawing annotations.
+
+## Prepare a binary input
+
+`Cv2.FindContours` expects an 8-bit single-channel image where zero is background and non-zero pixels are foreground:
+
+```csharp
+using var source = Cv2.ImRead("objects.png", ImreadModes.Color);
+if (source.Empty())
+{
+    throw new InvalidOperationException("Could not read objects.png.");
+}
+
+using var grayscale = new Mat();
+using var binary = new Mat();
+
+Cv2.CvtColor(source, grayscale, ColorConversionCodes.BGR2GRAY);
+Cv2.Threshold(
+    grayscale,
+    binary,
+    0,
+    255,
+    ThresholdTypes.Binary | ThresholdTypes.Otsu);
+```
+
+If the objects are darker than the background, use `ThresholdTypes.BinaryInv | ThresholdTypes.Otsu`.
+
+## Find external contours
+
+Use `RetrievalModes.External` when only the outer boundary of each foreground object matters:
+
+```csharp
+using Mat contourInput = binary.Clone();
+Cv2.FindContours(
+    contourInput,
+    out Point[][] contours,
+    out HierarchyIndex[] hierarchy,
+    RetrievalModes.External,
+    ContourApproximationModes.ApproxSimple);
+```
+
+Each element in `contours` is a managed array of image coordinates. `ApproxSimple` compresses straight segments to their endpoints and is appropriate for most measurement and drawing tasks.
+
+The cloned input makes the ownership and reuse of `binary` unambiguous across OpenCV versions and overloads.
+
+## Filter and draw contours
+
+Measure contour area before drawing or performing more expensive analysis:
+
+```csharp
+Point[][] significantContours = contours
+    .Where(contour => Cv2.ContourArea(contour) >= 500)
+    .ToArray();
+
+using Mat annotated = source.Clone();
+Cv2.DrawContours(
+    annotated,
+    significantContours,
+    contourIdx: -1,
+    color: new Scalar(0, 255, 0),
+    thickness: 2);
+
+foreach (Point[] contour in significantContours)
+{
+    Rect bounds = Cv2.BoundingRect(contour);
+    Cv2.Rectangle(
+        annotated,
+        bounds,
+        new Scalar(0, 0, 255),
+        thickness: 2);
+}
+```
+
+`contourIdx: -1` draws every contour in the supplied collection. OpenCV colors are BGR by default, so `(0, 255, 0)` is green and `(0, 0, 255)` is red.
+
+## Understand contour hierarchy
+
+`HierarchyIndex` records four indices for each contour:
+
+- The next contour at the same level.
+- The previous contour at the same level.
+- The first child contour.
+- The parent contour.
+
+Missing relationships use `-1`. `RetrievalModes.External` produces no nested children. Use `RetrievalModes.CComp` for two-level component boundaries or `RetrievalModes.Tree` for the full nesting structure.
+
+## Use connected components for filled regions
+
+Connected-component labeling is often simpler when the goal is to enumerate filled blobs rather than analyze their boundaries:
+
+```csharp
+ConnectedComponents components = Cv2.ConnectedComponentsEx(binary);
+using Mat annotated = source.Clone();
+
+foreach (ConnectedComponents.Blob blob in components.Blobs.Skip(1))
+{
+    if (blob.Area < 500)
+    {
+        continue;
+    }
+
+    Cv2.Rectangle(
+        annotated,
+        blob.Rect,
+        new Scalar(255, 0, 0),
+        thickness: 2);
+}
+```
+
+Label zero is the background, so typical applications skip the first blob. Each remaining blob includes its area, centroid, and bounding rectangle.
+
+Choose contours when perimeter geometry and nested boundaries matter. Choose connected components when labels, areas, centroids, and axis-aligned bounds are sufficient.
+
+## Common mistakes
+
+- Passing a three-channel color image to `FindContours`.
+- Treating grayscale intensity as a mask without thresholding it first.
+- Forgetting that `Point.X` is the column and `Point.Y` is the row.
+- Using `RetrievalModes.External` when holes or nested objects are significant.
+- Comparing contour area with bounding-box area as if they were equivalent.
+- Keeping every noise contour instead of filtering by scale or applying morphology first.
+
+## From C++ or Python
+
+The native `std::vector<std::vector<cv::Point>>` and the Python contour sequence map naturally to `Point[][]` in the common OpenCvSharp overload. Python returns contours and hierarchy together, while OpenCvSharp uses `out` parameters.
+
+## Official OpenCV references
+
+- [Structural analysis and shape descriptors](https://docs.opencv.org/5.0/main_modules/imgproc_shape.html)
+- [OpenCV image processing tutorials](https://docs.opencv.org/5.0/tutorials/imgproc/imgproc.html)
+
+## Related OpenCvSharp API
+
+- [Cv2](xref:OpenCvSharp.Cv2)
+- [HierarchyIndex](xref:OpenCvSharp.HierarchyIndex)
+- [RetrievalModes](xref:OpenCvSharp.RetrievalModes)
+- [ContourApproximationModes](xref:OpenCvSharp.ContourApproximationModes)
+- [ConnectedComponents](xref:OpenCvSharp.ConnectedComponents)