preview

Documentation

Overview

Package preview renders remote images inside a terminal.

Index

• Variables
• func ASCII(img image.Image, cols, rows int) string
• func BlockSize(src image.Rectangle, cols, rows int) (int, int)
• func Decode(r io.Reader) (image.Image, error)
• func Fit(src image.Rectangle, cols, rows int) (w, h int)
• func HalfBlocks(img image.Image, cols, rows int) string
• func Inline(img image.Image, mode Mode, cols, rows int) (s string, ok bool)
• func Render(img image.Image, mode Mode, cols, rows int) string
• func Resize(img image.Image, w, h int) *image.RGBA
• type Fetcher
  • func NewFetcher(dir string) *Fetcher
  • func (f *Fetcher) Cached(url string) (image.Image, bool)
  • func (f *Fetcher) Failed(url string) (error, bool)
  • func (f *Fetcher) Get(ctx context.Context, url string) (image.Image, error)
• type Mode
  • func Detect() Mode
  • func ParseMode(s string) (Mode, error)

Variables

var Modes = []string{"auto", "iterm", "kitty", "blocks", "ascii", "none"}

Modes lists every accepted --preview value.

Functions

func ASCII

func ASCII(img image.Image, cols, rows int) string

ASCII renders an image as monochrome characters, for terminals without 24-bit colour. One character is one pixel, so the source is squashed vertically to compensate for cells being about twice as tall as wide.

func BlockSize

func BlockSize(src image.Rectangle, cols, rows int) (int, int)

BlockSize reports the character grid HalfBlocks will actually produce, so callers can lay out around it without measuring escape codes.

func Decode

func Decode(r io.Reader) (image.Image, error)

Decode reads an image in any format the standard library supports.

func Fit

func Fit(src image.Rectangle, cols, rows int) (w, h int)

Fit returns the pixel size that fits src into a cols x rows character grid, assuming half-block rendering (2 image rows per text row) and terminal cells roughly twice as tall as wide.

func HalfBlocks

func HalfBlocks(img image.Image, cols, rows int) string

HalfBlocks renders an image as text using the upper-half-block character: the foreground colour is the top pixel and the background the bottom one, giving two vertical pixels per character cell. Works in any 24-bit-colour terminal, including inside a full-screen TUI, unlike inline image protocols.

func Inline

func Inline(img image.Image, mode Mode, cols, rows int) (s string, ok bool)

Inline renders an image using a terminal graphics protocol. The returned string is a single escape sequence that draws at the cursor and occupies `cols` columns; ok is false when mode is not a graphics protocol.

func Render

func Render(img image.Image, mode Mode, cols, rows int) string

Render draws an image with the given mode, resolving ModeAuto first. The result always fits in cols x rows character cells.

func Resize

func Resize(img image.Image, w, h int) *image.RGBA

Resize downscales img to w x h by averaging source pixels, which keeps thumbnails readable where nearest-neighbour would alias badly.

Types

type Fetcher

type Fetcher struct {
	Dir    string // disk cache directory; empty disables it
	Client *http.Client
	// contains filtered or unexported fields
}

Fetcher downloads and decodes thumbnails, caching the bytes on disk and the decoded images in memory so scrolling a result list stays instant.

func NewFetcher

func NewFetcher(dir string) *Fetcher

NewFetcher returns a Fetcher caching into dir.

func (*Fetcher) Cached

func (f *Fetcher) Cached(url string) (image.Image, bool)

Cached returns an already-decoded image without touching the network.

func (*Fetcher) Failed

func (f *Fetcher) Failed(url string) (error, bool)

Failed reports a previously recorded fetch error, so callers can show it instead of retrying in a redraw loop.

func (*Fetcher) Get

func (f *Fetcher) Get(ctx context.Context, url string) (image.Image, error)

Get returns the decoded thumbnail for url, fetching it if necessary.

type Mode

type Mode string

Mode is how a preview is drawn.

const (
	ModeAuto   Mode = "auto"
	ModeITerm  Mode = "iterm"  // iTerm2 inline images protocol
	ModeKitty  Mode = "kitty"  // Kitty graphics protocol (also Ghostty, WezTerm)
	ModeBlocks Mode = "blocks" // half-block characters, works everywhere
	ModeASCII  Mode = "ascii"
	ModeNone   Mode = "none"
)

func Detect

func Detect() Mode

Detect picks the best mode for the current terminal. Inline image protocols are only reported when the terminal actually implements them; everything else falls back to half-blocks, which need nothing but 24-bit colour.

func ParseMode

func ParseMode(s string) (Mode, error)

ParseMode validates a mode name.