Repository navigation
v0.18.1
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 ImageRenderableThe README now carries this matrix, the measurement and the guidance.
Fixed
examples/image.pyused 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