textual-image 0.5.0__py3-none-any.whl

textual_image/__init__.py

@@ -0,0 +1,4 @@
+"""Package to render images in Rich and Textual.
+
+Provides Rich Renderables and a Textual Widget to render images in the terminal.
+"""

textual_image/__main__.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python
+
+"""Run the textual_image demo."""
+
+import sys
+from argparse import ArgumentParser
+from importlib.util import find_spec
+
+from textual_image.demo.renderable import RENDERING_METHODS
+
+textual_available = bool(find_spec("textual"))
+default_mode = "rich" if find_spec("textual") is None else "textual"
+
+parser = ArgumentParser(description="Demo the capabilities of textual-image")
+parser.add_argument("mode", choices=["rich", "textual"], nargs="?", default=default_mode)
+parser.add_argument("-m", "--method", choices=RENDERING_METHODS.keys(), default="auto")
+arguments = parser.parse_args()
+
+if arguments.mode == "rich":
+    from textual_image.demo.renderable import run as run_rich_demo
+
+    run_rich_demo(arguments.method)
+elif not textual_available:
+    sys.stderr.write(
+        "Optional Textual dependency not available. Install this package as `textual-image[textual]` for Textual support."
+    )
+else:
+    from textual_image.demo.widget import run as run_textual_demo
+
+    run_textual_demo(arguments.method)

textual_image/_geometry.py

@@ -0,0 +1,133 @@
+"""Geometry types and logic."""
+
+from types import NoneType
+from typing import NamedTuple, Tuple, cast
+
+from textual_image._terminal import TerminalSizes
+
+
+class ImageSize(NamedTuple):
+    """Image size class capable of parsing size specifications and calculating pixel and cell sizes.
+
+    This class expects the size of the source image as `source_pixel_width` and `source_pixel_height`
+    and a target width and height as `width` and `height`.
+    `width` and `height` can have multiple forms:
+
+    - If set to an integer, they describe the number of cells to be used when rendering the image.
+    - If set to a string ending with `%` (e.g. `80%`) they describe the percentage of available render
+      space to be used when rending the image.
+    - If set to `auto` the image will be scaled to use as much as possible of the available render space
+      while keeping the image's aspect ratio.
+    - If set to `None` the original images dimension will be used.
+    """
+
+    source_pixel_width: int
+    source_pixel_height: int
+    width: int | str | None
+    height: int | str | None
+
+    def validate(self) -> None:
+        """Validate the instance's size specifications.
+
+        Raises:
+            ValueError: If `width` or `height` are not valid.
+        """
+        self.validate_value(self.width)
+        self.validate_value(self.height)
+
+    @classmethod
+    def validate_value(cls, value: int | str | None) -> None:
+        """Validate a single size specification.
+
+        Args:
+            value: The size specification.
+
+        Raises:
+            ValueError: If `width` or `height` are not valid.
+        """
+        if isinstance(value, (int, NoneType)) or value == "auto":
+            return
+        if isinstance(value, str) and value.endswith("%") and value[:-1].isdecimal() and int(value[:-1]) >= 0:
+            return
+        raise ValueError(f"Invalid size: {value}")
+
+    def get_cell_size(self, max_width: int, max_height: int, terminal_sizes: TerminalSizes) -> Tuple[int, int]:
+        """Calculates the render size based on original image size, size specification and terminal cell sizes.
+
+        Args:
+            max_width: The maximum available render width in cells.
+            max_height: The maximum available render height in cells.
+            terminal_sizes: Size information of the terminal.
+
+        Returns:
+            The render size in cells as tuple of (width, height).
+        """
+        self.validate()
+
+        if self.source_pixel_height == 0 or self.source_pixel_width == 0:
+            return 0, 0
+
+        width = None
+        height = None
+
+        # Just use the original image size for dimensions that're `None`
+        if self.width is None:
+            width = round(self.source_pixel_width / terminal_sizes.cell_width)
+        if self.height is None:
+            height = round(self.source_pixel_height / terminal_sizes.cell_height)
+
+        # Explicitly given cell sizes
+        if isinstance(self.width, int):
+            width = self.width
+        if isinstance(self.height, int):
+            height = self.height
+
+        # Percentage of available space
+        if isinstance(self.width, str) and self.width.endswith("%"):
+            width = round(max_width / 100 * int(self.width[:-1]))
+        if isinstance(self.height, str) and self.height.endswith("%"):
+            height = round(max_height / 100 * int(self.height[:-1]))
+
+        # If `width` is `auto` we use the `max_width` if we don't have a height specified,
+        # but keep the ratio if `height` was set
+        if self.width == "auto" and self.height is not None:
+            ratio = self.source_pixel_width / self.source_pixel_height
+            scaled_pixel_height: float = (height or max_height) * terminal_sizes.cell_height
+            scaled_pixel_width = scaled_pixel_height * ratio
+            width = min(round(scaled_pixel_width / terminal_sizes.cell_width), max_width)
+        elif self.width == "auto":
+            width = max_width
+
+        # Same for height
+        if self.height == "auto" and self.width is not None:
+            ratio = self.source_pixel_width / self.source_pixel_height
+            scaled_pixel_width = cast(int, width) * terminal_sizes.cell_width
+            scaled_pixel_height = scaled_pixel_width / ratio
+            height = round(scaled_pixel_height / terminal_sizes.cell_height)
+        elif self.height == "auto":
+            height = max_height
+
+        # By deriving `height` from `width` in the `auto` case, `height` may exceed `max_height`,
+        # which shouldn't happen when set to `auto`. Fix this my scaling down both `height` and `width`.`
+        if self.width == "auto" and self.height == "auto" and cast(int, height) > max_height:
+            height = max_height
+            ratio = self.source_pixel_width / self.source_pixel_height
+            scaled_pixel_height = height * terminal_sizes.cell_height
+            scaled_pixel_width = scaled_pixel_height * ratio
+            width = round(scaled_pixel_width / terminal_sizes.cell_width)
+
+        return cast(Tuple[int, int], (width, height))
+
+    def get_pixel_size(self, max_width: int, max_height: int, terminal_sizes: TerminalSizes) -> Tuple[int, int]:
+        """Calculates the pixel size to use for rendering based on original image size, size specification and terminal cell sizes.
+
+        Args:
+            max_width: The maximum available render width in cells.
+            max_height: The maximum available render height in cells.
+            terminal_sizes: Size information of the terminal.
+
+        Returns:
+            The render size in pixels as tuple of (width, height).
+        """
+        width, height = self.get_cell_size(max_width, max_height, terminal_sizes)
+        return width * terminal_sizes.cell_width, height * terminal_sizes.cell_height

textual_image/_pixeldata.py

@@ -0,0 +1,134 @@
+"""Provides access to pixel data."""
+
+import io
+from base64 import b64encode
+from contextlib import nullcontext
+from pathlib import Path
+from typing import ContextManager, Iterable, Iterator, Literal, Tuple
+
+from PIL import Image as PILImage
+
+from textual_image._utils import grouped
+
+
+def ensure_image(image: str | Path | PILImage.Image) -> ContextManager[PILImage.Image]:
+    """Ensures value to be an `PIL.Image.Image`.
+
+    This function accepts either a str or `pathlib.Path` of a path to an image file or a `PIL.Image.Image` instance.
+    It returns a context manager that either just provides the passed `PIL.Image.Image` instance or opens the path
+    with `PIL` and provides the result.
+
+    Args:
+        image: Path to an image file or `PIL.Image.Image` instance.
+
+    Returns:
+        A context manager providing a `PIL.Image.Image` instance.
+    """
+    if isinstance(image, PILImage.Image):
+        return nullcontext(image)
+    return PILImage.open(image)
+
+
+class PixelMeta:
+    """Provides access to meta information of an image from a path or `PIL.Image.Image` instance."""
+
+    def __init__(self, image: str | Path | PILImage.Image) -> None:
+        """Initializes a PixelMeta.
+
+        Args:
+            image: Path to an image file or `PIL.Image.Image` instance with the image data to render.
+        """
+        with ensure_image(image) as opened_image:
+            self.width = opened_image.width
+            self.height = opened_image.height
+
+
+class PixelData:
+    """Provides access to pixel data from a path or `PIL.Image.Image` instance."""
+
+    def __init__(self, image: str | Path | PILImage.Image, mode: Literal["grayscale", "rgb"] | None = None) -> None:
+        """Initializes a PixelData.
+
+        Args:
+            image: Path to an image file or `PIL.Image.Image` instance with the image data to render.
+            mode: Mode to convert the image into or `None` to keep the original mode.
+        """
+        with ensure_image(image) as opened_image:
+            self._image = opened_image.copy()
+
+        if mode == "grayscale":
+            self._image = self._image.convert("L")
+        elif mode == "rgb":
+            self._image = self._image.convert("RGB")
+
+    @property
+    def pil_image(self) -> PILImage.Image:
+        """The image as `PILImage.Image`."""
+        return self._image
+
+    @property
+    def width(self) -> int:
+        """The image's width."""
+        return self._image.width
+
+    @property
+    def height(self) -> int:
+        """The image's height."""
+        return self._image.height
+
+    def scaled(self, width: int, height: int) -> "PixelData":
+        """Returns a scaled copy of this PixelData.
+
+        Args:
+            width: Width to scale to.
+            height: Height to scale to.
+
+        Returns:
+            A new `PixelData` instance of the same image, scaled to (width, height).
+        """
+        scaled_image = self._image.resize((width, height))
+        return PixelData(scaled_image)
+
+    def cropped(self, left: int, top: int, right: int, bottom: int) -> "PixelData":
+        """Returns a cropped copy of this PixelData.
+
+        Args:
+            left: Left position of the crop rectangle.
+            top: Top position of the crop rectangle.
+            right: Right position of the crop rectangle.
+            bottom: Bottom position of the crop rectangle.
+
+        Returns:
+            A new `PixelData` instance of the same image, cropped (left, top, right, bottom).
+        """
+        cropped_image = self._image.crop((left, top, right, bottom))
+        return PixelData(cropped_image)
+
+    def to_base64(self) -> str:
+        """Return the pixel data as base64 encoded PNG.
+
+        Returns:
+        The image data, as base64 encoded PNG.
+        """
+        image_buffer = io.BytesIO()
+        self._image.save(image_buffer, format="png", compress_level=2)
+        return b64encode(image_buffer.getvalue()).decode("ascii")
+
+    def __iter__(self) -> Iterator[Iterable[int | Tuple[int, ...]]]:
+        """Iterate the pixel data.
+
+        Returns an `Iterator` over rows of the image.
+        The rows are `Iterable`s of pixel values.
+
+        Example:
+            Iterate the image data::
+
+            for row in PixelData("image.png"):
+                for pixel in row:
+                    ...  # Do something with the pixel here
+
+        Returns:
+            An `Iterator` over `Iterable`s of pixel values.
+        """
+        data = self._image.getdata()
+        yield from grouped(data, self._image.width)

textual_image/_sixel.py

@@ -0,0 +1,67 @@
+from itertools import groupby
+
+from PIL import Image as PILImage
+
+from textual_image._utils import grouped
+
+DCS = "\x1bP"
+ST = "\x1b\\"
+COLORS = 256
+
+
+def image_to_sixels(image: PILImage.Image) -> str:
+    """Convert an image to Sixels.
+
+    This function convert a `PIL.Image.Image` into the Sixel format.
+
+    Args:
+        image: Image to convert to Sixels
+
+    Returns:
+        The `image` as Sixel data.
+    """
+    image = image.convert("RGB").convert("P", palette=PILImage.Palette.ADAPTIVE, colors=COLORS)
+
+    return "".join(
+        [
+            _get_header(image),
+            _get_body(image),
+            _get_terminator(),
+        ]
+    )
+
+
+def _get_header(image: PILImage.Image) -> str:
+    # See <https://vt100.net/docs/vt3xx-gp/chapter14.html#S14.2.1> for details about the parameters.
+    sixel_mode = f"{DCS}0;0;0"
+    raster_attributes = f'q"1;1;{image.width};{image.height}'
+
+    color_registers = []
+    for i, color in enumerate(grouped(image.getpalette() or [], 3)):
+        color_str = ";".join(str(int(channel / 256 * 100)) for channel in color)
+        color_registers.append(f"#{i};2;{color_str}")
+
+    return f'{sixel_mode}{raster_attributes}{"".join(color_registers)}'
+
+
+def _get_body(image: PILImage.Image) -> str:
+    tokens = []
+
+    for y, row in enumerate(grouped(image.getdata(), image.width)):
+        n = 1 << y % 6
+        for color, group in groupby(row):
+            tokens.append(f"#{color}")
+
+            count = len(list(group))
+            if count < 3:
+                tokens.append(chr(0x3F + n) * count)
+            else:
+                tokens.append(f"!{count}{chr(0x3F + n)}")
+
+        tokens.append("-" if n == 32 else "$")
+
+    return "".join(tokens)
+
+
+def _get_terminator() -> str:
+    return ST

textual_image/_terminal.py

@@ -0,0 +1,132 @@
+"""Functionality to interact with the terminal."""
+
+import logging
+import os
+import sys
+import termios
+import tty
+from array import array
+from contextlib import contextmanager
+from fcntl import ioctl
+from select import select
+from types import SimpleNamespace
+from typing import Iterator, NamedTuple
+
+logger = logging.getLogger(__name__)
+
+
+class TerminalError(Exception):
+    """Error thrown on failing terminal operations."""
+
+    pass
+
+
+class TerminalSizes(NamedTuple):
+    """Size of several terminal features."""
+
+    rows: int
+    """Width of the terminal in cells."""
+    columns: int
+    """Height of the terminal in cells."""
+    screen_width: int
+    """Width of the terminal in pixels."""
+    screen_height: int
+    """Height of the terminal in pixels."""
+    cell_width: int
+    """Width of a terminal cell in pixels."""
+    cell_height: int
+    """Height of a terminal cell in pixels."""
+
+
+def get_terminal_sizes() -> TerminalSizes:
+    """Get size information from the terminal.
+
+    Returns:
+        The size information
+
+    """
+    if not sys.__stdout__:
+        raise TerminalError("stdout is closed")
+
+    if sys.__stdout__.isatty():
+        try:
+            buf = array("H", [0, 0, 0, 0])
+            ioctl(sys.__stdout__, termios.TIOCGWINSZ, buf)
+
+            rows, columns, screen_width, screen_height = buf
+
+            # If we can't get the cell size (not all terminals support this) we're just assuming some hopefully reasonable numbers.
+            # Does this suck? Yes. Is there something we can do about it? Not really.
+            if not screen_width or not screen_height:
+                logger.warning("Terminal doesn't support getting pixel size; falling back to assumptions")
+
+        except OSError as e:
+            raise TerminalError("Unsupported terminal") from e
+
+    else:
+        logger.debug("Not connected to a terminal, assuming reasonable size information")
+        rows = 24
+        columns = 80
+        screen_width = 0
+        screen_height = 0
+
+    cell_width = int(screen_width / columns) or 8
+    cell_height = int(screen_height / rows) or 16
+
+    return TerminalSizes(
+        rows=rows,
+        columns=columns,
+        screen_width=screen_width,
+        screen_height=screen_height,
+        cell_width=cell_width,
+        cell_height=cell_height,
+    )
+
+
+@contextmanager
+def capture_terminal_response(
+    start_marker: str, end_marker: str, timeout: float | None = None
+) -> Iterator[SimpleNamespace]:
+    """Captures a terminal response.
+
+    Captures the terminal's response to an escape sequence.
+    This is a bit flaky -- keystrokes during reading the response can lead to false answers.
+    Additionally, when the terminal does *not* doesn't send an answer, the first character
+    of stdin may get lost as this function reads it to determine if it is the response.
+    Anyway, as this is improbable to happen, it should be fine.
+
+    Please not this function will not work anymore once Textual is started. Textual runs a threads to read stdin
+    and will grab the response.
+
+    Args:
+        start_marker: The start sequence of the expected response
+        end_marker: The end sequence of the expected response
+        timeout: The number of seconds to wait for the response. None to disable timeout.
+
+    Returns:
+        The terminal's response
+    """
+    if not sys.__stdin__:
+        raise TerminalError("stdout is closed")
+
+    response = SimpleNamespace(sequence="")
+
+    stdin = sys.__stdin__.buffer.fileno()
+    old_term_mode = termios.tcgetattr(stdin)
+    tty.setcbreak(stdin, termios.TCSANOW)
+
+    try:
+        yield response
+
+        while not response.sequence.endswith(end_marker):
+            readable, _, _ = select([stdin], [], [], timeout)
+            if not readable:
+                raise TimeoutError("Timeout waiting for response")
+
+            response.sequence += os.read(stdin, 1).decode()
+
+            if not response.sequence.startswith(start_marker[: len(response.sequence)]):
+                raise TerminalError("Unexpected response from terminal")
+
+    finally:
+        termios.tcsetattr(stdin, termios.TCSANOW, old_term_mode)

textual_image/_utils.py

@@ -0,0 +1,44 @@
+"""Utility functions."""
+
+from typing import Iterable, Iterator, TypeVar
+
+T = TypeVar("T")
+
+
+def grouped(iterable: Iterable[T], n: int) -> Iterator[Iterable[T]]:
+    """Groups values of an iterable into equally sized groups.
+
+    The values of iterable are collected into groups of size `n`.
+    An iterator over the resulting groups is returned.
+
+    Example:
+        Grouping a list of integers::
+
+            >>> list(grouped([1, 2, 3, 4, 5, 6], 2))
+            [(1, 2), (3, 4), (5, 6)]
+
+    Args:
+        iterable: Iterable over the values to group
+        n: Size of each group
+
+    Returns:
+        An iterator over the groups
+    """
+    return zip(*([iter(iterable)] * n), strict=True)
+
+
+N = TypeVar("N", bound=int | float)
+
+
+def clamp(n: N, minimum: N, maximum: N) -> N:
+    """Constrains a value to lie between two further values.
+
+    Args:
+        n: The value to constrain.
+        minimum: The manimum value n may have.
+        maximum: The maximum value n may have.
+
+    Returns:
+        The constrained value.
+    """
+    return max(min(n, maximum), minimum)

textual_image-0.5.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.1
+Name: textual-image
+Version: 0.5.0
+Summary: Render images via Kitty's Terminal Graphics Protocol with Rich and Textual
+Author-email: Simon Hayessen <simon@lnqs.io>
+Project-URL: Homepage, https://github.com/lnqs/textual-image
+Project-URL: Documentation, https://github.com/lnqs/textual-image
+Project-URL: Repository, https://github.com/lnqs/textual-image
+Project-URL: Issues, https://github.com/lnqs/textual-image/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: License :: OSI Approved :: GNU General Public License (GPL)
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Description-Content-Type: text/markdown
+Requires-Dist: pillow>=10.3.0
+Requires-Dist: rich>=13.4.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: syrupy; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: typing-extensions; extra == "dev"
+Requires-Dist: typos; extra == "dev"
+Provides-Extra: textual
+Requires-Dist: textual>=0.68.0; extra == "textual"
+
+# textual-image
+
+**Render images directly in your terminal using [Textual](https://www.textualize.io/) and [Rich](https://github.com/Textualize/rich).**
+
+![Demo App](./demo.gif)
+
+_textual-image_ offers both Rich renderables and Textual Widgets that leverage the [Terminal Graphics Protocol (TGP)](https://sw.kovidgoyal.net/kitty/graphics-protocol/) and [Sixel](https://en.wikipedia.org/wiki/Sixel) protocols to display images in your terminal. For terminals that don't support these protocols, fallback rendering using Unicode characters is available.
+
+## Supported Terminals
+
+- **Terminal Graphics Protocol (TGP)**: Initially introduced by the [Kitty](https://sw.kovidgoyal.net/kitty/) terminal emulator, fully supported in Kitty, and largely implemented in [WezTerm](https://wezfurlong.org/wezterm/index.html) and partially supported by [Konsole](https://konsole.kde.org/) and [wayst](https://github.com/91861/wayst).
+- **Sixel Graphics**: Supported by various terminal emulators including [xterm](https://invisible-island.net/xterm/) and others.
+
+_Note_: Testing has been conducted primarily using Kitty for TGP and xterm for Sixel on Linux, with some sanity checks on other terminals. Feedback and interoperability testing on other terminal emulators and operating systems would be highly valued.
+
+See the Support Matrix below on what was tested already.
+
+### Support Matrix [^1]
+
+| Terminal            | TPG support | Sixel support | Works with textual-image |
+|---------------------|:-----------:|:-------------:|:------------------------:|
+| Alacritty           |          ❌ |            ❌ |                          |
+| Black Box           |          ❌ |            ✅ |                       ⚫ |
+| Bobcat              |          ❌ |            ✅ |                       ⚫ |
+| ConEmu              |          ❌ |            ❌ |                          |
+| Contour             |          ❌ |            ✅ |                       ⚫ |
+| ctx terminal        |          ❌ |            ✅ |                       ⚫ |
+| Darktile            |          ❌ |            ✅ |                       ⚫ |
+| DomTerm             |          ❌ |            ✅ |                       ⚫ |
+| Eat                 |          ❌ |            ✅ |                       ⚫ |
+| Elementary Terminal |          ❌ |            ❌ |                          |
+| foot                |          ❌ |            ✅ |                       ✅ |
+| GNOME Terminal      |          ❌ |            ❌ |                          |
+| guake               |          ❌ |            ❌ |                          |
+| iTerm2              |          ❌ |            ✅ |                       ⚫ |
+| kitty               |          ✅ |            ❌ |                       ✅ |
+| konsole             |          ✅ |            ✅ |                   ❓[^2] |
+| LaTerminal          |          ❌ |            ✅ |                       ⚫ |
+| MacTerm             |          ❌ |            ✅ |                       ⚫ |
+| mintty              |          ❌ |            ✅ |                       ⚫ |
+| mlterm              |          ❌ |            ✅ |                       ⚫ |
+| MobaXterm           |          ❌ |            ❌ |                          |
+| PuTTY               |          ❌ |            ❌ |                          |
+| Rio terminal        |          ❌ |            ❌ |                          |
+| Rlogin              |          ❌ |            ✅ |                       ⚫ |
+| suckless st         |          ❌ |            ❌ |                          |
+| SwiftTerm           |          ❌ |            ✅ |                       ⚫ |
+| SyncTERM            |          ❌ |            ✅ |                       ⚫ |
+| TeraTerm            |          ❌ |            ❌ |                          |
+| Terminal.app        |          ❌ |            ❌ |                          |
+| Terminology         |          ❌ |            ❌ |                          |
+| termux              |          ❌ |            ❌ |                          |
+| Tilix               |          ❌ |            ❌ |                          |
+| tmux                |          ❌ |            ✅ |                   ✅[^3] |
+| toyterm             |          ❌ |            ✅ |                       ⚫ |
+| URxvt               |          ❌ |            ❌ |                          |
+| U++                 |          ❌ |            ✅ |                       ⚫ |
+| Visual Studio Code  |          ❌ |            ✅ |                   ✅[^4] |
+| wayst               |          ✅ |            ✅ |                   ❓[^5] |
+| wezterm             |          ✅ |            ✅ |                   ❓[^6] |
+| Windows Console     |          ❌ |            ❌ |                          |
+| Windows Terminal    |          ❌ |            ✅ |                       ⚫ |
+| xfce-terminal       |          ❌ |            ✅ |                       ⚫ |
+| xterm               |          ❌ |            ✅ |                       ✅ |
+| xterm.js            |          ❌ |            ✅ |                       ⚫ |
+| yaft                |          ❌ |            ✅ |                       ⚫ |
+| Yakuake             |          ❌ |            ✅ |                       ⚫ |
+| Zellij              |          ❌ |            ✅ |                   ❌[^7] |
+
+✅ = Supported; ❌ = Not Supported; ⚫ = To Be Tested; ❓ = Works, but with glitches (further investigation needed)
+
+[^1]: Based on [Are We Sixel Yet?](https://www.arewesixelyet.com/)
+[^2]: Reports to support TGP but doesn't draw images. If set to Sixel explicitly, it works besides a few minor glitches.
+[^3]: Works only in a Sixel enabled terminal, TGP does not work with tmux.
+[^4]: The `terminal.integrated.enableImages` setting has to be enabled.
+[^5]: Both TGP and Sixel draw graphics, but only with major glitches.
+[^6]: TGP draws graphics, but with major glitches; Sixel works fine but doesn't get auto-selected due to reporting TGP support.
+[^7]: Reports to support Sixel, but doesn't draw anything.
+
+### Enabling Sixel Support on xterm
+
+Sixel on xterm is disabled by default. To enable it, add `+lc` and `-ti vt340` options when launching xterm:
+
+```sh
+xterm +lc -ti vt340
+```
+
+Alternatively, you can add these options to your xterm configuration file (`~/.Xresources` or `~/.Xdefaults`) to make the change permanent:
+
+```sh
+echo 'XTerm*decTerminalID: vt340' >> ~/.Xresources
+xrdb -merge ~/.Xresources
+```
+
+## Installation
+
+Install _textual-image_ using pip with the following commands:
+
+For the basic installation:
+```sh
+pip install textual-image
+```
+
+To include the Textual Widget's dependencies:
+```sh
+pip install textual-image[textual]
+```
+
+## Demonstration
+
+Once installed, run the demo application to see the module in action.
+
+For a demonstration of the Rich renderable, use:
+```sh
+python -m textual_image rich
+```
+
+For a demonstration of the Textual Widget, use:
+```sh
+python -m textual_image textual
+```
+
+The module will automatically select the best available rendering option. If you wish to specify a particular rendering method, use the `-p` argument with one of the following values: `tgp`, `sixel`, `halfcell`, or `unicode`.
+
+For more information, use:
+```sh
+python -m textual_image --help
+```
+
+## Usage
+
+### Rich Integration
+
+To use the Rich renderable, simply pass an instance of `textual_image.renderable.Image` to a Rich function that renders data:
+
+```python
+from rich.console import Console
+from textual_image.renderable import Image
+
+console = Console()
+console.print(Image("path/to/image.png"))
+```
+
+The `Image` constructor accepts either a string, a `pathlib.Path` representing the file path of an image readable by [Pillow](https://python-pillow.org/), or a Pillow `Image` instance directly.
+
+By default, the image is rendered in its original dimensions. You can modify this behavior by specifying the `width` and/or `height` parameters. These can be defined as an integer (number of cells), a percentage string (e.g., `50%`), or the literal `auto` to automatically scale while maintaining the aspect ratio.
+
+`textual_image.renderable.Image` defaults to the best available rendering method. To specify an explicit rendering method, use one of the following classes: `textual_image.renderable.tgp.Image`, `textual_image.renderable.sixel.Image`, `textual_image.renderable.halfcell.Image`, or `textual_image.renderable.unicode.Image`.
+
+### Textual Integration
+
+For integration with Textual, _textual-image_ offers a Textual `Widget` to render images:
+
+```python
+from textual.app import App, ComposeResult
+from textual_image.widget import Image
+
+class ImageApp(App[None]):
+    def compose(self) -> ComposeResult:
+        yield Image("path/to/image.png")
+
+ImageApp().run()
+```
+
+The `Image` constructor accepts either a string or a `pathlib.Path` with the file path of an image readable by [Pillow](https://python-pillow.org/), or a Pillow `Image` instance directly.
+
+You can also set the image using the `image` property of an `Image` instance:
+
+```python
+from textual.app import App, ComposeResult
+from textual_image.textual import Image
+
+class ImageApp(App[None]):
+    def compose(self) -> ComposeResult:
+        image = Image()
+        image.image = "path/to/image.png"
+        yield image
+
+ImageApp().run()
+```
+
+If a different image is set, the Widget will update to display the new image.
+
+By default, the best available rendering option is used. To override this, you can instantiate `textual_image.widget.TGPImage`, `textual_image.widget.SixelImage`, `textual_image.widget.HalfcellImage`, or `textual_image.widget.UnicodeImage` directly.
+
+_*Note*_: The process of determining the best available rendering option involves querying the terminal, which means sending and receiving data. Since Textual starts threads to handle input and output, this query will **not work** once the Textual app has started. Therefore, make sure that `textual_image.renderable` is imported **before** running the Textual app (which is typically the case in most use cases).
+
+## Limitations
+
+- **Sixel Support in Textual**: Sixel support in Textual is not particularly performant due to the way Textual handles rendering. The Sixel graphics are injected into the rendering process in a somewhat hacky manner, which affects performance. Scrolling and changing styles of images can lead to a lot of flickering. But for mostly static images it should work fine. If not, please file an issue on GitHub.
+
+## Contribution
+
+If you find this module useful, please consider starring the repository on GitHub.
+
+This project began by moving some TGP functionality from a private project to a public GitHub repository and PyPI package, with some additional code added along the way to support Sixel graphics. If you encounter any issues, please file an issue on GitHub.
+
+Contributions via pull requests are welcome and encouraged.

textual_image-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+textual_image/__init__.py,sha256=Z2sVPBEYASzL_HAPG0iYCko2XKxTtQ4-K6zmTCe3o3A,135
+textual_image/__main__.py,sha256=68Q5b1U5cxlPvssfc91-ZzXYGhgjq2VfXeNPB1wle1w,1034
+textual_image/_geometry.py,sha256=I6rDB6LBMBAypDzQ0613DNxnr4HXtMGUD1xL0QG0rOU,5808
+textual_image/_pixeldata.py,sha256=YqOdRTJTKIfVEya82vugVmskrY8XKUKEGivADbAKJSU,4504
+textual_image/_sixel.py,sha256=pLsYtR1af_7Ow5sVv6h2M08wSddzLzNqWt7ooSKC5jo,1750
+textual_image/_terminal.py,sha256=zzxfdKT0h0uaS9t_cWM0rPxifjFDtwFb1wlwYEKOq_s,4122
+textual_image/_utils.py,sha256=laffJ8rjenr9tHlcy05bSuJkHi5VzYAPn53OD18nVe0,1075
+textual_image-0.5.0.dist-info/METADATA,sha256=fgSOxeOmJWqv7NGh75nSzleA030qB5vmvitDePplxzA,12684
+textual_image-0.5.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+textual_image-0.5.0.dist-info/top_level.txt,sha256=MOt8XOuhYDHzY66-5tWpDc7ctvTVrcHPjGOa7E7YyYI,14
+textual_image-0.5.0.dist-info/RECORD,,

textual_image-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

textual_image-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+textual_image