Skip to content

blacktop/go-termimg

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

148 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Fallback logo

Modern terminal image library for Go

Features

Universal Protocol Support

  • 🐱 Kitty - Fast graphics with virtual images, z-index, compression
  • 🎨 Sixel - High-quality with palette optimization and dithering
  • 🍎 iTerm2 - Native inline images with ECH clearing
  • 🧱 Halfblocks - Unicode fallback (works everywhere)

Rich Image Processing

  • Smart scaling (fit, fill, stretch, none)
  • Advanced dithering (Stucki, Floyd-Steinberg)
  • Quality vs speed control
  • TUI framework integration (Bubbletea)

Advanced Features

  • Automatic protocol detection with fallbacks
  • Terminal font size detection via CSI queries
  • Tmux passthrough support
  • Optimized font size caching

Warning

Kitty Unicode placeholder/relative placement features are currently under construction and not recommended for production use.

Supported Formats

  • PNG, JPEG, GIF
  • Any format supported by Go's image package
  • WebP support planned

Installation

go get github.com/blacktop/go-termimg

Getting Started

Basic Usage

package main

import "github.com/blacktop/go-termimg"

func main() {
    // Simple one-liner
    termimg.PrintFile("image.png")

    // Or with control
    img, _ := termimg.Open("image.png")
    img.Width(50).Height(25).Print()
}

API

// Auto-detect best protocol and render
rendered, err := termimg.Open("image.png").
    Width(80).
    Height(40).
    Scale(termimg.ScaleFit).
    Render()

Protocol-Specific Features

// Kitty with virtual images and z-index (experimental)
termimg.Open("overlay.png").
    Protocol(termimg.Kitty).
    Virtual(true).
    ZIndex(5).
    Print()

// Sixel with dithering
termimg.Open("photo.jpg").
    Protocol(termimg.Sixel).
    Dither(true).
    DitherMode(termimg.DitherStucki).
    Print()

TUI Integration

import tea "github.com/charmbracelet/bubbletea"

type model struct {
    widget *termimg.ImageWidget
}

func (m model) View() string {
    rendered, _ := m.widget.Render()
    return rendered
}

func main() {
    img := termimg.NewImageWidgetFromFile("image.png")
    img.SetSize(50, 25).SetProtocol(termimg.Auto)

    p := tea.NewProgram(model{widget: img})
    p.Run()
}

Command Line Tools

imgcat - Terminal Image Viewer

Install:

go install github.com/blacktop/go-termimg/cmd/imgcat@latest

Basic usage:

# Display an image
imgcat image.png

# With specific protocol and size
imgcat -W 100 -H 50 --protocol kitty image.png

# Virtual placement with positioning (Kitty only)
imgcat --virtual --x 10 --y 5 --z-index 3 image.png

# Test terminal capabilities
imgcat --detect

# Show Unicode test grid
imgcat --test-grid

Advanced options:

# Compression and PNG mode (Kitty)
imgcat --compression --png image.png

# Dithering
imgcat --dither photo.jpg

# Scale modes
imgcat --scale fit image.png    # Fit within terminal
imgcat --scale fill image.png   # Fill terminal, crop if needed
imgcat --scale none image.png   # No scaling

gallery - Interactive TUI Demo

Install and run:

go install github.com/blacktop/go-termimg/cmd/gallery@latest
gallery

Interactive features:

  • File navigation (↑/↓ or k/j keys, page up/down, home/end)
  • Virtual mode toggle (v key - Kitty only)
  • Grid view toggle (g key)
  • Auto-detection of best terminal protocol

Protocol Detection

// Auto-detect best available protocol
protocol := termimg.DetectProtocol()

// Check specific protocol support
if termimg.KittySupported() {
    // Use Kitty features
}

// Get detailed terminal features
features := termimg.QueryTerminalFeatures()
fmt.Printf("Font size: %dx%d\n", features.FontWidth, features.FontHeight)

Performance

Performance benchmarks for different protocols:

  • Halfblocks: ~800µs (fastest, works everywhere)
  • Kitty: ~2.5ms (efficient, modern terminals)
  • iTerm2: ~2.5ms (fast, macOS)
  • Sixel: ~90ms (high quality, slower)

Font size detection is cached to avoid repeated terminal queries.

Running Examples

The cmd/ directory contains several example programs:

# Image viewer
cd cmd/imgcat/
go run main.go ../../test/image.png --id 123 --place --x 5 --y 10

# Interactive gallery
cd cmd/gallery/
go run main.go

# Terminal info
cd cmd/terminfo/
go run main.go

License

MIT Copyright (c) 2024-2025 blacktop

About

Modern terminal image library for Go

Topics

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors