wijjit.elements.display.image.ImageView

class wijjit.elements.display.image.ImageView(id=None, classes=None, src=None, width=None, height=None, mode='color', threshold='auto', invert=False, background=(0, 0, 0), bind=True)[source]

Element for displaying images in the terminal.

Converts images to ANSI-colored characters for terminal display. Supports three rendering modes, selected with mode:

  • "color" (default): Uses half-block characters (U+2580) with foreground (upper pixel) and background (lower pixel) colors, achieving 2x vertical resolution.

  • "quadrant": Uses quadrant block characters (U+2596-U+259F) for a 2x2 subpixel grid per cell. Each cell is split into a bright and a dark group at the cell’s own mean luminance and drawn with two colors, so it keeps full color while doubling horizontal detail over "color".

  • "braille": Converts the image to black/white using threshold, then renders using braille characters (U+2800-U+28FF) for 2x4 pixel resolution per character.

Notes

Braille resolves 2x4 subpixels but its dots only cover part of each cell, so fine detail is monochrome and visually diluted. "quadrant" resolves fewer subpixels but fills the cell completely and keeps color, which reads better for photographs; "braille" suits line art and high-contrast graphics. Denser full-coverage charsets exist (sextants at 2x3, octants at 2x4) but are absent from common terminal fonts - including Cascadia Mono, the Windows Terminal default - so they are deliberately not offered here.

Parameters:

  • id (str, optional) – Element identifier

  • src (str, Path, bytes, or PIL.Image.Image, optional) – Image source - file path, bytes data, or PIL Image object

  • width (int or str, optional) – Display width. If “auto” or None, calculate from height and aspect ratio. If “fill”, expand to available space.

  • height (int or str, optional) – Display height. If “auto” or None, calculate from width and aspect ratio. If “fill”, expand to available space.

  • mode (str, optional) – Rendering mode: “color”, “quadrant”, or “braille” (default: “color”)

  • threshold (int or str, optional) – Binarization cutoff for braille mode: an integer 0-255, or “auto” to compute Otsu’s threshold from the image (default: “auto”)

  • invert (bool, optional) – If True, invert the threshold in braille mode so dark pixels become dots instead of light pixels (default: False)

  • background (tuple of (int, int, int), optional) – Background RGB color for transparency compositing (default: (0, 0, 0))

  • classes (str or list of str, optional) – CSS class names for styling

  • bind (bool | str)

Raises:

ValueError – If mode is not one of the supported modes, or threshold is neither “auto” nor an integer.

Variables:

  • src (ImageSource) – Image source

  • width_spec (int or str or None) – Width specification

  • height_spec (int or str or None) – Height specification

  • mode (str) – Active rendering mode

  • threshold (int or str) – Braille binarization cutoff, or “auto”

  • invert (bool) – Whether to invert the braille threshold

  • background (tuple) – Background color for transparency

__init__(id=None, classes=None, src=None, width=None, height=None, mode='color', threshold='auto', invert=False, background=(0, 0, 0), bind=True)[source]
Parameters:
Return type:

None

Methods

__init__([id, classes, src, width, height, ...])

add_class(class_name)

Add a CSS class to this element.

apply_props(props)

Apply props from a VNode, skipping ephemeral props.

get_ephemeral_state()

Get ephemeral state that should survive reconciliation.

get_hardware_cursor_position()

Absolute screen cell where the hardware terminal cursor should park.

get_height_for_width(width)

Return the height this element needs when laid out at width.

get_intrinsic_size()

Get the intrinsic size based on image dimensions.

handle_key(key)

Handle a key press.

handle_mouse(event)

Handle a mouse event.

has_class(class_name)

Check if element has a CSS class.

invalidate_cache()

Force cache invalidation for next render.

on_blur()

Called when element loses focus.

on_focus()

Called when element gains focus.

on_hover_enter()

Called when mouse enters element.

on_hover_exit()

Called when mouse exits element.

on_mount()

Called when element is first added to the element tree.

on_unmount()

Called when element is removed from the element tree.

on_update(changed_props)

Called when element props are updated during reconciliation.

remove_class(class_name)

Remove a CSS class from this element.

render_signature()

Hashable/comparable capture of everything render_to() reads.

render_to(ctx)

Render the image to the paint context.

restore_ephemeral_state(state)

Restore ephemeral state after reconciliation.

set_bounds(bounds)

Set the element's screen bounds.

set_src(src)

Update image source and invalidate cache.

toggle_class(class_name)

Toggle a CSS class on this element.

Attributes

BRAILLE_BASE

BRAILLE_DOTS

HALF_BLOCK

MODES

Supported values for mode.

QUADRANT_CHARS

captures_tab

Whether this element wants the Tab key instead of focus movement.

parent_frame

Get the parent Frame if this element is inside a scrollable frame.

supports_dynamic_sizing

Whether this element supports dynamic sizing.
MODES = ('color', 'quadrant', 'braille')

Supported values for mode.

HALF_BLOCK = '▀'
QUADRANT_CHARS = (' ', '▘', '▝', '▀', '▖', '▌', '▞', '▛', '▗', '▚', '▐', '▜', '▄', '▙', '▟', '█')
BRAILLE_BASE = 10240
BRAILLE_DOTS = [(0, 0, 0), (0, 1, 1), (0, 2, 2), (1, 0, 3), (1, 1, 4), (1, 2, 5), (0, 3, 6), (1, 3, 7)]
get_intrinsic_size()[source]

Get the intrinsic size based on image dimensions.

Returns:

(width, height) for auto sizing

Return type:

tuple of (int, int)

render_to(ctx)[source]

Render the image to the paint context.

Parameters:

ctx (PaintContext) – Paint context with buffer, style resolver, and bounds

Return type:

None

set_src(src)[source]

Update image source and invalidate cache.

Parameters:

src (ImageSource) – New image source

Return type:

None

invalidate_cache()[source]

Force cache invalidation for next render.

Return type:

None