rich-pixels

Install the rich-pixels library from PyPI using pip.

pip install rich-pixels

Use the Pixels.from_image method to create a Pixels object from an existing Pillow (PIL) Image object. This is useful if you need to perform image processing or modifications using Pillow before rendering to the terminal.

from rich_pixels import Pixels
from rich.console import Console
from PIL import Image

console = Console()

with Image.open("path/to/image.png") as image:
    pixels = Pixels.from_image(image)

console.print(pixels)

Use the Pixels.from_image_path method to load an image file directly from a filesystem path. The resulting Pixels object is a Rich-compatible renderable that can be printed using a rich.console.Console instance.

from rich_pixels import Pixels
from rich.console import Console

console = Console()
pixels = Pixels.from_image_path("pokemon/bulbasaur.png")
console.print(pixels)

Use Pixels.from_image_path() to create a Pixels object directly from a file path (string or PurePath). This method handles opening the image file using PIL. You can provide a resize tuple (width, height) and a renderer instance.

Note: This method requires the image extra dependencies to be installed.

from pathlib import Path
from rich_pixels import Pixels, HalfcellRenderer

pixels = Pixels.from_image_path("path/to/image.png", resize=(80, 40), renderer=HalfcellRenderer())

The Pixels class implements the __rich_console__ protocol, meaning you can pass a Pixels object directly to console.print() to render the pixel grid in your terminal.

from rich.console import Console
from rich_pixels import Pixels

console = Console()
pixels = Pixels.from_ascii("X")

console.print(pixels)

Use Pixels.from_image() to create a Pixels object from an existing PIL Image instance. You can optionally resize the image to a specific (width, height) tuple and specify a custom Renderer (e.g., FullcellRenderer or HalfcellRenderer). If no renderer is provided, it defaults to HalfcellRenderer.

Note: This method requires the image extra dependencies to be installed.

from PIL import Image
from rich_pixels import Pixels, FullcellRenderer

image = Image.open("path/to/image.png")
pixels = Pixels.from_image(image, resize=(40, 20), renderer=FullcellRenderer())

The Renderer class is the base class for all image-to-terminal rendering logic in rich-pixels. It provides the core render method which converts a PIL Image into a list of rich.segment.Segment objects.

When initializing a renderer, you can provide an optional default_color (as a string, e.g., 'black'). This color is used when a pixel is transparent or has an alpha value of 0. If default_color is provided, the renderer automatically configures a null_style using the on {default_color} pattern to ensure background consistency.

from PIL import Image
from rich_pixels import Renderer

# Note: Renderer is an abstract base class; use HalfcellRenderer or FullcellRenderer instead.
image = Image.open("example.png")
renderer = Renderer(default_color="black")
segments = renderer.render(image, resize=(80, 40))

The FullcellRenderer renders an image using full-height cells. Each pixel in the source image is represented by a two-space character ( ) in the terminal, where the background color of the space is set to the pixel's color.

This is a simpler rendering mode compared to HalfcellRenderer and maps one source pixel to one terminal character cell.

from PIL import Image
from rich_pixels import FullcellRenderer

image = Image.open("example.png")
renderer = FullcellRenderer()
segments = renderer.render(image, resize=(80, 40))

Use Pixels.from_segments() to create a Pixels object from an iterable of rich.segment.Segment objects. This is the lowest-level way to construct a Pixels object manually.

from rich.segment import Segment
from rich_pixels import Pixels

segments = [Segment("X", style="red"), Segment("O", style="blue")]
pixels = Pixels.from_segments(segments)