README.md

Rich Pixels

A Rich-compatible library for writing pixel images and other colourful grids to the terminal.

Installation

Get rich-pixels from PyPI.

pip install rich-pixels

Basic Usage

Images

Image from a file

You can load an image file from a path using from_image_path:

from rich_pixels import Pixels
from rich.console import Console

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

Pillow image object

You can create a PIL image object yourself and pass it in to from_image.

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)

Using this approach means you can modify your PIL Image beforehard.

ASCII Art

You can quickly build shapes using a tool like asciiflow, and apply styles the ASCII characters. This provides a quick way of sketching out shapes.

from rich_pixels import Pixels
from rich.console import Console
from rich.segment import Segment
from rich.style import Style

console = Console()

# Draw your shapes using any character you want
grid = """\
     xx   xx
     ox   ox
     Ox   Ox
xx             xx
xxxxxxxxxxxxxxxxx
"""

# Map characters to different characters/styles
mapping = {
    "x": Segment(" ", Style.parse("yellow on yellow")),
    "o": Segment(" ", Style.parse("on white")),
    "O": Segment(" ", Style.parse("on blue")),
}

pixels = Pixels.from_ascii(grid, mapping)
console.print(pixels)

Using with Textual

Pixels can be integrated into Textual applications just like any other Rich renderable.