added preview to Image

Author: readrawhex

dithertools/generators.py

@@ -227,17 +227,23 @@ def __init__(
                 f"source must be Image, Video, or a file path,"
                 f" got {type(source).__name__!r}"
             )
+        self._crop_position: tuple[int, int] | None = None
+        self._crop_size: tuple[int, int] | None = None
 
     @property
     def width(self) -> int:
-        """Frame width in pixels."""
+        """Frame width in pixels (after any configured crop)."""
+        if self._crop_size is not None:
+            return self._crop_size[0]
         if self._source_type == "video":
             return self._video.width  # type: ignore[union-attr]
         return self._buffer.shape[1]  # type: ignore[index]
 
     @property
     def height(self) -> int:
-        """Frame height in pixels."""
+        """Frame height in pixels (after any configured crop)."""
+        if self._crop_size is not None:
+            return self._crop_size[1]
         if self._source_type == "video":
             return self._video.height  # type: ignore[union-attr]
         return self._buffer.shape[0]  # type: ignore[index]
@@ -265,6 +271,47 @@ def reset(self) -> None:
         elif self._source_type == "video" and self._video is not None:
             iter(self._video)
 
+    def crop(
+        self, position: tuple[int, int], size: tuple[int, int]
+    ) -> "FrameGenerator":
+        """Configure each yielded frame to be cropped to the region defined by
+        *position* and *size*.
+
+        The user-supplied ``fn`` still receives the full-size frame buffer; the
+        crop is applied to the output just before the frame is returned.
+        Validation is performed against the source frame dimensions.
+
+        Args:
+            position: ``(x, y)`` pixel coordinates of the crop region's top-left corner.
+            size: ``(width, height)`` of the crop region in pixels.
+
+        Returns:
+            ``self``, to allow method chaining.
+
+        Raises:
+            ValueError: If the crop region extends outside the source frame boundaries.
+        """
+        x, y = position
+        w, h = size
+        src_w = (
+            self._buffer.shape[1]  # type: ignore[union-attr]
+            if self._source_type == "image"
+            else self._video.width  # type: ignore[union-attr]
+        )
+        src_h = (
+            self._buffer.shape[0]  # type: ignore[union-attr]
+            if self._source_type == "image"
+            else self._video.height  # type: ignore[union-attr]
+        )
+        if x < 0 or y < 0 or x + w > src_w or y + h > src_h:
+            raise ValueError(
+                f"crop region ({x}, {y}, {w}×{h}) out of bounds for "
+                f"{src_w}×{src_h} frame"
+            )
+        self._crop_position = (x, y)
+        self._crop_size = (w, h)
+        return self
+
     def __iter__(self) -> "FrameGenerator":
         return self
 
@@ -273,15 +320,21 @@ def __next__(self) -> np.ndarray:
             if self._frame_idx > 0:
                 self._fn(self._buffer, self._frame_idx)
             self._frame_idx += 1
-            return self._buffer
-        frame = next(self._video)
-        if self._buffer is None:
-            self._buffer = frame.copy()
+            frame = self._buffer
         else:
-            self._buffer[:] = frame
-        self._fn(self._buffer, self._frame_idx)
-        self._frame_idx += 1
-        return self._buffer
+            raw = next(self._video)
+            if self._buffer is None:
+                self._buffer = raw.copy()
+            else:
+                self._buffer[:] = raw
+            self._fn(self._buffer, self._frame_idx)
+            self._frame_idx += 1
+            frame = self._buffer
+        if self._crop_position is not None:
+            cx, cy = self._crop_position
+            cw, ch = self._crop_size  # type: ignore[misc]
+            return frame[cy : cy + ch, cx : cx + cw]
+        return frame
 
     def to_video(
         self,
@@ -467,25 +520,30 @@ def __getitem__(self, key: "int | slice") -> "np.ndarray | FrameGenerator":
                 buf = self._original.copy()  # type: ignore[union-attr]
                 for idx in range(1, key + 1):
                     self._fn(buf, idx)
-                return buf.copy()
-
-            # video-backed: use a temporary sub-video so self._video is untouched
-            total = self._video.frame_count  # type: ignore[union-attr]
-            if key < 0:
-                key += total
-            if not 0 <= key < total:
-                raise IndexError(
-                    f"frame index {key} out of range for {total}-frame generator"
-                )
-            sub = self._video[0 : key + 1]  # type: ignore[union-attr]
-            buf = None
-            for idx, raw in enumerate(sub):
-                if buf is None:
-                    buf = raw.copy()
-                else:
-                    buf[:] = raw
-                self._fn(buf, idx)
-            return buf.copy()  # type: ignore[union-attr]
+                frame = buf
+            else:
+                # video-backed: use a temporary sub-video so self._video is untouched
+                total = self._video.frame_count  # type: ignore[union-attr]
+                if key < 0:
+                    key += total
+                if not 0 <= key < total:
+                    raise IndexError(
+                        f"frame index {key} out of range for {total}-frame generator"
+                    )
+                sub = self._video[0 : key + 1]  # type: ignore[union-attr]
+                buf = None
+                for idx, raw in enumerate(sub):
+                    if buf is None:
+                        buf = raw.copy()
+                    else:
+                        buf[:] = raw
+                    self._fn(buf, idx)
+                frame = buf  # type: ignore[assignment]
+            if self._crop_position is not None:
+                cx, cy = self._crop_position
+                cw, ch = self._crop_size  # type: ignore[misc]
+                return frame[cy : cy + ch, cx : cx + cw].copy()  # type: ignore[index]
+            return frame.copy()  # type: ignore[union-attr]
 
         if isinstance(key, slice):
             if self._source_type == "image":
@@ -499,13 +557,16 @@ def __getitem__(self, key: "int | slice") -> "np.ndarray | FrameGenerator":
                     raise IndexError("slice selects no frames")
                 fps = _DEFAULT_FPS
                 src_frames = [self._original.copy() for _ in indices]  # type: ignore[union-attr]
-                return FrameGenerator(Video.from_frames(src_frames, fps), self._fn)
-
-            # video-backed: slice the raw source and let fn run fresh
-            raw_sub = self._video[key]  # type: ignore[union-attr]
-            if not isinstance(raw_sub, Video):
-                raise IndexError("slice selects no frames")
-            return FrameGenerator(raw_sub, self._fn)
+                result = FrameGenerator(Video.from_frames(src_frames, fps), self._fn)
+            else:
+                # video-backed: slice the raw source and let fn run fresh
+                raw_sub = self._video[key]  # type: ignore[union-attr]
+                if not isinstance(raw_sub, Video):
+                    raise IndexError("slice selects no frames")
+                result = FrameGenerator(raw_sub, self._fn)
+            result._crop_position = self._crop_position
+            result._crop_size = self._crop_size
+            return result
 
         raise TypeError(
             f"indices must be integers or slices, not {type(key).__name__!r}"

dithertools/image.py

@@ -77,6 +77,21 @@ def from_array(cls, data: np.ndarray) -> "Image":
         img.width = img.data.shape[1]
         return img
 
+    @classmethod
+    def solid(cls, width: int, height: int, color: tuple[int, int, int]) -> "Image":
+        """Create an ``Image`` filled entirely with a single color.
+
+        Args:
+            width: Image width in pixels.
+            height: Image height in pixels.
+            color: Fill color as an ``(R, G, B)`` tuple (0–255 per channel).
+
+        Returns:
+            A new ``Image`` with every pixel set to *color*.
+        """
+        data = np.full((height, width, 3), color, dtype=np.uint8)
+        return cls.from_array(data)
+
     def resize(self, width: int, height: int) -> "Image":
         """Return a new ``Image`` resized to ``(width, height)``
         using Lanczos resampling.
@@ -115,6 +130,105 @@ def resize_nearest(self, width: int, height: int) -> "Image":
         )
         return Image.from_array(resized)
 
+    def crop(self, position: tuple[int, int], size: tuple[int, int]) -> "Image":
+        """Return a new ``Image`` cropped to the region defined by *position* and
+        *size*.
+
+        The original instance is not modified.
+
+        Args:
+            position: ``(x, y)`` pixel coordinates of the crop region's top-left corner.
+            size: ``(width, height)`` of the crop region in pixels.
+
+        Returns:
+            A new ``Image`` containing only the cropped pixel data.
+
+        Raises:
+            ValueError: If the crop region extends outside the image boundaries.
+        """
+        x, y = position
+        w, h = size
+        if x < 0 or y < 0 or x + w > self.width or y + h > self.height:
+            raise ValueError(
+                f"crop region ({x}, {y}, {w}×{h}) out of bounds for "
+                f"{self.width}×{self.height} image"
+            )
+        return Image.from_array(self.data[y : y + h, x : x + w])
+
+    def overlay(
+        self,
+        other: "Image",
+        pos: tuple[int, int],
+        size: tuple[int, int],
+        blend: str = "replace",
+    ) -> "Image":
+        """Return a new ``Image`` with *other* composited at *pos*.
+
+        *other* is resized to *size* (Lanczos) before placement.  Portions
+        that fall outside the base image's bounds are clipped silently.
+
+        Args:
+            other: The image to overlay.
+            pos: ``(x, y)`` pixel coordinates of the overlay's top-left corner.
+            size: ``(width, height)`` — *other* is resized to these dimensions
+                before placement.
+            blend: Compositing mode.  ``"replace"`` (default) writes overlay
+                pixels directly over the base.  Other modes: ``"multiply"``,
+                ``"screen"``, ``"add"``, ``"difference"``.
+
+        Returns:
+            A new ``Image`` with the overlay applied.  The original is not
+            modified.
+
+        Raises:
+            ValueError: If *blend* is not a recognised mode.
+        """
+        _MODES = {"replace", "multiply", "screen", "add", "difference"}
+        if blend not in _MODES:
+            raise ValueError(f"blend must be one of {sorted(_MODES)!r}, got {blend!r}")
+
+        x, y = pos
+        ow, oh = size
+
+        ov_data = other.resize(ow, oh).data
+
+        # Normalise overlay channels to match base
+        base_mode = _PILImage.fromarray(self.data).mode
+        ov_pil = _PILImage.fromarray(ov_data)
+        if ov_pil.mode != base_mode:
+            ov_data = np.array(ov_pil.convert(base_mode))
+
+        dst_x0 = max(x, 0)
+        dst_y0 = max(y, 0)
+        dst_x1 = min(x + ow, self.width)
+        dst_y1 = min(y + oh, self.height)
+
+        out = self.data.copy()
+        if dst_x0 >= dst_x1 or dst_y0 >= dst_y1:
+            return Image.from_array(out)
+
+        src_x0 = dst_x0 - x
+        src_y0 = dst_y0 - y
+        src_x1 = src_x0 + (dst_x1 - dst_x0)
+        src_y1 = src_y0 + (dst_y1 - dst_y0)
+
+        base_reg = out[dst_y0:dst_y1, dst_x0:dst_x1].astype(np.float32)
+        ov_reg = ov_data[src_y0:src_y1, src_x0:src_x1].astype(np.float32)
+
+        if blend == "replace":
+            blended = ov_reg
+        elif blend == "multiply":
+            blended = base_reg * ov_reg / 255.0
+        elif blend == "screen":
+            blended = 255.0 - (255.0 - base_reg) * (255.0 - ov_reg) / 255.0
+        elif blend == "add":
+            blended = base_reg + ov_reg
+        else:  # difference
+            blended = np.abs(base_reg - ov_reg)
+
+        out[dst_y0:dst_y1, dst_x0:dst_x1] = np.clip(blended, 0, 255).astype(np.uint8)
+        return Image.from_array(out)
+
     def save(self, filepath: str | Path) -> None:
         """Save pixel data to disk.
 
@@ -140,6 +254,52 @@ def to_palette(self, colors: int = 8) -> list[tuple[int, int, int]]:
         raw = quantized.getpalette()
         return [tuple(raw[i * 3 : (i + 1) * 3]) for i in range(colors)]
 
+    def preview(self) -> None:
+        """Open the image in an external viewer for preview.
+
+        ``ffplay`` (part of the FFmpeg suite) is tried first because it
+        blocks until the window is closed.  If ``ffplay`` is not found on
+        ``PATH``, the image is opened with the system default viewer and a
+        :class:`UserWarning` is issued, as that opener returns immediately
+        rather than waiting for the window to close.
+        """
+        import atexit
+        import os
+        import platform
+        import subprocess
+        import tempfile
+        import warnings
+
+        fd, name = tempfile.mkstemp(suffix=".png")
+        os.close(fd)
+        tmp = Path(name)
+        atexit.register(lambda: tmp.unlink(missing_ok=True))
+
+        self.save(tmp)
+
+        try:
+            subprocess.run(
+                ["ffplay", str(tmp)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            return
+        except FileNotFoundError:
+            pass
+
+        warnings.warn(
+            "ffplay not found; opening with system default viewer "
+            "(the call will return before the window is closed)",
+            stacklevel=2,
+        )
+        system = platform.system()
+        if system == "Darwin":
+            subprocess.run(["open", "-W", str(tmp)])
+        elif system == "Windows":
+            subprocess.run(["cmd", "/c", "start", "/wait", "", str(tmp)])
+        else:
+            subprocess.run(["xdg-open", str(tmp)])
+
     def __mul__(self, n: int | float) -> "object":
         """Return a Video consisting of *n* identical copies of this image.