Merge pull request #2028 from shimat/fix/filenode-filestorage-quality

Close FileNode/FileStorage gaps vs. the native CV_WRAP surface

Author: shimat

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

@@ -450,6 +450,9 @@ public static partial void vector_string_getElements(
 
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial void vector_string_delete(IntPtr vector);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial void vector_string_pushBack(OpenCvSafeHandle vector, [MarshalAs(UnmanagedType.LPStr)] string value);
     #endregion
     #region vector<cv::line_descriptor::KeyLine>
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]

src/OpenCvSharp/Internal/PInvoke/NativeMethods/core/NativeMethods_core_FileNode.cs

@@ -48,10 +48,17 @@ public static partial ExceptionStatus core_FileNode_operatorThis_byString(
     public static partial ExceptionStatus core_FileNode_name(OpenCvSafeHandle obj, IntPtr buf);
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileNode_size(OpenCvSafeHandle obj, out IntPtr returnValue);
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileNode_rawSize(OpenCvSafeHandle obj, out IntPtr returnValue);
+
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileNode_keys(OpenCvSafeHandle obj, IntPtr returnValue);
 
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileNode_toInt(OpenCvSafeHandle obj, out int returnValue);
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileNode_toInt64(OpenCvSafeHandle obj, out long returnValue);
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileNode_toFloat(OpenCvSafeHandle obj, out float returnValue);
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileNode_toDouble(OpenCvSafeHandle obj, out double returnValue);
@@ -74,6 +81,8 @@ public static partial ExceptionStatus core_FileNode_readRaw(
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileNode_read_int(OpenCvSafeHandle node, out int value, int defaultValue);
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileNode_read_int64(OpenCvSafeHandle node, out long value, long defaultValue);
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileNode_read_float(OpenCvSafeHandle node, out float value, float defaultValue);
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileNode_read_double(OpenCvSafeHandle node, out double value, double defaultValue);

src/OpenCvSharp/Internal/PInvoke/NativeMethods/core/NativeMethods_core_FileStorage.cs

@@ -78,10 +78,22 @@ public static partial ExceptionStatus core_FileStorage_startWriteStruct(
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileStorage_state(OpenCvSafeHandle obj, out int returnValue);
 
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileStorage_getFormat(OpenCvSafeHandle obj, out int returnValue);
+
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileStorage_write_int(
         OpenCvSafeHandle fs, [MarshalAs(UnmanagedType.LPStr)] string name, int value);
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileStorage_write_bool(
+        OpenCvSafeHandle fs, [MarshalAs(UnmanagedType.LPStr)] string name, int value);
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileStorage_write_int64(
+        OpenCvSafeHandle fs, [MarshalAs(UnmanagedType.LPStr)] string name, long value);
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    public static partial ExceptionStatus core_FileStorage_write_vectorOfString(
+        OpenCvSafeHandle fs, [MarshalAs(UnmanagedType.LPStr)] string name, IntPtr value);
+    [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     public static partial ExceptionStatus core_FileStorage_write_float(
         OpenCvSafeHandle fs, [MarshalAs(UnmanagedType.LPStr)] string name, float value);
     [LibraryImport(DllExtern), UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]

src/OpenCvSharp/Internal/Vectors/VectorOfString.cs

@@ -26,6 +26,23 @@ public VectorOfString(int size)
         SetSafeHandle(new OpenCvPtrSafeHandle(p, ownsHandle: false, releaseAction: null));
     }
 
+    /// <summary>
+    /// Creates a vector populated from <paramref name="data"/>.
+    /// </summary>
+    /// <param name="data"></param>
+    public VectorOfString(IEnumerable<string> data)
+    {
+        ArgumentNullException.ThrowIfNull(data);
+        var p = NativeMethods.vector_string_new1();
+        SetSafeHandle(new OpenCvPtrSafeHandle(p, ownsHandle: false, releaseAction: null));
+        foreach (var s in data)
+        {
+            if (s is null)
+                throw new ArgumentException("Collection must not contain null elements.", nameof(data));
+            NativeMethods.vector_string_pushBack(Handle, s);
+        }
+    }
+
     /// <summary>
     /// Releases unmanaged resources
     /// </summary>

src/OpenCvSharp/Modules/core/FileNode.cs

@@ -1,5 +1,6 @@
 using System.Collections;
 using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Nodes;
 using OpenCvSharp.Internal;
 using OpenCvSharp.Internal.Vectors;
 
@@ -45,6 +46,28 @@ private void InitSafeHandle(IntPtr p, bool ownsHandle = true)
             static h => NativeMethods.HandleException(NativeMethods.core_FileNode_delete(h))));
     }
 
+    /// <summary>
+    /// Wraps a native cv::FileNode* as a nullable FileNode, normalizing the "not found" case.
+    /// Native FileNode lookups (FileStorage/FileNode indexers) never return a null pointer -
+    /// a missing key comes back as a non-null, heap-allocated node whose Type is None. That
+    /// sentinel is indistinguishable from a key that is present but explicitly stores a "none"
+    /// value (e.g. YAML's <c>~</c>), so this treats both as "not found" and returns null,
+    /// which is what a C# caller chaining with <c>?.</c> actually expects.
+    /// </summary>
+    internal static FileNode? FromRawPtrOrNull(IntPtr ptr)
+    {
+        if (ptr == IntPtr.Zero)
+            return null;
+
+        var node = new FileNode(ptr);
+        if (node.IsNone)
+        {
+            node.Dispose();
+            return null;
+        }
+        return node;
+    }
+
     #endregion
 
     #region Cast
@@ -74,6 +97,31 @@ public int ToInt32()
         return ret;
     }
 
+    /// <summary>
+    /// Returns the node content as a signed 64-bit integer. If the node stores a floating-point number, it is rounded.
+    /// </summary>
+    /// <param name="node"></param>
+    /// <returns></returns>
+    public static explicit operator long(FileNode node)
+    {
+        ArgumentNullException.ThrowIfNull(node);
+        return node.ToInt64();
+    }
+
+    /// <summary>
+    /// Returns the node content as a signed 64-bit integer. If the node stores a floating-point number, it is rounded.
+    /// </summary>
+    /// <returns></returns>
+    public long ToInt64()
+    {
+        ThrowIfDisposed();
+
+        NativeMethods.HandleException(
+            NativeMethods.core_FileNode_toInt64(Handle, out var ret));
+
+        return ret;
+    }
+
     /// <summary>
     /// Returns the node content as float
     /// </summary>
@@ -176,12 +224,65 @@ public Mat ToMat()
         return matrix;
     }
 
+    /// <summary>
+    /// Converts this node (and, recursively, its children) into a <see cref="JsonNode"/> tree,
+    /// regardless of whether the underlying <see cref="FileStorage"/> was opened as XML, YAML or
+    /// JSON. This is a generic structural conversion (scalars, sequences, mappings) - it does not
+    /// give special treatment to OpenCV-specific encodings such as <c>Mat</c>/<c>KeyPoint</c>/
+    /// <c>DMatch</c>, which come through as their raw mapping/sequence shape (e.g. a Mat becomes a
+    /// JSON object with "rows"/"cols"/"dt"/"data" members, not an <see cref="OpenCvSharp.Mat"/>).
+    /// The result can be fed to <see cref="System.Text.Json.JsonSerializer"/> or queried directly.
+    /// </summary>
+    /// <returns>
+    /// The converted node, or null for a <see cref="Types.None"/> node (mirroring JSON <c>null</c>).
+    /// </returns>
+    public JsonNode? ToJsonNode()
+    {
+        ThrowIfDisposed();
+
+        return Type switch
+        {
+            Types.None => null,
+            Types.Int => JsonValue.Create(ToInt64()),
+            Types.Real => JsonValue.Create(ToDouble()),
+            Types.Str => JsonValue.Create(ToString()),
+            Types.Seq => SeqToJsonArray(),
+            Types.Map => MapToJsonObject(),
+            _ => throw new NotSupportedException($"Cannot convert a FileNode of type {Type} to a JsonNode."),
+        };
+    }
+
+    private JsonArray SeqToJsonArray()
+    {
+        var array = new JsonArray();
+        foreach (var child in this)
+        {
+            using (child)
+            {
+                array.Add(child.ToJsonNode());
+            }
+        }
+        return array;
+    }
+
+    private JsonObject MapToJsonObject()
+    {
+        var obj = new JsonObject();
+        foreach (var key in Keys)
+        {
+            using var child = this[key];
+            obj[key] = child?.ToJsonNode();
+        }
+        return obj;
+    }
+
     #endregion
 
     #region Properties
 
     /// <summary>
-    /// returns element of a mapping node
+    /// Returns the element of a mapping node with the given key, or null if the key is not
+    /// present (or is explicitly stored as a "none" value).
     /// </summary>
     public FileNode? this[string nodeName]
     {
@@ -193,28 +294,69 @@ public FileNode? this[string nodeName]
             NativeMethods.HandleException(
                 NativeMethods.core_FileNode_operatorThis_byString(Handle, nodeName, out var node));
 
-            if (node == IntPtr.Zero)
-                return null;
-            return new FileNode(node);
+            return FromRawPtrOrNull(node);
         }
     }
 
     /// <summary>
-    /// returns element of a sequence node
+    /// Returns the element of a sequence node at the given index, or null if the index is out
+    /// of range (or the element is explicitly stored as a "none" value).
     /// </summary>
     public FileNode? this[int i]
     {
         get
         {
             ThrowIfDisposed();
 
-            NativeMethods.HandleException( 
+            NativeMethods.HandleException(
                 NativeMethods.core_FileNode_operatorThis_byInt(Handle, i, out var node));
 
-            if (node == IntPtr.Zero)
+            return FromRawPtrOrNull(node);
+        }
+    }
+
+    /// <summary>
+    /// Navigates a chain of mapping keys (<see cref="string"/>) and/or sequence indices
+    /// (<see cref="int"/>), disposing every intermediate <see cref="FileNode"/> along the way.
+    /// Equivalent to repeated indexer chaining (e.g. <c>node["a"][2]["b"]</c>), except that the
+    /// indexer chain leaves every intermediate node unreferenced - each one is still a real
+    /// native allocation that would otherwise sit around until the GC finalizes it.
+    /// </summary>
+    /// <param name="path">One or more mapping keys / sequence indices to follow, in order.</param>
+    /// <returns>The node at the end of the path, or null if any segment along the way is missing.</returns>
+    public FileNode? GetPath(params object[] path)
+    {
+        ArgumentNullException.ThrowIfNull(path);
+        if (path.Length == 0)
+            throw new ArgumentException("Path must contain at least one key or index.", nameof(path));
+
+        ThrowIfDisposed();
+
+        var current = this;
+        var ownsCurrent = false;
+
+        foreach (var segment in path)
+        {
+            var next = segment switch
+            {
+                string key => current[key],
+                int index => current[index],
+                _ => throw new ArgumentException(
+                    $"Path segments must be string (mapping key) or int (sequence index), got '{segment?.GetType()}'.",
+                    nameof(path)),
+            };
+
+            if (ownsCurrent)
+                current.Dispose();
+
+            if (next is null)
                 return null;
-            return new FileNode(node);
+
+            current = next;
+            ownsCurrent = true;
         }
+
+        return current;
     }
 
     /// <summary>
@@ -368,6 +510,35 @@ public long Size
         }
     }
 
+    /// <summary>
+    /// Returns the keys of a mapping node.
+    /// </summary>
+    public string[] Keys
+    {
+        get
+        {
+            ThrowIfDisposed();
+            using var buf = new VectorOfString();
+            NativeMethods.HandleException(
+                NativeMethods.core_FileNode_keys(Handle, buf.CvPtr));
+            return buf.ToArray();
+        }
+    }
+
+    /// <summary>
+    /// Returns the raw size of the node in bytes.
+    /// </summary>
+    public long RawSize
+    {
+        get
+        {
+            ThrowIfDisposed();
+            NativeMethods.HandleException(
+                NativeMethods.core_FileNode_rawSize(Handle, out var ret));
+            return ret.ToInt64();
+        }
+    }
+
     /// <summary>
     /// Returns type of the node.
     /// </summary>
@@ -433,14 +604,17 @@ IEnumerator IEnumerable.GetEnumerator()
     /// Reads node elements to the buffer with the specified format
     /// </summary>
     /// <param name="fmt"></param>
-    /// <param name="vec"></param>
-    /// <param name="len"></param>
-    public void ReadRaw(string fmt, IntPtr vec, long len)
+    /// <param name="vec">The buffer to read into.</param>
+    public unsafe void ReadRaw(string fmt, Span<byte> vec)
     {
         ThrowIfDisposed();
         ArgumentNullException.ThrowIfNull(fmt);
-        NativeMethods.HandleException(
-            NativeMethods.core_FileNode_readRaw(Handle, fmt, vec, new IntPtr(len)));
+
+        fixed (byte* p = vec)
+        {
+            NativeMethods.HandleException(
+                NativeMethods.core_FileNode_readRaw(Handle, fmt, (IntPtr)p, new IntPtr(vec.Length)));
+        }
     }
 
     #region Read
@@ -457,6 +631,18 @@ public int ReadInt(int defaultValue = default)
         return value;
     }
 
+    /// <summary>
+    /// Reads the node element as Int64 (long)
+    /// </summary>
+    /// <param name="defaultValue"></param>
+    /// <returns></returns>
+    public long ReadInt64(long defaultValue = default)
+    {
+        NativeMethods.HandleException(
+            NativeMethods.core_FileNode_read_int64(Handle, out var value, defaultValue));
+        return value;
+    }
+
     /// <summary>
     /// Reads the node element as Single (float)
     /// </summary>