add alpha_mask attribute to ImageData and refactor mask (#814)

* feature: add alpha-mask to ImageData

* Apply suggestions from code review

Author: vincentsarago

CHANGES.md

@@ -1,6 +1,12 @@
 
 # Unreleased
 
+* only cast data to `uint8` if colormap values are of type `uint8`
+* add `alpha_mask` attribute to `ImageData` class
+* allow partial alpha values from alpha band
+* better handle non-uint8 alpha band
+* remove deprecated `force_binary_mask` option in `reader.read` function  **breaking change**
+
 # 7.8.1 (2025-06-16)
 
 * apply scale/offset to dataset statistics in ImageData object (used for automatic rescaling)

docs/src/models.md

@@ -15,6 +15,7 @@ This class has helper methods like `render` which forward internal data and mask
 - **band_names**: image band's names
 - **dataset_statistics**: Dataset's min/max values (list of (min,max), optional)
 - **cutline_mask**: array representing the mask for `feature` methods
+- **alpha_nask**: array reprsenting the alpha mask (allowing partial transparency)
 
 ```python
 import numpy

rio_tiler/colormap.py

@@ -1,5 +1,6 @@
 """rio-tiler colormap functions and classes."""
 
+import itertools
 import json
 import os
 import pathlib
@@ -166,9 +167,10 @@ def apply_discrete_cmap(
 
     data = numpy.transpose(res, [2, 0, 1])
 
-    # If the output data has values between 0-255
+    # If colormap values are between 0-255
     # we cast the output array to Uint8
-    if data.min() >= 0 and data.max() <= 255:
+    cmap_v = list(itertools.chain(*colormap.values()))
+    if min(cmap_v) >= 0 and max(cmap_v) <= 255:
         data = data.astype("uint8")
 
     return data[:-1], data[-1]
@@ -206,9 +208,10 @@ def apply_intervals_cmap(
 
     data = numpy.transpose(res, [2, 0, 1])
 
-    # If the output data has values between 0-255
+    # If colormap values are between 0-255
     # we cast the output array to Uint8
-    if data.min() >= 0 and data.max() <= 255:
+    cmap_v = list(itertools.chain(*[v for k, v in colormap]))
+    if min(cmap_v) >= 0 and max(cmap_v) <= 255:
         data = data.astype("uint8")
 
     return data[:-1], data[-1]

rio_tiler/io/rasterio.py

@@ -637,7 +637,6 @@ def tile(  # type: ignore
         tilesize: int = 256,
         indexes: Optional[Indexes] = None,
         expression: Optional[str] = None,
-        force_binary_mask: bool = True,
         out_dtype: Optional[Union[str, numpy.dtype]] = None,
         resampling_method: RIOResampling = "nearest",
         unscale: bool = False,
@@ -654,7 +653,6 @@ def tile(  # type: ignore
             tilesize (int, optional): Output image size. Defaults to `256`.
             indexes (int or sequence of int, optional): Band indexes.
             expression (str, optional): rio-tiler expression (e.g. b1/b2+b3).
-            force_binary_mask (bool, optional): Cast returned mask to binary values (0 or 255). Defaults to `True`.
             resampling_method (RIOResampling, optional): RasterIO resampling algorithm. Defaults to `nearest`.
             unscale (bool, optional): Apply 'scales' and 'offsets' on output data value. Defaults to `False`.
             post_process (callable, optional): Function to apply on output data and mask values.
@@ -675,7 +673,6 @@ def tile(  # type: ignore
             max_size=None,
             indexes=indexes,
             expression=expression,
-            force_binary_mask=force_binary_mask,
             out_dtype=out_dtype,
             resampling_method=resampling_method,
             unscale=unscale,
@@ -690,7 +687,6 @@ def part(  # type: ignore
         max_size: Optional[int] = None,
         height: Optional[int] = None,
         width: Optional[int] = None,
-        force_binary_mask: bool = True,
         out_dtype: Optional[Union[str, numpy.dtype]] = None,
         resampling_method: RIOResampling = "nearest",
         unscale: bool = False,
@@ -707,7 +703,6 @@ def part(  # type: ignore
             max_size (int, optional): Limit the size of the longest dimension of the dataset read, respecting bounds X/Y aspect ratio.
             height (int, optional): Output height of the array.
             width (int, optional): Output width of the array.
-            force_binary_mask (bool, optional): Cast returned mask to binary values (0 or 255). Defaults to `True`.
             resampling_method (RIOResampling, optional): RasterIO resampling algorithm. Defaults to `nearest`.
             unscale (bool, optional): Apply 'scales' and 'offsets' on output data value. Defaults to `False`.
             post_process (callable, optional): Function to apply on output data and mask values.
@@ -733,7 +728,6 @@ def part(  # type: ignore
             width=width,
             height=height,
             indexes=indexes,
-            force_binary_mask=force_binary_mask,
             out_dtype=out_dtype,
             resampling_method=resampling_method,
             unscale=unscale,
@@ -804,7 +798,6 @@ def feature(  # type: ignore
         max_size: Optional[int] = None,
         height: Optional[int] = None,
         width: Optional[int] = None,
-        force_binary_mask: bool = True,
         out_dtype: Optional[Union[str, numpy.dtype]] = None,
         resampling_method: RIOResampling = "nearest",
         unscale: bool = False,
@@ -824,7 +817,6 @@ def feature(  # type: ignore
             max_size=max_size,
             height=height,
             width=width,
-            force_binary_mask=force_binary_mask,
             out_dtype=out_dtype,
             resampling_method=resampling_method,
             unscale=unscale,