imagepreview

package
v0.115.1 Latest Latest
Warning

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

Go to latest
Published: Sep 30, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package imagepreview renders in-terminal thumbnails of images.

It offers two techniques, chosen by the caller from what the terminal accepts (see internal/ui/termgfx):

  • Half blocks, in this file: Unicode upper half-block characters (U+2580, "▀") with SGR colours stack two vertical pixels into one character cell, the foreground painting the top pixel and the background the bottom. The output is pure styled text, so it survives anywhere and needs no support beyond 256 colours.
  • Kitty graphics, in kitty.go: real pictures, either carried by Unicode placeholder cells that travel with the view text, or placed directly at the cursor for terminals that strip the combining marks placeholders are built from.

Half blocks remain the fallback, and the only renderer that needs nothing from the terminal but colour.

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 DeletePlacements added in v0.98.0

func DeletePlacements(id uint32) string

DeletePlacements returns the escape sequence that removes every placement of an image while keeping the transmitted data, so the image can be drawn again without being sent again.

A directly-placed image is painted over the screen and stays there until it is told to go; redrawing the cells underneath does not remove it. Anything that takes such an image off screen — scrolling it out of the viewport, covering it with a modal, clearing the transcript — must therefore drop its placements explicitly.

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

	// PixelWidth and PixelHeight are the dimensions of the transmitted image.
	// They are what makes a partial placement possible: a slice of the image is
	// named in pixels, so a caller must be able to convert a count of cell rows
	// into the pixel band those rows cover. See PlaceRows.
	PixelWidth, PixelHeight 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.

func (Thumbnail) PlaceRows added in v0.98.0

func (t Thumbnail) PlaceRows(skip, rows int) string

PlaceRows returns the escape sequence that draws a horizontal band of an already-transmitted image at the current cursor position: the first skip cell rows of the image are left out and the next rows rows are drawn.

Clipping is what lets a directly-placed image live in a scrolling list. The image is painted over the screen instead of being part of the view, so one whose top has scrolled out of the viewport would otherwise be drawn over whatever sits above it. Naming only the visible band keeps the picture aligned with the cells the list gave it, and lets it slide under the edge of the viewport one row at a time.

It returns an empty string when there is nothing left to draw, so callers can emit it unconditionally.

Jump to

Keyboard shortcuts

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