Merge pull request #2030 from shimat/feature/2009-imgcodecs-coverage

imgcodecs: add Animation, ImageCollection, metadata I/O, imcount (#2009)

Author: shimat

.github/copilot-instructions.md

@@ -166,6 +166,20 @@ Place each submodule facade in its module folder as `Cv2.<Sub>.cs` (e.g. `Module
 
 See `src/OpenCvSharpExtern/ximgproc_EdgeDrawing.h`, `src/OpenCvSharp/Modules/ximgproc/EdgeDrawing.cs` for a complete example covering: factory, OutputArray methods, std::vector methods, nested Params struct with bool fields, and VectorOfVec6d.
 
+## Enum member naming
+
+C++ enum members are `ALL_CAPS_WITH_UNDERSCORES` (e.g. `IMWRITE_JPEG_QUALITY`, `NORM_L2SQR`). When wrapping them as a C# enum, **default to PascalCase**, stripping the module/family prefix (`IMWRITE_JPEG_QUALITY` → `JpegQuality`). Keep the original casing (or a near-verbatim form) only when one of these narrow exceptions applies:
+
+1. **The value itself is an unbreakable acronym/abbreviation, standing alone (nothing else glued onto it).** Test: read it aloud — do you spell out the letters (like an acronym) rather than pronounce it as a word? If so, PascalCasing it (`Exif`, `L2Sqr`) destroys the acronym for no benefit. Keep it verbatim (`EXIF`, `L2SQR`). Precedent: `NormTypes.INF`/`L1`/`L2SQR`, `ImageMetadataType.EXIF`/`XMP`/`ICCP`/`CICP`.
+2. **The value has no natural word boundaries — it's an opaque code, not a phrase.** Test: does inserting word breaks add any information, or does it just capitalize letters arbitrarily? If the latter, keep it verbatim. Precedent: `ColorConversionCodes.BGR2GRAY` (whole body kept verbatim, only the `COLOR_` prefix stripped), `FASTType.TYPE_5_8`.
+3. **The prefix identifies a specific vendor/backend and is semantically load-bearing.** Test: does stripping the prefix delete information a reader needs (which camera SDK/backend this property belongs to)? If so, keep the prefix verbatim; the suffix can still be PascalCased normally. Precedent: `VideoCaptureProperties`' `XI_`/`OPENNI_`/`PVAPI_`/`GIGA_`/`IOS_`-prefixed members.
+
+When none of the three applies, PascalCase — don't keep a verbatim name "to be safe." The exceptions are narrow and should be justifiable by one of the tests above, not a default.
+
+**Compounds win over exception 1.** The "standalone" qualifier in exception 1 matters: once an acronym is glued to another word/acronym to form one compound member name, PascalCase the whole compound rather than leaving the acronym in caps — an ALL-CAPS-then-lowercase transition mid-identifier (`TIFFResUnit`, `CCITTRle`) is harder to read than a clean compound (`TiffResUnit`, `CcittRle`). This is why the pre-existing `ImwriteFlags.TiffResUnit`/`JpegQuality`/`PngCompression`/`PamTupleType` PascalCase acronyms that would otherwise qualify for exception 1 in isolation — they're prefixes in a compound, not standalone values. Same reasoning covers `ImwriteTiffCompressionFlags.CcittRle`/`CcittFax3` and the standalone-but-left-PascalCase `Lzw`/`Jbig`/`Dcs`/`Rle` siblings in that same enum (and its `ImwriteEXRCompressionFlags`/`ImwriteHDRCompressionFlags` cousins) — treating every acronym-derived compression-scheme name as ordinary vocabulary, consistently within the enum, beats selectively all-capping only some of them.
+
+**Enum type names are a separate question — mirror the C++ type identifier verbatim, don't run it through this heuristic.** OpenCV's own C++ type names are inconsistently cased across acronyms (`ImwriteJPEGSamplingFactorParams`, `ImwriteEXRTypeFlags`, `ImwritePNGFlags`, `ImwritePAMFlags`, `ImwriteWEBPLosslessMode`, `ImwriteHDRCompressionFlags`, `ImwriteBMPCompressionFlags`, `ImwriteGIFCompressionFlags` are capitalized, but `ImwriteTiffCompressionFlags`/`ImwriteTiffPredictorFlags`/`ImwriteTiffResolutionUnitFlags` use `Tiff`) — that inconsistency is inherited straight from `opencv2/imgcodecs.hpp`, not introduced on the C# side. Keep mirroring the C++ type name 1:1 regardless: it keeps the C# type grep-able against OpenCV's own headers/docs, which matters more than internal cosmetic consistency for a type name. This has always been this codebase's practice (`ImwriteEXRTypeFlags`/`ImwritePNGFlags`/`ImwritePAMFlags` pre-date this rule and already mirror C++ verbatim).
+
 ## Repository structure
 
 OpenCvSharp has three layers:

src/OpenCvSharp/Cv2/Cv2_imgcodecs.cs

@@ -20,6 +20,52 @@ public static partial ExceptionStatus imgcodecs_imread(
     public static partial ExceptionStatus imgcodecs_imreadmulti(
         [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, IntPtr mats, int flags, out int returnValue);
 
+    // acpOk is 0 (and returnValue 0) on Windows when 'fileName' can't be represented in the process
+    // ANSI code page; the managed caller retries via an ASCII-safe temp copy.
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imreadmulti_range(
+        [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, IntPtr mats, int start, int count, int flags, out int acpOk, out int returnValue);
+
+    // imcount (UTF-8 everywhere). On Windows, acpOk is 0 (and returnValue 0) when the path can't be
+    // represented in the process ANSI code page; the managed caller retries via an ASCII-safe temp copy.
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imcount(
+        [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, int flags, out int acpOk, out IntPtr returnValue);
+
+    // imreadWithMetadata / imwriteWithMetadata / imdecodeWithMetadata / imencodeWithMetadata
+
+    // acpOk/managed-retry contract: see imgcodecs_imreadmulti_range.
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imreadWithMetadata(
+        [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, IntPtr metadataTypes, IntPtr metadata, int flags, out int acpOk, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imwriteWithMetadata(
+        [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, IntPtr img,
+        [In] int[] metadataTypes, int metadataTypesLength, IntPtr metadata,
+        [In] int[] @params, int paramsLength, out int acpOk, out int returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial ExceptionStatus imgcodecs_imdecodeWithMetadata(
+        in InputArrayProxy buf, IntPtr metadataTypes, IntPtr metadata, int flags, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial ExceptionStatus imgcodecs_imencodeWithMetadata(
+        [MarshalAs(UnmanagedType.LPStr)] string ext, in InputArrayProxy img,
+        [In] int[] metadataTypes, int metadataTypesLength, IntPtr metadata, IntPtr buf,
+        [In] int[] @params, int paramsLength, out int returnValue);
+
+    // imdecodemulti / imencodemulti
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial ExceptionStatus imgcodecs_imdecodemulti(
+        in InputArrayProxy buf, int flags, IntPtr mats, Range range, out int returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imencodemulti(
+        [MarshalAs(UnmanagedType.LPStr)] string ext, IntPtr imgs, IntPtr buf, [In] int[] @params, int paramsLength, out int returnValue);
+
     // imwrite (UTF-8 everywhere; the native side converts to a wide path on Windows so non-ANSI names work)
 
     [LibraryImport(DllExtern, EntryPoint = "imgcodecs_imwrite"), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
@@ -61,6 +107,88 @@ internal static partial ExceptionStatus imgcodecs_imdecode_InputArray(
     internal static partial ExceptionStatus imgcodecs_imencode_vector(
         [MarshalAs(UnmanagedType.LPStr)] string ext, in InputArrayProxy img, IntPtr buf, [In] int[] @params, int paramsLength, out int returnValue);
 
+    // Animation
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_new(int loopCount, Scalar bgColor, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_delete(IntPtr obj);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_get_loop_count(IntPtr obj, out int returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_set_loop_count(IntPtr obj, int value);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_get_bgcolor(IntPtr obj, out Scalar returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_set_bgcolor(IntPtr obj, Scalar value);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_get_durations(IntPtr obj, IntPtr outVec);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_set_durations(IntPtr obj, [In] int[] data, int length);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_get_frames(IntPtr obj, IntPtr outVec);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_set_frames(IntPtr obj, IntPtr frames);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_get_still_image(IntPtr obj, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_Animation_set_still_image(IntPtr obj, IntPtr image);
+
+    // imreadanimation / imdecodeanimation / imwriteanimation / imencodeanimation
+
+    // acpOk/managed-retry contract: see imgcodecs_imreadmulti_range.
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imreadanimation(
+        [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, IntPtr animation, int start, int count, out int acpOk, out int returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial ExceptionStatus imgcodecs_imdecodeanimation(
+        in InputArrayProxy buf, IntPtr animation, int start, int count, out int returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imwriteanimation(
+        [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, IntPtr animation, [In] int[] @params, int paramsLength, out int acpOk, out int returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_imencodeanimation(
+        [MarshalAs(UnmanagedType.LPStr)] string ext, IntPtr animation, IntPtr buf, [In] int[] @params, int paramsLength, out int returnValue);
+
+    // ImageCollection
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_ImageCollection_new1(out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_ImageCollection_new2(
+        [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, int flags, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_ImageCollection_delete(IntPtr obj);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_ImageCollection_init(
+        IntPtr obj, [MarshalAs(UnmanagedType.LPUTF8Str)] string fileName, int flags);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_ImageCollection_size(IntPtr obj, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_ImageCollection_at(IntPtr obj, int index, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus imgcodecs_ImageCollection_releaseCache(IntPtr obj, int index);
+
     // haveImageReader (UTF-8 everywhere; native probes via a wide path on Windows)
 
     [LibraryImport(DllExtern, EntryPoint = "imgcodecs_haveImageReader"), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]

src/OpenCvSharp/Internal/PInvoke/NativeMethods/NativeMethods_imgcodecs.cs

@@ -0,0 +1,150 @@
+using OpenCvSharp.Internal;
+using OpenCvSharp.Internal.Util;
+using OpenCvSharp.Internal.Vectors;
+
+namespace OpenCvSharp;
+
+/// <summary>
+/// Represents an animation with multiple frames.
+/// Stores and manages data for animated sequences such as those from animated formats (e.g., GIF, AVIF, APNG, WebP).
+/// It provides support for looping, background color settings, frame timing, and frame storage.
+/// </summary>
+public class Animation : CvObject
+{
+    /// <summary>
+    /// Constructs an Animation object with optional loop count and background color.
+    /// </summary>
+    /// <param name="loopCount">
+    /// The number of times the animation should loop. 0 (default) indicates infinite looping.
+    /// Negative values or values beyond 0xffff (65535) are reset to 0.
+    /// </param>
+    /// <param name="bgColor">Background color of the animation in BGR(A) format. Defaults to an empty color.</param>
+    public Animation(int loopCount = 0, Scalar? bgColor = null)
+    {
+        NativeMethods.HandleException(
+            NativeMethods.imgcodecs_Animation_new(loopCount, bgColor ?? Scalar.All(0), out var p));
+        SetSafeHandle(new OpenCvPtrSafeHandle(p, ownsHandle: true,
+            static h => NativeMethods.HandleException(NativeMethods.imgcodecs_Animation_delete(h))));
+    }
+
+    /// <summary>
+    /// Number of times the animation should loop. 0 means infinite looping.
+    /// </summary>
+    public int LoopCount
+    {
+        get
+        {
+            ThrowIfDisposed();
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_get_loop_count(CvPtr, out var ret));
+            GC.KeepAlive(this);
+            return ret;
+        }
+        set
+        {
+            ThrowIfDisposed();
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_set_loop_count(CvPtr, value));
+            GC.KeepAlive(this);
+        }
+    }
+
+    /// <summary>
+    /// Background color of the animation in BGRA format.
+    /// </summary>
+    public Scalar BgColor
+    {
+        get
+        {
+            ThrowIfDisposed();
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_get_bgcolor(CvPtr, out var ret));
+            GC.KeepAlive(this);
+            return ret;
+        }
+        set
+        {
+            ThrowIfDisposed();
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_set_bgcolor(CvPtr, value));
+            GC.KeepAlive(this);
+        }
+    }
+
+    /// <summary>
+    /// Duration for each frame in milliseconds.
+    /// </summary>
+    public int[] Durations
+    {
+        get
+        {
+            ThrowIfDisposed();
+            using var vec = new StdVector<int>();
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_get_durations(CvPtr, vec.CvPtr));
+            GC.KeepAlive(this);
+            return vec.ToArray();
+        }
+        set
+        {
+            ThrowIfDisposed();
+            ArgumentNullException.ThrowIfNull(value);
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_set_durations(CvPtr, value, value.Length));
+            GC.KeepAlive(this);
+        }
+    }
+
+    /// <summary>
+    /// Frames of the animation. The getter returns freshly-copied <see cref="Mat"/> headers that the
+    /// caller owns and is responsible for disposing.
+    /// </summary>
+    public Mat[] Frames
+    {
+        get
+        {
+            ThrowIfDisposed();
+            using var vec = new VectorOfMat();
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_get_frames(CvPtr, vec.CvPtr));
+            GC.KeepAlive(this);
+            return vec.ToArray();
+        }
+        set
+        {
+            ThrowIfDisposed();
+            ArgumentNullException.ThrowIfNull(value);
+            using var vec = new VectorOfMat(value);
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_set_frames(CvPtr, vec.CvPtr));
+            GC.KeepAlive(this);
+            GC.KeepAlive(value);
+        }
+    }
+
+    /// <summary>
+    /// Image that can be used for the format in addition to the animation, or if animation is not supported
+    /// in the reader (like in PNG). The getter returns a freshly-copied <see cref="Mat"/> header that the
+    /// caller owns and is responsible for disposing.
+    /// </summary>
+    public Mat StillImage
+    {
+        get
+        {
+            ThrowIfDisposed();
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_get_still_image(CvPtr, out var ret));
+            GC.KeepAlive(this);
+            return new Mat(ret);
+        }
+        set
+        {
+            ThrowIfDisposed();
+            ArgumentNullException.ThrowIfNull(value);
+            NativeMethods.HandleException(
+                NativeMethods.imgcodecs_Animation_set_still_image(CvPtr, value.CvPtr));
+            GC.KeepAlive(this);
+            GC.KeepAlive(value);
+        }
+    }
+}

src/OpenCvSharp/Modules/imgcodecs/Animation.cs

@@ -0,0 +1,34 @@
+// ReSharper disable InconsistentNaming
+
+namespace OpenCvSharp;
+
+/// <summary>
+/// Type of metadata chunk stored in / retrieved from an image file by the *WithMetadata family of functions.
+/// </summary>
+public enum ImageMetadataType
+{
+    /// <summary>
+    /// Used when metadata type is unrecognized or not set.
+    /// </summary>
+    Unknown = -1,
+
+    /// <summary>
+    /// EXIF metadata (e.g., camera info, GPS, orientation).
+    /// </summary>
+    EXIF = 0,
+
+    /// <summary>
+    /// XMP metadata (eXtensible Metadata Platform - Adobe format).
+    /// </summary>
+    XMP = 1,
+
+    /// <summary>
+    /// ICC Profile (color profile for color management).
+    /// </summary>
+    ICCP = 2,
+
+    /// <summary>
+    /// cICP Profile (video signal type).
+    /// </summary>
+    CICP = 3
+}

src/OpenCvSharp/Modules/imgcodecs/Enum/ImageMetadataType.cs

@@ -72,5 +72,10 @@ public enum ImreadModes
     /// <summary>
     /// If set, do not rotate the image according to EXIF's orientation flag.
     /// </summary>
-    IgnoreOrientation = 128 
+    IgnoreOrientation = 128,
+
+    /// <summary>
+    /// If set, always convert image to the 3 channel RGB color image.
+    /// </summary>
+    ColorRgb = 256
 };

src/OpenCvSharp/Modules/imgcodecs/Enum/ImreadModes.cs

@@ -0,0 +1,17 @@
+namespace OpenCvSharp;
+
+/// <summary>
+/// Imwrite BMP specific values for the IMWRITE_BMP_COMPRESSION parameter key.
+/// </summary>
+public enum ImwriteBMPCompressionFlags
+{
+    /// <summary>
+    /// Use BI_RGB. OpenCV v4.12.0 or before supports encoding with this compression only.
+    /// </summary>
+    Rgb = 0,
+
+    /// <summary>
+    /// Use BI_BITFIELDS. OpenCV v4.13.0 or later can support encoding with this compression. (only for 32 BPP images)
+    /// </summary>
+    Bitfields = 3
+}