imagepreview

package
v0.97.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package imagepreview renders low-resolution, in-terminal thumbnails of images using Unicode upper half-block characters (U+2580, "▀") combined with SGR foreground/background color codes.

The technique stacks two vertical pixels into a single character cell: the foreground color paints the top pixel and the background color paints the bottom pixel. This produces pure styled text — no graphics escape sequences — so the output survives terminal multiplexers (tmux, zellij) untouched.

The Kitty graphics protocol, Sixel, and iTerm2 inline images are deliberately NOT used: those are graphics escape-sequence protocols that tmux and zellij strip or mangle by default.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DeleteImage added in v0.97.0

func DeleteImage(id uint32) string

DeleteImage returns the escape sequence that removes a transmitted image and frees the memory the terminal holds for it.

Every transmitted thumbnail must be deleted once its preview is gone. Terminals keep image data until told otherwise, so a session that pastes many images would otherwise accumulate all of them.

func Render

func Render(data []byte, mediaType string, maxCols, maxRows int, bg color.Color) (string, error)

Render returns a half-block ANSI thumbnail of the image, scaled to fit within maxCols x maxRows terminal cells while preserving aspect ratio.

Each terminal cell encodes two vertically-stacked pixels, so the effective pixel resolution of the thumbnail is up to maxCols x (maxRows*2).

Colors are emitted at the fidelity of the detected terminal color profile: truecolor (24-bit) when available, degrading to 256-color. When the terminal supports neither (no truecolor and no 256-color), Render returns an empty string and a nil error so the caller can fall back to a text indicator. A non-nil error is only returned when the image data cannot be decoded.

bg is the color used to composite transparent pixels (typically the terminal background). A nil bg defaults to black.

Types

type Thumbnail added in v0.97.0

type Thumbnail struct {
	// Transmit is an escape sequence that must reach the terminal unmodified,
	// outside the normal view text. It is empty for half-block thumbnails.
	//
	// Write it with tea.Raw, never by embedding it in a view: the frame
	// renderer parses view text into cells and would mangle or drop an APC
	// sequence hidden inside it.
	Transmit string

	// Cells is the text to place in the view. For a placeholder thumbnail this
	// is the Unicode placeholder grid that displays the image; for a direct
	// placement it is blank cells that reserve the area the image is drawn
	// over; for a half-block thumbnail it is the coloured art itself. Either
	// way it is ordinary text that occupies exactly the intended cells, so the
	// frame renderer can measure, pad, and diff it like any other content.
	Cells string

	// ImageID identifies the transmitted image so it can be deleted later. It
	// is zero when nothing was transmitted.
	ImageID uint32

	// Cols and Rows are the size of the preview in terminal cells.
	Cols, Rows int

	// NeedsPlacement reports that the image is drawn by a direct placement
	// anchored at the cursor, rather than by placeholder cells that travel with
	// the view text.
	//
	// A direct placement is not part of the view, so the caller must position
	// the cursor and emit Place after every frame that shows the preview, and
	// must emit DeleteImage when it goes away. See RenderKittyDirect.
	NeedsPlacement bool
}

Thumbnail is a rendered image preview, split into the part that must be written straight to the terminal and the part that belongs in the view.

The half-block renderer produces Cells only. The Kitty renderers produce both: Transmit carries the image data, and Cells reserves the screen area the image occupies.

func RenderKitty added in v0.97.0

func RenderKitty(data []byte, maxCols, maxRows, cellW, cellH int) (Thumbnail, error)

RenderKitty builds a Kitty graphics thumbnail: a virtual image placement plus the Unicode placeholder grid that displays it.

Unicode placeholders let the image travel as ordinary text: the terminal draws it only where the placeholder cells appear, so it moves, scrolls, and disappears with the surrounding view. That is what a redrawing TUI wants, and it is the right choice wherever it works.

It does not work everywhere. Zellij 0.45 forwards the graphics protocol but discards the combining marks that tell each placeholder cell which part of the image it holds, so nothing is drawn. Use RenderKittyDirect there.

cellW and cellH are the pixel dimensions of a terminal cell, used to choose the resampling resolution. Pass zero for either to use a default.

maxCols and maxRows bound the preview in cells, as with Render.

func RenderKittyDirect added in v0.97.0

func RenderKittyDirect(data []byte, maxCols, maxRows, cellW, cellH int) (Thumbnail, error)

RenderKittyDirect builds a Kitty graphics thumbnail that is drawn by a direct placement at the cursor rather than by placeholder cells.

This exists for terminals that carry the graphics protocol but not the Unicode placeholder encoding — zellij 0.45 strips the combining marks that placeholders depend on, so RenderKitty draws nothing there while this works.

The trade-off is that the image is not part of the view. It is painted over the screen at whatever position the cursor held when Place was written, and it stays there until deleted. The caller must therefore:

  • reserve the area with Cells, which is blank text of exactly Cols x Rows, so the layout accounts for the space the image covers;
  • write Transmit once to load the image;
  • position the cursor and write Place on every frame that shows it;
  • write DeleteImage when the preview goes away, since overwriting the cells does not remove it.

cellW and cellH are the pixel dimensions of a terminal cell, used to choose the resampling resolution. Pass zero for either to use a default.

func (Thumbnail) Place added in v0.97.0

func (t Thumbnail) Place() string

Place returns the escape sequence that draws an already-transmitted image at the current cursor position, scaled into a Cols x Rows cell box.

It returns an empty string for thumbnails that do not need a placement, so callers can emit it unconditionally.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL