Add AsRows<T>/RowSpan<T> for efficient pixel access; fix Row() GC bug; obsolete Marshal-based indexer

- Fix missing GC.KeepAlive(this) in Mat.Row() (present in RowRange but absent in Row)
- Add Mat.RowSpan<T>(int row): returns a Span<T> over a single row without allocating
  a submatrix object, avoiding P/Invoke per element
- Add MatRowAccessor<T> (ref struct) and Mat.AsRows<T>(): captures data pointer and step
  once at construction, then all row/element access is pure pointer arithmetic with zero
  P/Invoke per row or element — the recommended API for high-performance pixel loops
- Add #if DEBUG guard in At<T>(int i0) to detect misuse on 1-row 2D submatrices
  (e.g. Row(i).At<T>(col) silently accesses wrong memory); guard is compile-time only
  so Release builds have no overhead
- Mark Mat.Indexer<T> and GetGenericIndexer<T>() as [Obsolete]: Marshal.PtrToStructure
  is slower than At<T> and AsRows<T> and predates the unmanaged constraint

Closes #1775

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: shimat

src/OpenCvSharp/Modules/core/Mat/Mat.cs

@@ -1552,6 +1552,7 @@ public Mat Row(int y)
         ThrowIfDisposed();
         NativeMethods.HandleException(
             NativeMethods.core_Mat_row(CvPtr, y, out var matPtr));
+        GC.KeepAlive(this);
         return new Mat(matPtr);
     }
 
@@ -3118,6 +3119,8 @@ public Mat EmptyClone()
     /// </summary>
     /// <typeparam name="T"></typeparam>
     /// <returns></returns>
+    [Obsolete("Use At<T>(row, col) for occasional access, or AsRows<T>() for high-performance loops. " +
+              "GetGenericIndexer uses Marshal.PtrToStructure which is slower than both alternatives.")]
     public Indexer<T> GetGenericIndexer<T>() where T : struct
     {
         return new Indexer<T>(this);
@@ -3136,6 +3139,8 @@ public UnsafeIndexer<T> GetUnsafeGenericIndexer<T>() where T : unmanaged
     /// Mat Indexer
     /// </summary>
     /// <typeparam name="T"></typeparam>
+    [Obsolete("Use At<T>(row, col) for occasional access, or AsRows<T>() for high-performance loops. " +
+              "This class uses Marshal.PtrToStructure which is slower than both alternatives.")]
     public sealed class Indexer<T> : MatIndexer<T> where T : struct
     {
         private readonly long ptrVal;
@@ -3401,13 +3406,23 @@ public T Get<T>(params int[] idx) where T : struct
     }
 
     /// <summary>
-    /// Returns a value to the specified array element.
+    /// Returns a reference to the specified array element.
+    /// For 2D matrices, <paramref name="i0"/> is the row index (dimension 0).
+    /// Do NOT call this with a column index on a row-submatrix obtained from <see cref="Row"/>;
+    /// use <see cref="At{T}(int, int)"/> or <see cref="RowSpan{T}"/> instead.
+    /// For performance-sensitive pixel loops, prefer <see cref="AsRows{T}"/>.
     /// </summary>
     /// <typeparam name="T"></typeparam>
     /// <param name="i0">Index along the dimension 0</param>
-    /// <returns>A value to the specified array element.</returns>
+    /// <returns>A reference to the specified array element.</returns>
     public unsafe ref T At<T>(int i0) where T : unmanaged
     {
+#if DEBUG
+        if (Dims == 2 && Rows == 1 && Cols > 1)
+            throw new InvalidOperationException(
+                "At<T>(int) on a 1-row 2D matrix treats i0 as a row index, not a column index. " +
+                "Use At<T>(0, col) or RowSpan<T>(0) instead.");
+#endif
         var p = Ptr(i0);
         return ref Unsafe.AsRef<T>(p.ToPointer());
     }
@@ -4241,12 +4256,49 @@ public void ForEachAsVec6d(MatForeachFunctionVec6d operation)
 
     #endregion
 
+    /// <summary>
+    /// Returns a <see cref="Span{T}"/> over a single row of this matrix without allocating a submatrix object.
+    /// Padding bytes between rows are excluded from the span.
+    /// For iterating all rows in a loop, prefer <see cref="AsRows{T}"/> which captures the step once.
+    /// </summary>
+    /// <typeparam name="T">Element type. Must match the matrix element type.</typeparam>
+    /// <param name="row">Zero-based row index.</param>
+    /// <returns>A span covering the <paramref name="row"/>-th row.</returns>
+    public unsafe Span<T> RowSpan<T>(int row) where T : unmanaged
+    {
+        ThrowIfDisposed();
+        if (Dims != 2)
+            throw new InvalidOperationException("RowSpan is only supported for 2D matrices.");
+        if ((uint)row >= (uint)Rows)
+            throw new ArgumentOutOfRangeException(nameof(row));
+        var rowPtr = DataPointer + (nint)Step(0) * row;
+        return new Span<T>(rowPtr, Cols * ElemSize() / sizeof(T));
+    }
+
+    /// <summary>
+    /// Returns a <see cref="MatRowAccessor{T}"/> that provides efficient row-by-row access
+    /// with no P/Invoke per row or per element.
+    /// The data pointer, step, and dimensions are captured once; all indexing is pure pointer arithmetic.
+    /// </summary>
+    /// <typeparam name="T">Element type. Must match the matrix element type (e.g. <see cref="Vec3b"/> for CV_8UC3).</typeparam>
+    /// <returns>A <see cref="MatRowAccessor{T}"/> over this matrix.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the matrix is not 2-dimensional.</exception>
+    public unsafe MatRowAccessor<T> AsRows<T>() where T : unmanaged
+    {
+        ThrowIfDisposed();
+        if (Dims != 2)
+            throw new InvalidOperationException("AsRows is only supported for 2D matrices.");
+        var elemCount = Cols * ElemSize() / sizeof(T);
+        return new MatRowAccessor<T>((nint)DataPointer, (nint)Step(0), Rows, elemCount);
+    }
+
     /// <summary>
     /// Creates a new span over the Mat.
+    /// The matrix must be continuous (<see cref="IsContinuous"/>); returns an empty span otherwise.
     /// </summary>
     /// <typeparam name="T"></typeparam>
     /// <returns></returns>
-    public unsafe Span<T> AsSpan<T>() where T : unmanaged  
+    public unsafe Span<T> AsSpan<T>() where T : unmanaged
         => IsContinuous() ? new Span<T>(DataPointer, (int)Total() * ElemSize() / sizeof(T)) : [];
 
     #endregion

src/OpenCvSharp/Modules/core/Mat/MatRowAccessor.cs

@@ -0,0 +1,63 @@
+namespace OpenCvSharp;
+
+/// <summary>
+/// Provides zero-allocation, zero-P/Invoke-per-element row access to a 2D <see cref="Mat"/>.
+/// Obtain via <see cref="Mat.AsRows{T}"/>. The data pointer, step, and dimensions are captured
+/// once at construction time, so all subsequent row indexing is pure pointer arithmetic.
+/// </summary>
+/// <typeparam name="T">Unmanaged element type matching the matrix element type (e.g. <see cref="Vec3b"/> for CV_8UC3).</typeparam>
+/// <remarks>
+/// <para>
+/// Typical usage for per-pixel iteration:
+/// <code>
+/// var rows = mat.AsRows&lt;Vec3b&gt;();
+/// for (int r = 0; r &lt; rows.Count; r++)
+/// {
+///     Span&lt;Vec3b&gt; row = rows[r];
+///     for (int c = 0; c &lt; row.Length; c++)
+///     {
+///         Vec3b pixel = row[c];
+///     }
+/// }
+/// </code>
+/// </para>
+/// <para>
+/// This is a <c>ref struct</c> and therefore cannot be stored in fields, boxed, or used as a
+/// generic type argument.
+/// </para>
+/// </remarks>
+public readonly ref struct MatRowAccessor<T> where T : unmanaged
+{
+    private readonly nint _data;
+    private readonly nint _step;
+    private readonly int _cols;
+
+    /// <summary>Number of rows in the matrix.</summary>
+    public int Count { get; }
+
+    internal MatRowAccessor(nint data, nint step, int rows, int cols)
+    {
+        _data = data;
+        _step = step;
+        Count = rows;
+        _cols = cols;
+    }
+
+    /// <summary>
+    /// Returns a <see cref="Span{T}"/> over the specified row.
+    /// No P/Invoke is performed; this is pure pointer arithmetic.
+    /// Bounds are checked in DEBUG builds only.
+    /// </summary>
+    /// <param name="row">Zero-based row index.</param>
+    public unsafe Span<T> this[int row]
+    {
+        get
+        {
+#if DEBUG
+            if ((uint)row >= (uint)Count)
+                throw new ArgumentOutOfRangeException(nameof(row));
+#endif
+            return new Span<T>((void*)(_data + _step * row), _cols);
+        }
+    }
+}