prezo 0.3.1__py3-none-any.whl

prezo/images/__init__.py

@@ -0,0 +1,14 @@
+"""Image rendering for Prezo."""
+
+from __future__ import annotations
+
+from .base import ImageRenderer, get_renderer
+from .processor import process_slide_images, render_image, resolve_image_path
+
+__all__ = [
+    "ImageRenderer",
+    "get_renderer",
+    "process_slide_images",
+    "render_image",
+    "resolve_image_path",
+]

prezo/images/ascii.py

@@ -0,0 +1,240 @@
+"""ASCII art image renderer."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+# ASCII characters from dark to light
+ASCII_CHARS = " .:-=+*#%@"
+ASCII_CHARS_DETAILED = (
+    " .'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$"
+)
+
+
+class AsciiRenderer:
+    """Render images as ASCII art."""
+
+    def __init__(self, detailed: bool = False) -> None:
+        """Initialize ASCII renderer.
+
+        Args:
+            detailed: Use detailed character set for more gradients.
+
+        """
+        self.chars = ASCII_CHARS_DETAILED if detailed else ASCII_CHARS
+
+    @property
+    def name(self) -> str:
+        """Get the renderer name."""
+        return "ascii"
+
+    def supports_inline(self) -> bool:
+        """ASCII art supports inline display."""
+        return True
+
+    def render(self, path: Path, width: int, height: int) -> str:
+        """Render an image as ASCII art.
+
+        Args:
+            path: Path to the image file.
+            width: Target width in characters.
+            height: Target height in lines.
+
+        Returns:
+            ASCII art string representation.
+
+        """
+        try:
+            return self._render_image(path, width, height)
+        except Exception:
+            return self._render_placeholder(path, width, height)
+
+    def _render_image(self, path: Path, width: int, height: int) -> str:
+        """Render image using PIL."""
+        from PIL import Image
+
+        img = Image.open(path)
+
+        # Convert to grayscale
+        img = img.convert("L")
+
+        # Calculate aspect ratio correction
+        # Terminal characters are typically ~2x taller than wide
+        aspect_ratio = img.width / img.height
+        new_width = min(width, int(height * 2 * aspect_ratio))
+        new_height = min(height, int(new_width / aspect_ratio / 2))
+
+        # Resize
+        img = img.resize((new_width, new_height))
+
+        # Convert to ASCII
+        pixels = list(img.getdata())
+        lines = []
+
+        for y in range(new_height):
+            line = ""
+            for x in range(new_width):
+                pixel = pixels[y * new_width + x]
+                # Map pixel value (0-255) to character
+                char_idx = int(pixel / 256 * len(self.chars))
+                char_idx = min(char_idx, len(self.chars) - 1)
+                line += self.chars[char_idx]
+            lines.append(line)
+
+        return "\n".join(lines)
+
+    def _render_placeholder(self, path: Path, width: int, height: int) -> str:
+        """Render a placeholder when image can't be loaded."""
+        name = (
+            path.name if len(path.name) < width - 4 else path.name[: width - 7] + "..."
+        )
+        box_width = max(len(name) + 4, 20)
+        box_width = min(box_width, width)
+
+        lines = []
+        lines.append("┌" + "─" * (box_width - 2) + "┐")
+        lines.append("│" + " " * (box_width - 2) + "│")
+        lines.append("│" + f"[Image: {name}]".center(box_width - 2) + "│")
+        lines.append("│" + " " * (box_width - 2) + "│")
+        lines.append("└" + "─" * (box_width - 2) + "┘")
+
+        return "\n".join(lines)
+
+
+class ColorAsciiRenderer(AsciiRenderer):
+    """Render images as colored ASCII art using ANSI colors."""
+
+    @property
+    def name(self) -> str:
+        """Get the renderer name."""
+        return "ascii-color"
+
+    def _render_image(self, path: Path, width: int, height: int) -> str:
+        """Render image as colored ASCII."""
+        from PIL import Image
+
+        img = Image.open(path)
+
+        # Keep color, convert to RGB
+        img = img.convert("RGB")
+
+        # Calculate aspect ratio correction
+        aspect_ratio = img.width / img.height
+        new_width = min(width, int(height * 2 * aspect_ratio))
+        new_height = min(height, int(new_width / aspect_ratio / 2))
+
+        # Resize
+        img = img.resize((new_width, new_height))
+
+        # Convert to colored ASCII
+        pixels = list(img.getdata())
+        lines = []
+
+        for y in range(new_height):
+            line = ""
+            for x in range(new_width):
+                r, g, b = pixels[y * new_width + x]
+                # Use half-block character with true color
+                line += f"\x1b[38;2;{r};{g};{b}m█\x1b[0m"
+            lines.append(line)
+
+        return "\n".join(lines)
+
+
+class HalfBlockRenderer:
+    """Render images using Unicode half-block characters for higher resolution."""
+
+    @property
+    def name(self) -> str:
+        """Get the renderer name."""
+        return "halfblock"
+
+    def supports_inline(self) -> bool:
+        """Half-block supports inline display."""
+        return True
+
+    def render(self, path: Path, width: int, height: int) -> str:
+        """Render image using half-block characters.
+
+        Each character cell displays 2 vertical pixels using the upper
+        half block character (▀) with foreground and background colors.
+
+        Args:
+            path: Path to the image file.
+            width: Target width in characters.
+            height: Target height in lines.
+
+        Returns:
+            Colored half-block string representation.
+
+        """
+        try:
+            return self._render_image(path, width, height)
+        except Exception:
+            return AsciiRenderer()._render_placeholder(path, width, height)
+
+    def _render_image(self, path: Path, width: int, height: int) -> str:
+        """Render image using half-blocks."""
+        from PIL import Image
+
+        img = Image.open(path)
+        img = img.convert("RGB")
+
+        # Calculate dimensions (height is doubled because of half-blocks)
+        aspect_ratio = img.width / img.height
+        new_width = min(width, int(height * 2 * aspect_ratio))
+        # Height in pixels (2 pixels per character row)
+        new_height = min(height * 2, int(new_width / aspect_ratio))
+        # Make height even
+        new_height = new_height - (new_height % 2)
+
+        img = img.resize((new_width, new_height))
+        pixels = list(img.getdata())
+
+        lines = []
+        for y in range(0, new_height, 2):
+            line = ""
+            for x in range(new_width):
+                # Upper pixel
+                r1, g1, b1 = pixels[y * new_width + x]
+                # Lower pixel (or black if at edge)
+                if y + 1 < new_height:
+                    r2, g2, b2 = pixels[(y + 1) * new_width + x]
+                else:
+                    r2, g2, b2 = 0, 0, 0
+
+                # Upper half block: foreground = top, background = bottom
+                line += f"\x1b[38;2;{r1};{g1};{b1};48;2;{r2};{g2};{b2}m▀\x1b[0m"
+            lines.append(line)
+
+        return "\n".join(lines)
+
+
+@lru_cache(maxsize=32)
+def render_cached(
+    renderer_name: str,
+    path: str,
+    width: int,
+    height: int,
+) -> str:
+    """Render an image with caching.
+
+    Args:
+        renderer_name: Name of the renderer to use.
+        path: Path to the image file.
+        width: Target width.
+        height: Target height.
+
+    Returns:
+        Rendered image string.
+
+    """
+    renderers = {
+        "ascii": AsciiRenderer,
+        "ascii-color": ColorAsciiRenderer,
+        "halfblock": HalfBlockRenderer,
+    }
+    renderer_cls = renderers.get(renderer_name, AsciiRenderer)
+    renderer = renderer_cls()
+    return renderer.render(Path(path), width, height)

prezo/images/base.py

@@ -0,0 +1,111 @@
+"""Base image renderer protocol and factory."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from prezo.config import get_config
+from prezo.terminal import ImageCapability, detect_image_capability
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ImageRenderer(Protocol):
+    """Protocol for image renderers."""
+
+    def render(self, path: Path, width: int, height: int) -> str:
+        """Render an image to a string representation.
+
+        Args:
+            path: Path to the image file.
+            width: Target width in characters.
+            height: Target height in lines.
+
+        Returns:
+            String representation of the image for terminal display.
+
+        """
+        ...
+
+    def supports_inline(self) -> bool:
+        """Check if renderer supports inline display with text.
+
+        Returns:
+            True if images can be displayed inline.
+
+        """
+        ...
+
+    @property
+    def name(self) -> str:
+        """Get the renderer name."""
+        ...
+
+
+class NullRenderer:
+    """Null renderer that produces no output."""
+
+    @property
+    def name(self) -> str:
+        """Get the renderer name."""
+        return "none"
+
+    def render(self, path: Path, width: int, height: int) -> str:
+        """Return empty string (no rendering)."""
+        return ""
+
+    def supports_inline(self) -> bool:
+        """Null renderer doesn't support inline."""
+        return False
+
+
+def get_renderer(mode: str | None = None) -> ImageRenderer:
+    """Get an image renderer based on mode or auto-detection.
+
+    Args:
+        mode: Explicit mode ('auto', 'kitty', 'sixel', 'iterm', 'ascii', 'none').
+              If None, uses config setting.
+
+    Returns:
+        An image renderer instance.
+
+    """
+    if mode is None:
+        mode = get_config().images.mode
+
+    if mode == "none":
+        return NullRenderer()
+
+    if mode == "auto":
+        capability = detect_image_capability()
+    else:
+        # Map mode string to capability
+        mode_map = {
+            "kitty": ImageCapability.KITTY,
+            "sixel": ImageCapability.SIXEL,
+            "iterm": ImageCapability.ITERM,
+            "ascii": ImageCapability.ASCII,
+        }
+        capability = mode_map.get(mode, ImageCapability.ASCII)
+
+    # Return appropriate renderer
+    if capability == ImageCapability.KITTY:
+        from .kitty import KittyRenderer
+
+        return KittyRenderer()
+
+    if capability == ImageCapability.ITERM:
+        from .iterm import ItermRenderer
+
+        return ItermRenderer()
+
+    if capability == ImageCapability.SIXEL:
+        from .sixel import SixelRenderer
+
+        return SixelRenderer()
+
+    # Default to ASCII
+    from .ascii import AsciiRenderer
+
+    return AsciiRenderer()

prezo/images/chafa.py

@@ -0,0 +1,137 @@
+"""Chafa-based image renderer for high-quality terminal graphics."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def chafa_available() -> bool:
+    """Check if chafa is installed."""
+    return shutil.which("chafa") is not None
+
+
+def render_with_chafa(
+    path: Path,
+    width: int,
+    height: int,
+    *,
+    symbols: str = "block+border+space",
+    colors: str = "full",
+) -> str | None:
+    """Render an image using chafa.
+
+    Args:
+        path: Path to the image file.
+        width: Target width in characters.
+        height: Target height in lines.
+        symbols: Symbol set to use (block, border, space, ascii, etc.).
+        colors: Color mode (full, 256, 16, 8, 2, none).
+
+    Returns:
+        Rendered image as ANSI string, or None if chafa not available.
+
+    """
+    if not chafa_available():
+        return None
+
+    if not path.exists():
+        return None
+
+    chafa_path = shutil.which("chafa")
+    if not chafa_path:
+        return None
+
+    try:
+        result = subprocess.run(
+            [
+                chafa_path,
+                "--size",
+                f"{width}x{height}",
+                "--format",
+                "symbols",  # Force symbols, not native protocols
+                "--symbols",
+                symbols,
+                "--colors",
+                colors,
+                "--color-space",
+                "rgb",
+                "--dither",
+                "ordered",
+                "--work",
+                "9",  # Maximum quality
+                str(path),
+            ],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            return result.stdout
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError):
+        pass
+
+    return None
+
+
+class ChafaRenderer:
+    """Render images using chafa for high-quality terminal graphics."""
+
+    def __init__(self) -> None:
+        """Initialize the chafa renderer."""
+        self._available = chafa_available()
+
+    @property
+    def name(self) -> str:
+        """Get the renderer name."""
+        return "chafa"
+
+    @property
+    def available(self) -> bool:
+        """Check if chafa is available."""
+        return self._available
+
+    def supports_inline(self) -> bool:
+        """Chafa supports inline display."""
+        return True
+
+    def render(self, path: Path, width: int, height: int) -> str:
+        """Render an image using chafa.
+
+        Args:
+            path: Path to the image file.
+            width: Target width in characters.
+            height: Target height in lines.
+
+        Returns:
+            Rendered image as ANSI string.
+
+        """
+        result = render_with_chafa(path, width, height)
+        if result:
+            return result
+
+        # Fall back to placeholder if chafa fails
+        return self._render_placeholder(path, width, height)
+
+    def _render_placeholder(self, path: Path, width: int, height: int) -> str:
+        """Render a placeholder when image can't be loaded."""
+        name = (
+            path.name if len(path.name) < width - 4 else path.name[: width - 7] + "..."
+        )
+        box_width = max(len(name) + 4, 20)
+        box_width = min(box_width, width)
+
+        lines = []
+        lines.append("┌" + "─" * (box_width - 2) + "┐")
+        lines.append("│" + " " * (box_width - 2) + "│")
+        lines.append("│" + f"[Image: {name}]".center(box_width - 2) + "│")
+        lines.append("│" + " " * (box_width - 2) + "│")
+        lines.append("└" + "─" * (box_width - 2) + "┘")
+
+        return "\n".join(lines)

prezo/images/iterm.py

@@ -0,0 +1,126 @@
+"""iTerm2 image renderer using inline images protocol."""
+
+from __future__ import annotations
+
+import base64
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ItermRenderer:
+    """Render images using iTerm2's inline images protocol."""
+
+    @property
+    def name(self) -> str:
+        """Get the renderer name."""
+        return "iterm"
+
+    def supports_inline(self) -> bool:
+        """iTerm2 supports inline images."""
+        return True
+
+    def render(self, path: Path, width: int, height: int) -> str:
+        """Render an image using iTerm2 inline images protocol.
+
+        Args:
+            path: Path to the image file.
+            width: Target width in characters.
+            height: Target height in lines.
+
+        Returns:
+            Escape sequence string to display the image.
+
+        """
+        try:
+            return self._render_image(path, width, height)
+        except Exception:
+            from .ascii import AsciiRenderer
+
+            return AsciiRenderer()._render_placeholder(path, width, height)
+
+    def _render_image(self, path: Path, width: int, height: int) -> str:
+        """Render image using iTerm2 protocol."""
+        # Read and encode image
+        image_data = path.read_bytes()
+        encoded = base64.b64encode(image_data).decode("ascii")
+
+        # Get file name for the name parameter
+        name = base64.b64encode(path.name.encode()).decode("ascii")
+
+        # Build iTerm2 inline image escape sequence
+        # Format: \x1b]1337;File=name=<b64name>;size=<bytes>;width=<w>;height=<h>;inline=1:<b64data>\x07
+        #
+        # name: base64 encoded filename
+        # size: file size in bytes
+        # width: width (can be pixels, cells, percent, or auto)
+        # height: height (same options)
+        # inline: 1 = display inline, 0 = download
+        # preserveAspectRatio: 1 = preserve, 0 = stretch
+
+        params = [
+            f"name={name}",
+            f"size={len(image_data)}",
+            f"width={width}",
+            f"height={height}",
+            "inline=1",
+            "preserveAspectRatio=1",
+        ]
+
+        param_str = ";".join(params)
+        return f"\x1b]1337;File={param_str}:{encoded}\x07"
+
+    def render_with_options(
+        self,
+        path: Path,
+        *,
+        width: str = "auto",
+        height: str = "auto",
+        preserve_aspect: bool = True,
+    ) -> str:
+        """Render image with more control over sizing.
+
+        Args:
+            path: Path to the image file.
+            width: Width specification (e.g., "80", "50%", "auto", "80px").
+            height: Height specification.
+            preserve_aspect: Whether to preserve aspect ratio.
+
+        Returns:
+            Escape sequence string.
+
+        """
+        image_data = path.read_bytes()
+        encoded = base64.b64encode(image_data).decode("ascii")
+        name = base64.b64encode(path.name.encode()).decode("ascii")
+
+        params = [
+            f"name={name}",
+            f"size={len(image_data)}",
+            f"width={width}",
+            f"height={height}",
+            "inline=1",
+            f"preserveAspectRatio={1 if preserve_aspect else 0}",
+        ]
+
+        param_str = ";".join(params)
+        return f"\x1b]1337;File={param_str}:{encoded}\x07"
+
+
+def write_image_to_terminal(path: Path, width: int = 80, height: int = 24) -> None:
+    """Write an image directly to the terminal.
+
+    Utility function for direct terminal output.
+
+    Args:
+        path: Path to the image file.
+        width: Target width in cells.
+        height: Target height in cells.
+
+    """
+    renderer = ItermRenderer()
+    output = renderer.render(path, width, height)
+    sys.stdout.write(output)
+    sys.stdout.flush()