Add to_array/decode_into support for fg_value/bg_value, dtype, HWC output

- Extend to_array with fg_value, bg_value, dtype params (2D and 3D HWC)
- Extend decode_into with fg_value, bg_value params for float32/float64
- Add fused-type Cython decode paths for float32/float64
- Deprecate 'value' param in favor of 'fg_value' with warnings
- Deprecate 'thresh128' param in from_array with warning

Author: isarandi

src/rlemasklib/oop.py

@@ -2,13 +2,16 @@
 
 import itertools
 import os
+import warnings
 from collections.abc import Iterable
 from typing import Union, Sequence, Optional, Callable
 
 import numpy as np
 from .boolfunc import BoolFunc
 from .oop_cython import RLECy
 
+_UNSET = object()
+
 
 class RLEMask:
     """Run-length encoded mask.
@@ -129,6 +132,9 @@ def from_array(
             thresh128: deprecated, equivalent to threshold=128.
         """
         if thresh128:
+            warnings.warn(
+                "The 'thresh128' parameter is deprecated, use 'threshold=128' instead.",
+                DeprecationWarning, stacklevel=2)
             threshold = 128
         result = RLEMask._init()
         result.cy._i_from_array(mask_array, threshold, is_sparse)
@@ -3063,52 +3069,145 @@ def to_dict(self, zlevel: Optional[int] = None) -> dict:
         """
         return self.cy.to_dict(zlevel)
 
-    def to_array(self, value: int = 1, order="F") -> np.ndarray:
-        """Convert the RLE mask to a dense 2D uint8 numpy array.
+    def to_array(
+            self, fg_value=1, bg_value=0, dtype=np.uint8, order="F", *, value=_UNSET
+    ) -> np.ndarray:
+        """Convert the RLE mask to a dense numpy array.
+
+        Background pixels get ``bg_value`` and foreground pixels get ``fg_value``.
+
+        If either ``fg_value`` or ``bg_value`` is a tuple, list, or 1D array, the result is a
+        3D HWC array with one channel per element. A scalar value for the other parameter is
+        broadcast to all channels.
 
-        False (background) values become 0 and True (foreground) values become the specified value.
         The RLE is internally stored for the Fortran order, so order='F' is faster, because
         'C' requires a transpose. To improve efficiency, the transpose is done either in RLE or
         in dense form, depending on the sparseness of the mask.
 
         Args:
-            value: the "True" value to use in the resulting array
+            fg_value: the foreground value (scalar for 2D, tuple/list/array for HWC)
+            bg_value: the background value (scalar for 2D, tuple/list/array for HWC)
+            dtype: the numpy dtype of the resulting array (default: np.uint8)
             order: the order of the array ('C' for row-major, 'F' for column-major)
+            value: deprecated alias for ``fg_value``
 
         Returns:
-            An F or C-contiguous 2D numpy array of type uint8 representing the mask.
+            A 2D or 3D numpy array representing the mask.
 
         See Also:
             :meth:`__array__`, :meth:`from_array`
         """
-        return self.cy._r_to_dense_array(value, order)
+        if value is not _UNSET:
+            warnings.warn(
+                "The 'value' parameter is deprecated, use 'fg_value' instead.",
+                DeprecationWarning, stacklevel=2)
+            fg_value = value
+
+        fg_multi = isinstance(fg_value, (tuple, list)) or (isinstance(fg_value, np.ndarray) and fg_value.ndim == 1)
+        bg_multi = isinstance(bg_value, (tuple, list)) or (isinstance(bg_value, np.ndarray) and bg_value.ndim == 1)
+
+        if not fg_multi and not bg_multi:
+            return self.cy._r_to_dense_array(fg_value, bg_value, order, np.dtype(dtype))
+
+        # Multi-valued: produce HWC array
+        if fg_multi:
+            fg_value = np.asarray(fg_value, dtype=dtype)
+            n_channels = len(fg_value)
+        if bg_multi:
+            bg_value = np.asarray(bg_value, dtype=dtype)
+            n_channels = len(bg_value)
+        if n_channels == 0:
+            raise ValueError("fg_value/bg_value must have at least one channel")
+        if fg_multi and bg_multi and len(fg_value) != len(bg_value):
+            raise ValueError(
+                f"fg_value length ({len(fg_value)}) != bg_value length ({len(bg_value)})")
 
-    def decode_into(self, arr: np.ndarray, value: int = 1) -> None:  # noqa: vulture
-        """Decode the RLE mask into an existing array, only setting foreground pixels.
+        # Broadcast scalar to all channels
+        dtype = np.dtype(dtype)
+        if not fg_multi:
+            fg_value = np.full(n_channels, fg_value, dtype=dtype)
+        if not bg_multi:
+            bg_value = np.full(n_channels, bg_value, dtype=dtype)
 
-        This method sets foreground pixels to the specified value while leaving
-        background pixels unchanged. This is useful for overlaying multiple masks
-        onto a single array, e.g., creating a label map or visualization.
+        h, w = self.shape
+        arr = np.empty((h, w, n_channels), dtype=dtype, order='C')
+        arr[:] = bg_value  # broadcasts along last axis
+        if dtype == np.uint8:
+            self.cy._decode_into(arr, fg_value)
+        elif dtype == np.float32 or dtype == np.float64:
+            self.cy._decode_typed_multi_into(arr, np.asarray(fg_value, dtype=dtype))
+        else:
+            mask01 = self.cy._r_to_dense_array(1, 0, 'C')
+            arr[mask01 != 0] = fg_value
+
+        if order == 'F' and not arr.flags.f_contiguous:
+            arr = np.asfortranarray(arr)
+        return arr
+
+    def decode_into(  # noqa: vulture
+            self, arr: np.ndarray, fg_value=None, bg_value=None,
+            *, value=_UNSET) -> None:
+        """Decode the RLE mask into an existing array.
+
+        Writes ``fg_value`` to foreground pixels and/or ``bg_value`` to background pixels.
+        Pixels whose corresponding parameter is ``None`` are left unchanged.
+
+        Supports uint8, float32, and float64 arrays (2D or 3D HWC).
 
         Args:
-            arr: A 2D uint8 numpy array with shape matching the mask.
-                 Must be either C-contiguous or Fortran-contiguous.
-            value: The value to assign to foreground pixels (default: 1).
+            arr: A numpy array with shape matching the mask.
+                 Must be either C-contiguous or Fortran-contiguous (or strided for 2D uint8).
+            fg_value: The value to assign to foreground pixels (default: None, meaning unchanged).
+            bg_value: The value to assign to background pixels (default: None, meaning unchanged).
+            value: deprecated alias for ``fg_value``
 
         Raises:
             ValueError: If array shape doesn't match mask shape or array is not contiguous.
 
         Example:
             >>> canvas = np.zeros((100, 100), dtype=np.uint8)
-            >>> mask1.decode_into(canvas, value=1)
-            >>> mask2.decode_into(canvas, value=2)
-            >>> mask3.decode_into(canvas, value=3)
+            >>> mask1.decode_into(canvas, fg_value=1)
+            >>> mask2.decode_into(canvas, fg_value=2)
+            >>> mask3.decode_into(canvas, fg_value=3)
             # canvas now contains 1, 2, 3 for respective mask regions
 
         See Also:
             :meth:`to_array`
         """
-        self.cy._decode_into(arr, value)
+        if value is not _UNSET:
+            warnings.warn(
+                "The 'value' parameter is deprecated, use 'fg_value' instead.",
+                DeprecationWarning, stacklevel=2)
+            fg_value = value
+
+        if bg_value is not None and fg_value is not None:
+            arr[:] = bg_value
+            self._decode_into_typed(arr, fg_value)
+        elif fg_value is not None:
+            self._decode_into_typed(arr, fg_value)
+        elif bg_value is not None:
+            self.complement()._decode_into_typed(arr, bg_value)
+        # else: both None, no-op
+
+    def _decode_into_typed(self, arr, fg_value):
+        """Dispatch decode_into to the right Cython method based on array dtype."""
+        if arr.dtype == np.uint8:
+            self.cy._decode_into(arr, fg_value)
+        elif arr.dtype == np.float32 or arr.dtype == np.float64:
+            if arr.ndim == 2:
+                if isinstance(fg_value, (tuple, list, np.ndarray)):
+                    raise ValueError(
+                        "fg_value must be scalar for 2D arrays; use a 3D HWC array for multi-channel values")
+                self.cy._decode_typed_into(arr, fg_value)
+            else:
+                fg_arr = np.asarray(fg_value, dtype=arr.dtype)
+                if fg_arr.ndim == 0:
+                    fg_arr = np.full(arr.shape[2], fg_value, dtype=arr.dtype)
+                self.cy._decode_typed_multi_into(arr, fg_arr)
+        else:
+            order = 'F' if arr.flags.f_contiguous else 'C'
+            mask01 = self.cy._r_to_dense_array(1, 0, order)
+            arr[mask01 != 0] = fg_value
 
     def __reduce__(self):
         """Support for pickle serialization."""
@@ -3213,7 +3312,7 @@ def _forward_slice(slice_obj, length):
 #     cropped = x.crop(box_old, inplace=False)
 #     interp = cv2.INTER_LINEAR if fx > 1 and fy > 1 else cv2.INTER_AREA
 #     resized = cv2.resize(
-#         cropped.to_array(order='C', value=255),
+#         cropped.to_array(order='C', fg_value=255),
 #         (box_new[2], box_new[3]),
 #         fx=fx, fy=fy, interpolation=interp)
 #     resized = RLEMask.from_array(resized, thresh128=True, is_sparse=x.density < 0.04)

src/rlemasklib/oop_cython.pyx

@@ -1,6 +1,9 @@
 # cython: language_level=3
 # distutils: language = c
 
+cimport cython
+from cython cimport floating
+
 import zlib
 import numpy as np
 cimport numpy as np
@@ -207,6 +210,40 @@ ctypedef const RLE *ConstRLEPtr
 ctypedef const ConstRLEPtr *ConstRLEPtrConstPtr
 ctypedef const RLEPtr *ConstRLEPtrPtr
 
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+cdef bint _rle_counts_valid(RLE *r) noexcept nogil:
+    cdef siz total = 0
+    cdef siz i
+    for i in range(r.m):
+        total += r.cnts[i]
+    return total == r.h * r.w
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+cdef void _rle_decode_typed(RLE *r, floating[::1] out, floating fg_value) noexcept nogil:
+    cdef siz i, j, pos = 0
+    for i in range(r.m):
+        if i % 2 == 1:
+            for j in range(r.cnts[i]):
+                out[pos + j] = fg_value
+        pos += r.cnts[i]
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+cdef void _rle_decode_typed_multi(RLE *r, floating[::1] out, siz n_channels, floating[::1] fg_values) noexcept nogil:
+    cdef siz i, j, c, pos = 0
+    for i in range(r.m):
+        if i % 2 == 1:
+            for j in range(r.cnts[i]):
+                for c in range(n_channels):
+                    out[(pos + j) * n_channels + c] = fg_values[c]
+        pos += r.cnts[i]
+
+
 # python class to wrap RLE array in C
 # the class handles the memory allocation and deallocation
 cdef class RLECy:
@@ -867,30 +904,111 @@ cdef class RLECy:
             else:
                 # Strided array (e.g., channel slice of HWC image)
                 # Use strided C function - strides are in bytes, arr.itemsize is 1 for uint8
+                if not _rle_counts_valid(&self.r):
+                    raise ValueError(
+                        "Invalid RLE: sum of runlengths does not match pixel count")
                 row_stride = arr.strides[0]
                 col_stride = arr.strides[1]
                 rleDecodeStrided(&self.r, <byte *> np.PyArray_DATA(arr), row_stride, col_stride,
                                  value)
 
-    def _r_to_dense_array(self, value, order) -> np.ndarray:
+    def _r_to_dense_array(self, fg_value, bg_value, order, dtype=np.uint8) -> np.ndarray:
+        cdef np.ndarray arr
+
+        dtype = np.dtype(dtype)
+        shape = (self.r.h, self.r.w)
         if self.r.h == 0 or self.r.w == 0:
-            return np.empty((self.r.h, self.r.w), dtype=np.uint8)
+            return np.full(shape, bg_value, dtype=dtype)
 
-        if order == 'F':
-            arr = np.zeros((self.r.h, self.r.w), dtype=np.uint8, order='F')
+        # For C-order with sparse masks, allocate C directly to skip full transpose
+        alloc_order = order if (order == 'F' or self.r.m < self.r.h * self.r.w * 0.04) else 'F'
+
+        if bg_value == 0:
+            arr = np.zeros(shape, dtype=dtype, order=alloc_order)
         else:
-            is_sparse = self.r.m < self.r.h * self.r.w * 0.04
-            if is_sparse:
-                arr = np.zeros((self.r.h, self.r.w), dtype=np.uint8, order='C')
-            else:
-                arr = np.zeros((self.r.h, self.r.w), dtype=np.uint8, order='F')
+            arr = np.full(shape, bg_value, dtype=dtype, order=alloc_order)
 
-        self._decode_into(arr, value)
+        if dtype == np.uint8:
+            self._decode_into(arr, fg_value)
+        elif dtype == np.float32 or dtype == np.float64:
+            self._decode_typed_into(arr, fg_value)
+        else:
+            mask01 = np.zeros(shape, dtype=np.uint8, order=alloc_order)
+            self._decode_into(mask01, 1)
+            arr[mask01 != 0] = fg_value
 
-        if order == 'C' and arr.flags.f_contiguous:
+        if order == 'C' and not arr.flags.c_contiguous:
             return np.ascontiguousarray(arr)
         return arr
 
+    def _decode_typed_into(self, np.ndarray arr, fg_value):
+        """Decode RLE into a typed 2D array (float32/float64) using fused types."""
+        cdef RLECy transp
+        cdef float[::1] flat_f32
+        cdef double[::1] flat_f64
+        cdef RLE *rle_ptr
+
+        if arr.shape[0] != self.r.h or arr.shape[1] != self.r.w:
+            raise ValueError(
+                f"Array shape ({arr.shape[0]}, {arr.shape[1]}) does not match RLE shape ({self.r.h}, {self.r.w})")
+
+        if arr.dtype != np.float32 and arr.dtype != np.float64:
+            raise ValueError(f"_decode_typed_into only supports float32 and float64, got {arr.dtype}")
+
+        if arr.flags.f_contiguous:
+            rle_ptr = &self.r
+        elif arr.flags.c_contiguous:
+            transp = self._r_transpose()
+            rle_ptr = &transp.r
+        else:
+            raise ValueError("Array must be C-contiguous or F-contiguous")
+
+        if not _rle_counts_valid(rle_ptr):
+            raise ValueError("Invalid RLE: sum of runlengths does not match pixel count")
+
+        order = 'F' if arr.flags.f_contiguous else 'C'
+        if arr.dtype == np.float32:
+            flat_f32 = arr.ravel(order=order)
+            _rle_decode_typed(rle_ptr, flat_f32, <float>fg_value)
+        else:
+            flat_f64 = arr.ravel(order=order)
+            _rle_decode_typed(rle_ptr, flat_f64, <double>fg_value)
+
+    def _decode_typed_multi_into(self, np.ndarray arr, np.ndarray fg_values):
+        """Decode RLE into a typed 3D HWC array (float32/float64) using fused types."""
+        cdef RLECy transp
+        cdef float[::1] flat_f32, fgv_f32
+        cdef double[::1] flat_f64, fgv_f64
+        cdef RLE *rle_ptr
+        cdef siz n_channels = arr.shape[2]
+
+        if arr.shape[0] != self.r.h or arr.shape[1] != self.r.w:
+            raise ValueError(
+                f"Array shape ({arr.shape[0]}, {arr.shape[1]}) does not match RLE shape ({self.r.h}, {self.r.w})")
+
+        if fg_values.shape[0] != n_channels:
+            raise ValueError(
+                f"fg_values length ({fg_values.shape[0]}) does not match "
+                f"number of channels ({n_channels})")
+
+        if not arr.flags.c_contiguous:
+            raise ValueError("3D array must be C-contiguous for typed multi-channel decode")
+
+        transp = self._r_transpose()
+        rle_ptr = &transp.r
+
+        if not _rle_counts_valid(rle_ptr):
+            raise ValueError("Invalid RLE: sum of runlengths does not match pixel count")
+
+        if arr.dtype == np.float32:
+            flat_f32 = arr.ravel(order='C')
+            fgv_f32 = np.ascontiguousarray(fg_values, dtype=np.float32)
+            _rle_decode_typed_multi(rle_ptr, flat_f32, n_channels, fgv_f32)
+        else:
+            flat_f64 = arr.ravel(order='C')
+            fgv_f64 = np.ascontiguousarray(fg_values, dtype=np.float64)
+            _rle_decode_typed_multi(rle_ptr, flat_f64, n_channels, fgv_f64)
+
     def _i_zeros(self, shape):
         rleZeros(&self.r, shape[0], shape[1])