add grayscale and bitonal algorithms (#1234)

Author: vincentsarago

CHANGES.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+* add `grayscale` and `bitonal` algorithms
+
 ## 0.24.0 (2025-09-23)
 
 ### Misc

docs/src/user_guide/algorithms.md

@@ -23,7 +23,8 @@ We added a set of custom algorithms:
 - `std`: Return the **Standard Deviation** along the `bands` axis.
 - `var`: Return **Variance** along the `bands` axis.
 - `sum`: Return **Sum** along the `bands` axis.
-
+- `grayscale`: Return a **grayscale** version of an image using ITU-R 601-2 luma transformation.
+- `bitonal`: All values larger than 127 are set to 255 (white), all other values to 0 (black).
 
 ### Usage
 

src/titiler/core/tests/test_algorithms.py

@@ -350,3 +350,71 @@ def test_math_algorithm(name, numpy_method, options):
         out.array, numpy_method(img.array, axis=0, keepdims=True, **options)
     )
     assert out.array[0, 1, 1] is numpy.ma.masked
+
+
+def test_bitonal_algorithm():
+    """Test bitonal algorithm."""
+    algo = default_algorithms.get("bitonal")()
+
+    arr = numpy.ma.MaskedArray(
+        numpy.zeros((1, 256, 256), dtype="uint8"),
+        mask=numpy.zeros((1, 256, 256), dtype="bool"),
+    )
+    arr.data[0, 100:200, 100:200] = 200
+    arr.mask[0, 120:130, 120:130] = True
+    img = ImageData(arr)
+    out = algo(img)
+    assert out.array.shape == (1, 256, 256)
+    assert out.array.dtype == "uint8"
+    assert out.array[0, 125, 125] is numpy.ma.masked
+    assert out.array[0, 150, 150] == 255
+    assert out.array[0, 50, 50] == 0
+
+    arr = numpy.ma.MaskedArray(
+        numpy.zeros((3, 256, 256), dtype="uint8"),
+        mask=numpy.zeros((3, 256, 256), dtype="bool"),
+    )
+    arr.data[:, 100:200, 100:200] = 200
+    arr.mask[0, 120:130, 120:130] = True
+    img = ImageData(arr)
+    out = algo(img)
+    assert out.array.shape == (1, 256, 256)
+    assert out.array.dtype == "uint8"
+    assert out.array[0, 125, 125] is numpy.ma.masked
+    assert out.array[0, 150, 150] == 255
+    assert out.array[0, 50, 50] == 0
+
+    arr = numpy.ma.MaskedArray(
+        numpy.zeros((4, 256, 256), dtype="uint8"),
+        mask=numpy.zeros((4, 256, 256), dtype="bool"),
+    )
+    img = ImageData(arr)
+    with pytest.raises(ValueError):
+        out = algo(img)
+
+
+def test_grayscale_algorithm():
+    """Test grayscale algorithm."""
+    algo = default_algorithms.get("grayscale")()
+
+    arr = numpy.ma.MaskedArray(
+        numpy.zeros((3, 256, 256), dtype="uint8"),
+        mask=numpy.zeros((3, 256, 256), dtype="bool"),
+    )
+    arr.data[:, 100:200, 100:200] = 200
+    arr.mask[0, 120:130, 120:130] = True
+    img = ImageData(arr)
+    out = algo(img)
+    assert out.array.shape == (1, 256, 256)
+    assert out.array.dtype == "uint8"
+    assert out.array[0, 125, 125] is numpy.ma.masked
+    assert out.array[0, 150, 150] != 0
+    assert out.array[0, 50, 50] == 0
+
+    arr = numpy.ma.MaskedArray(
+        numpy.zeros((2, 256, 256), dtype="uint8"),
+        mask=numpy.zeros((2, 256, 256), dtype="bool"),
+    )
+    img = ImageData(arr)
+    with pytest.raises(ValueError):
+        out = algo(img)

src/titiler/core/titiler/core/algorithm/__init__.py

@@ -15,6 +15,7 @@
     BaseAlgorithm,
 )
 from titiler.core.algorithm.dem import Contours, HillShade, Slope, TerrainRGB, Terrarium
+from titiler.core.algorithm.image import ToBitonal, ToGrayScale
 from titiler.core.algorithm.index import NormalizedIndex
 from titiler.core.algorithm.math import _Max, _Mean, _Median, _Min, _Std, _Sum, _Var
 from titiler.core.algorithm.ops import CastToInt, Ceil, Floor
@@ -36,6 +37,8 @@
     "std": _Std,
     "var": _Var,
     "sum": _Sum,
+    "grayscale": ToGrayScale,
+    "bitonal": ToBitonal,
 }
 
 

src/titiler/core/titiler/core/algorithm/image.py

@@ -0,0 +1,73 @@
+"""titiler.core.algorithm Images"""
+
+import numpy
+from rio_tiler.models import ImageData
+
+from titiler.core.algorithm.base import BaseAlgorithm
+
+
+class ToGrayScale(BaseAlgorithm):
+    """Transform a RGB Image to Grayscale."""
+
+    title: str = "Transform a RGB Image to Grayscale"
+    description: str = "Transform a RGB Image to Grayscale using the ITU-R 601-2 luma."
+
+    # metadata
+    output_nbands: int = 1
+
+    def __call__(self, img: ImageData) -> ImageData:
+        """RGB to L."""
+        if img.count < 3:
+            raise ValueError(
+                f"Cannot apply `grayscale` algorithm on image with {img.count} bands."
+            )
+
+        arr = (
+            img.array[0] * 299 / 1000
+            + img.array[1] * 587 / 1000
+            + img.array[2] * 114 / 1000
+        )
+        return ImageData(
+            arr.astype(img.array.dtype),
+            assets=img.assets,
+            crs=img.crs,
+            band_names=["grayscale"],
+            bounds=img.bounds,
+            cutline_mask=img.cutline_mask,
+        )
+
+
+class ToBitonal(BaseAlgorithm):
+    """Transform an Image to Bitonal."""
+
+    title: str = "Transform an Image to Bitonal"
+    description: str = "All values larger than 127 are set to 255 (white), all other values to 0 (black)."
+
+    # metadata
+    output_nbands: int = 1
+    output_dtype: str = "uint8"
+
+    def __call__(self, img: ImageData) -> ImageData:
+        """Image to Bitonal"""
+        if img.count == 3:
+            # Convert to Grayscale
+            arr = (
+                img.array[0] * 299 / 1000
+                + img.array[1] * 587 / 1000
+                + img.array[2] * 114 / 1000
+            )
+        elif img.count == 1:
+            arr = img.array
+        else:
+            raise ValueError(
+                f"Cannot apply `bitonal` algorithm on image with {img.count} bands."
+            )
+
+        return ImageData(
+            numpy.ma.where(arr > 127, 255, 0).astype("uint8"),
+            assets=img.assets,
+            crs=img.crs,
+            bounds=img.bounds,
+            band_names=["bitonal"],
+            cutline_mask=img.cutline_mask,
+        )