Implementation:Kornia Kornia Image Print
| Knowledge Sources | |
|---|---|
| Domains | Vision, Visualization, Terminal |
| Last Updated | 2026-02-09 15:00 GMT |
Overview
This module converts image tensors to ANSI escape-code strings for xterm-256color terminals, enabling visual rendering of images directly in the console.
Description
The image_print module in the Kornia image package provides functions and data structures for rendering images in terminal environments using xterm-256 color approximation. It contains a comprehensive CLUT (Color Look-Up Table) mapping 256 xterm color codes to their RGB hex values, along with the inverse mapping. The rgb2short function finds the closest xterm-256 color for any RGB hex value. The image_to_string function takes an image tensor of shape (C, H, W), optionally resizes it to a maximum width, and produces an ANSI escape-code string that renders the image using colored background characters. The print_image convenience function accepts either a file path or a tensor and prints it to the terminal.
Usage
Import this module when you need to visually inspect images in terminal-based environments (SSH sessions, CLI tools, notebooks without display) by printing a low-resolution color approximation to stdout.
Code Reference
Source Location
- Repository: Kornia
- File: kornia/image/image_print.py
- Lines: 1-421
Signature
def rgb2short(rgb: str) -> Tuple[str, str]: ...
def image_to_string(image: torch.Tensor, max_width: int = 256) -> str: ...
def print_image(image: Union[str, torch.Tensor], max_width: int = 96) -> None: ...
Import
from kornia.image.image_print import image_to_string, print_image, rgb2short
I/O Contract
image_to_string
| Name | Type | Required | Description |
|---|---|---|---|
| image | torch.Tensor | Yes | RGB image tensor of shape (3, H, W). Accepts float [0, 1] or int [0, 255]. |
| max_width | int | No | Maximum width before downscaling (default 256). |
print_image
| Name | Type | Required | Description |
|---|---|---|---|
| image | str or torch.Tensor | Yes | Path to an image file or an image tensor. |
| max_width | int | No | Maximum width for terminal output (default 96). |
rgb2short
| Name | Type | Required | Description |
|---|---|---|---|
| rgb | str | Yes | Hex RGB string, e.g. abcdef. |
Outputs
| Function | Return Type | Description |
|---|---|---|
| image_to_string | str | ANSI escape-code string that renders the image in xterm-256color terminals. |
| print_image | None | Prints the image to stdout. |
| rgb2short | Tuple[str, str] | Tuple of (xterm color code, closest RGB hex). |
Color Mapping
The module uses a 256-entry CLUT (Color Look-Up Table) based on the xterm-256color palette:
- Entries 0-7: Primary 8 colors
- Entries 8-15: Bright variants
- Entries 16-231: 6x6x6 color cube
- Entries 232-255: 24-step grayscale ramp
The rgb2short function finds the closest color by snapping each RGB channel to the nearest value in the set {0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF}.
Usage Examples
import torch
from kornia.image.image_print import image_to_string, print_image, rgb2short
# Convert RGB hex to xterm-256 code
code, approx = rgb2short('123456') # ('23', '005f5f')
# Render a tensor image as ANSI string
img = torch.rand(3, 64, 64)
ansi_str = image_to_string(img, max_width=80)
print(ansi_str)
# Print image from file path
print_image("photo.png", max_width=96)
# Print image from tensor
print_image(img, max_width=96)