reconfigured sphinx to use markdown, removed threshold from composite and composite_color

Author: readrawhex

.github/workflows/docs.yml

@@ -6,8 +6,6 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 jobs:
   build:
@@ -18,17 +16,4 @@ jobs:
         with:
           python-version: "3.12"
       - run: pip install -e ".[docs]"
-      - run: sphinx-build -b html docs/ public/
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: public/
-
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - uses: actions/deploy-pages@v4
-        id: deployment
+      - run: sphinx-build -b markdown docs/ public/

dithertools/dither.py

@@ -1,8 +1,8 @@
-"""Layer compositing using dithered threshold masks.
+"""Layer compositing using dithered masks compared against layer pixel values.
 
 The :func:`composite` function blends a top layer over a bottom layer pixel
-by pixel: where the mask value exceeds ``threshold``, the top layer shows
-through; everywhere else the bottom layer is visible.
+by pixel: where the top pixel's brightness exceeds the mask value, the top
+layer shows through; everywhere else the bottom layer is visible.
 
 When both layers are ``Image`` instances, the result is a new ``Image``.
 When either layer is a ``Video``, all composited frames are collected eagerly
@@ -27,10 +27,19 @@ def _blend(
     top: np.ndarray,
     bottom: np.ndarray,
     mask: np.ndarray,
-    threshold: int,
 ) -> np.ndarray:
-    """Return a frame with top pixels where mask > threshold, else bottom pixels."""
-    cond = mask > threshold
+    """Return a frame with top pixels where top brightness > mask, else bottom 
+    pixels.
+    """
+    if top.ndim == 3:
+        brightness = (
+            0.299 * top[:, :, 0].astype(np.float32)
+            + 0.587 * top[:, :, 1].astype(np.float32)
+            + 0.114 * top[:, :, 2].astype(np.float32)
+        )
+    else:
+        brightness = top.astype(np.float32)
+    cond = brightness > mask.astype(np.float32)
     if top.ndim == 3:
         cond = cond[:, :, np.newaxis]
     return np.where(cond, top, bottom).astype(np.uint8)
@@ -40,50 +49,51 @@ def _blend_color(
     top: np.ndarray,
     bottom: np.ndarray,
     mask: np.ndarray,
-    threshold: int,
 ) -> np.ndarray:
-    """Return a frame with per-channel blending: each channel replaced where its mask > threshold."""
-    return np.where(mask > threshold, top, bottom).astype(np.uint8)
+    """Return a frame with per-channel blending: each channel replaced where 
+    top channel > mask channel.
+    """
+    return np.where(top > mask, top, bottom).astype(np.uint8)
 
 
 def composite(
     top: "Image | Video",
     bottom: "Image | Video",
     mask: np.ndarray | None = None,
-    threshold: int = 127,
     tile_every_x: int | None = 8,
     tile_every_y: int | None = 8,
     repeat_every_x: int | None = 1,
     repeat_every_y: int | None = 1,
 ) -> "Image | Video":
-    """Composite a top layer over a bottom layer using a dithered threshold mask.
+    """Composite a top layer over a bottom layer using a dithered mask.
 
-    For every pixel, the top layer is used where ``mask > threshold`` and the
-    bottom layer is used everywhere else.
+    For every pixel, the top layer is used where the top pixel's perceived
+    brightness (``0.299·R + 0.587·G + 0.114·B``) exceeds the corresponding
+    mask value; the bottom layer is used everywhere else.
 
     **Dimension matching** — the top layer is always resized to match the
     bottom layer's spatial dimensions. When both layers are ``Video``, the top
     is also temporally resampled to match the bottom's frame count.
 
     **Return type** — mirrors the bottom layer type:
 
-    - ``bottom`` is ``Image`` and ``top`` is ``Image`` → new :class:`~dithertools.image.Image`.
+    - ``bottom`` is ``Image`` and ``top`` is ``Image`` →
+      new :class:`~dithertools.image.Image`.
     - ``bottom`` is ``Video`` → new :class:`~dithertools.video.Video` (memory-backed).
-    - ``bottom`` is ``Image`` and ``top`` is ``Video`` → new :class:`~dithertools.video.Video`
+    - ``bottom`` is ``Image`` and ``top`` is ``Video`` →
+      new :class:`~dithertools.video.Video`
       (memory-backed); the bottom image is repeated for every frame of the top video.
 
     Args:
-        top: The foreground layer. Shown where ``mask > threshold``.
+        top: The foreground layer. Shown where its brightness exceeds the mask.
         bottom: The background layer. Determines output dimensions and,
             when a ``Video``, the output frame count.
-        mask: A ``(height, width)`` ``uint8`` array of threshold values, such
-            as those returned by :func:`~dithertools.matrix.random_matrix`.
-            If ``None``, a fresh random mask is generated at the bottom
-            layer's dimensions. If the provided mask does not match the bottom
-            layer dimensions it is resized with nearest-neighbour interpolation.
-        threshold: Pixels in ``top`` replace pixels in ``bottom`` where the
-            corresponding mask value is strictly greater than this value.
-            Must be in ``[0, 255]``. Defaults to ``127``.
+        mask: A ``(height, width)`` ``uint8`` array of values against which
+            the top pixel brightness is compared, such as those returned by
+            :func:`~dithertools.matrix.random_matrix`. If ``None``, a fresh
+            random mask is generated at the bottom layer's dimensions. If the
+            provided mask does not match the bottom layer dimensions it is
+            resized with nearest-neighbour interpolation.
         tile_every_x: Tile width passed to :func:`~dithertools.matrix.random_matrix`
             when generating an auto mask (i.e. when ``mask`` is ``None``).
             The mask pattern repeats horizontally every this many columns.
@@ -144,15 +154,15 @@ def composite(
 
     if isinstance(bottom, Image) and isinstance(top, Image):
         return Image.from_array(
-            _blend(top.resize(w, h).data, bottom.data, mask, threshold)
+            _blend(top.resize(w, h).data, bottom.data, mask)
         )
 
     if isinstance(bottom, Video) and isinstance(top, Image):
         top_frame = top.resize(w, h).data
 
         def _image_over_video() -> Iterator[np.ndarray]:
             for bottom_frame in bottom:
-                yield _blend(top_frame, bottom_frame, mask, threshold)
+                yield _blend(top_frame, bottom_frame, mask)
 
         return Video.from_frames(_image_over_video(), fps=bottom.fps)
 
@@ -161,7 +171,7 @@ def _image_over_video() -> Iterator[np.ndarray]:
 
         def _video_over_video() -> Iterator[np.ndarray]:
             for bottom_frame, top_frame in zip(bottom, top):
-                yield _blend(top_frame, bottom_frame, mask, threshold)
+                yield _blend(top_frame, bottom_frame, mask)
 
         return Video.from_frames(_video_over_video(), fps=bottom.fps)
 
@@ -171,20 +181,20 @@ def _video_over_video() -> Iterator[np.ndarray]:
 
         def _video_over_image() -> Iterator[np.ndarray]:
             for top_frame in top:
-                yield _blend(top_frame, bottom_frame, mask, threshold)
+                yield _blend(top_frame, bottom_frame, mask)
 
         return Video.from_frames(_video_over_image(), fps=top.fps)
 
     raise TypeError(
-        f"Unsupported layer types: top={type(top).__name__}, bottom={type(bottom).__name__}"
+        f"Unsupported layer types: top={type(top).__name__},"
+        f" bottom={type(bottom).__name__}"
     )
 
 
 def composite_color(
     top: "Image | Video",
     bottom: "Image | Video",
     mask: np.ndarray | None = None,
-    threshold: int = 127,
     tile_every_x: int | None = 8,
     tile_every_y: int | None = 8,
     repeat_every_x: int | None = 1,
@@ -193,36 +203,35 @@ def composite_color(
     """Composite a top layer over a bottom layer with independent per-channel masking.
 
     Identical to :func:`composite` except that the mask is a three-channel
-    ``(height, width, 3)`` array and the threshold comparison is applied
-    separately to each colour channel. This means the red, green, and blue
-    components of each pixel can be replaced independently, producing chromatic
-    dithering effects that are not possible with a single-channel mask.
+    ``(height, width, 3)`` array and each channel of the top pixel is compared
+    directly against the corresponding mask channel. A top channel value replaces
+    the bottom wherever it strictly exceeds the mask channel value, producing
+    chromatic dithering effects not possible with a single-channel mask.
 
     **Dimension matching** — the top layer is always resized to match the
     bottom layer's spatial dimensions. When both layers are ``Video``, the top
     is also temporally resampled to match the bottom's frame count.
 
     **Return type** — mirrors the bottom layer type:
 
-    - ``bottom`` is ``Image`` and ``top`` is ``Image`` → new :class:`~dithertools.image.Image`.
+    - ``bottom`` is ``Image`` and ``top`` is ``Image`` →
+      new :class:`~dithertools.image.Image`.
     - ``bottom`` is ``Video`` → new :class:`~dithertools.video.Video` (memory-backed).
-    - ``bottom`` is ``Image`` and ``top`` is ``Video`` → new :class:`~dithertools.video.Video`
+    - ``bottom`` is ``Image`` and ``top`` is ``Video`` →
+      new :class:`~dithertools.video.Video`
       (memory-backed); the bottom image is repeated for every frame of the top video.
 
     Args:
-        top: The foreground layer. Each channel is shown where the
-            corresponding mask channel exceeds ``threshold``.
+        top: The foreground layer. Each channel is shown where that channel's
+            value exceeds the corresponding mask channel.
         bottom: The background layer. Determines output dimensions and,
             when a ``Video``, the output frame count.
-        mask: A ``(height, width, 3)`` ``uint8`` array of per-channel threshold
-            values, such as those returned by
-            :func:`~dithertools.matrix.random_matrix_color`. If ``None``, a
+        mask: A ``(height, width, 3)`` ``uint8`` array of per-channel values
+            against which the top channels are compared, such as those returned
+            by :func:`~dithertools.matrix.random_matrix_color`. If ``None``, a
             fresh random colour mask is generated at the bottom layer's
             dimensions. If the provided mask does not match the bottom layer
             dimensions it is resized with nearest-neighbour interpolation.
-        threshold: A channel value in ``top`` replaces the corresponding
-            channel in ``bottom`` where its mask channel is strictly greater
-            than this value. Must be in ``[0, 255]``. Defaults to ``127``.
         tile_every_x: Tile width passed to
             :func:`~dithertools.matrix.random_matrix_color` when generating an
             auto mask (i.e. when ``mask`` is ``None``). The mask pattern repeats
@@ -260,7 +269,9 @@ def composite_color(
 
         import numpy as np
         mask = np.random.randint(0, 256, (720, 1280, 3), dtype=np.uint8)
-        result = composite_color(top=Image("logo.png"), bottom=Video("clip.mp4"), mask=mask)
+        result = composite_color(
+            top=Image("logo.png"), bottom=Video("clip.mp4"), mask=mask
+        )
         result.save("out.mp4")
     """
     from dithertools.image import Image
@@ -288,15 +299,15 @@ def composite_color(
 
     if isinstance(bottom, Image) and isinstance(top, Image):
         return Image.from_array(
-            _blend_color(top.resize(w, h).data, bottom.data, mask, threshold)
+            _blend_color(top.resize(w, h).data, bottom.data, mask)
         )
 
     if isinstance(bottom, Video) and isinstance(top, Image):
         top_frame = top.resize(w, h).data
 
         def _image_over_video() -> Iterator[np.ndarray]:
             for bottom_frame in bottom:
-                yield _blend_color(top_frame, bottom_frame, mask, threshold)
+                yield _blend_color(top_frame, bottom_frame, mask)
 
         return Video.from_frames(_image_over_video(), fps=bottom.fps)
 
@@ -305,7 +316,7 @@ def _image_over_video() -> Iterator[np.ndarray]:
 
         def _video_over_video() -> Iterator[np.ndarray]:
             for bottom_frame, top_frame in zip(bottom, top):
-                yield _blend_color(top_frame, bottom_frame, mask, threshold)
+                yield _blend_color(top_frame, bottom_frame, mask)
 
         return Video.from_frames(_video_over_video(), fps=bottom.fps)
 
@@ -315,10 +326,11 @@ def _video_over_video() -> Iterator[np.ndarray]:
 
         def _video_over_image() -> Iterator[np.ndarray]:
             for top_frame in top:
-                yield _blend_color(top_frame, bottom_frame, mask, threshold)
+                yield _blend_color(top_frame, bottom_frame, mask)
 
         return Video.from_frames(_video_over_image(), fps=top.fps)
 
     raise TypeError(
-        f"Unsupported layer types: top={type(top).__name__}, bottom={type(bottom).__name__}"
+        f"Unsupported layer types: top={type(top).__name__},"
+        f" bottom={type(bottom).__name__}"
     )

dithertools/image.py

@@ -78,7 +78,8 @@ def from_array(cls, data: np.ndarray) -> "Image":
         return img
 
     def resize(self, width: int, height: int) -> "Image":
-        """Return a new ``Image`` resized to ``(width, height)`` using Lanczos resampling.
+        """Return a new ``Image`` resized to ``(width, height)``
+        using Lanczos resampling.
 
         The original instance is not modified.
 
@@ -95,7 +96,8 @@ def resize(self, width: int, height: int) -> "Image":
         return Image.from_array(resized)
 
     def resize_nearest(self, width: int, height: int) -> "Image":
-        """Return a new ``Image`` resized to ``(width, height)`` using nearest-neighbour resampling.
+        """Return a new ``Image`` resized to ``(width, height)``
+        using nearest-neighbour resampling.
 
         Nearest-neighbour preserves hard pixel edges, making it suitable for
         pixel art or any case where interpolation between values is undesirable.
@@ -125,4 +127,7 @@ def save(self, filepath: str | Path) -> None:
         _PILImage.fromarray(self.data).save(Path(filepath))
 
     def __repr__(self) -> str:
-        return f"Image(path={self.filepath.name!r}, width={self.width}, height={self.height})"
+        return (
+            f"Image(path={self.filepath.name!r},"
+            f" width={self.width}, height={self.height})"
+        )

dithertools/io.py

@@ -8,7 +8,8 @@
 
 
 def load(filepath: str | Path) -> Image | Video:
-    """Load a file as an :class:`~dithertools.image.Image` or :class:`~dithertools.video.Video`.
+    """Load a file as an :class:`~dithertools.image.Image`
+    or :class:`~dithertools.video.Video`.
 
     The type is determined by the MIME type inferred from the file extension.
     Any path whose MIME type starts with ``video/`` is opened as a ``Video``;

dithertools/matrix.py

@@ -1,4 +1,5 @@
-"""Functions for generating 2D NumPy arrays used as dithering masks throughout the library.
+"""Functions for generating 2D NumPy arrays used as dithering masks
+throughout the library.
 
 All matrices follow the NumPy image convention: shape is (height, width) for grayscale
 and (height, width, 3) for color.

docs/conf.py

@@ -5,6 +5,7 @@
 
 extensions = [
     "autoapi.extension",
+    "sphinx-markdown-builder",
 ]
 
 autoapi_dirs = ["../dithertools"]

main.py

@@ -4,7 +4,7 @@
 
 
 def _default_output(layers) -> str:
-    return "output.mp4" if any(isinstance(l, Video) for l in layers) else "output.png"
+    return "output.mp4" if any(isinstance(v, Video) for v in layers) else "output.png"
 
 
 @click.command()
@@ -16,11 +16,8 @@ def _default_output(layers) -> str:
     help="Output file path (default: output.png or output.mp4).",
 )
 @click.option("-c", "--color", is_flag=True, help="Use per-channel color compositing.")
-@click.option(
-    "--threshold", default=127, show_default=True, help="Composite threshold (0–255)."
-)
 def main(
-    files: tuple[str, ...], output: str | None, color: bool, threshold: int
+    files: tuple[str, ...], output: str | None, color: bool
 ) -> None:
     """Composite a list of image/video files dithered on top of each other.
 
@@ -42,7 +39,7 @@ def main(
 
     result = layers[0]
     for layer in layers[1:]:
-        result = fn(top=layer, bottom=result, threshold=threshold)  # type: ignore[arg-type]
+        result = fn(top=layer, bottom=result)  # type: ignore[arg-type]
 
     result.save(output)
     click.echo(f"Saved to {output}")

pyproject.toml

@@ -21,12 +21,11 @@ dependencies = [
 dev = [
     "pytest>=8.0",
     "ruff>=0.4",
-    "black>=24.0",
 ]
 docs = [
     "sphinx>=7.0",
     "sphinx-autoapi>=3.0",
-    "sphinx-rtd-theme>=2.0",
+    "sphinx-markdown-builder==0.6.10",
 ]
 
 [project.scripts]