Skip to content

v0.18.1

Choose a tag to compare

@tya5 tya5 released this 12 Aug 22:54
· 10 commits to main since this release

Documentation — which image renderables work, and why Sixel doesn't

A consumer reported images landing in the wrong position with Sixel. The cause is structural, and it was undocumented:

FlowView paints rows as cells and repaints them independently as you scroll, so it can only place an image that occupies cells. Measured, for the same image:

Renderable In the rendered row In FlowView
Kitty graphics, Unicode-placeholder (textual_image.renderable.tgp) 120 placeholder cells ✅ real pixels, positioned and clipped
Half-block / Unicode (…halfcell, rich-pixels) coloured cells ✅ works everywhere, approximate
Sixel (…sixel) 0 cells, 0 characters ❌ wrong position, no clipping

Sixel draws pixels relative to the cursor instead of into cells, so a virtualized painter has no way to position or clip it.

Why this bites: textual_image.renderable.Image auto-selects Sixel first wherever the terminal supports it (WezTerm, Konsole, xterm …) — so the convenient auto-detecting import is exactly the one that breaks. Import the cell-based renderable explicitly:

try:
    from textual_image.renderable.tgp import Image as ImageRenderable
except ImportError:
    from textual_image.renderable.halfcell import Image as ImageRenderable

The README now carries this matrix, the measurement and the guidance.

Fixed

  • examples/image.py used that auto-detecting import and so would have shown mispositioned images on Sixel-capable terminals. It now imports the Kitty placeholder renderable explicitly (verified: 456 placeholder cells painted, where Sixel would paint none).

Full Changelog: v0.18.0...v0.18.1