imgcat

command module
v0.0.0-...-d5b184a Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 1 Imported by: 0

README

imgcat - Terminal Image Viewer

A powerful command-line tool for displaying images in terminals using modern graphics protocols.

Features

  • Universal Protocol Support: Automatically detects and uses the best available protocol
    • 🐱 Kitty - Fast graphics with virtual images, z-index, compression
    • 🎨 Sixel - High-quality with palette optimization
    • 🍎 iTerm2 - Native inline images
    • 🧱 Halfblocks - Unicode fallback (works everywhere)
  • Advanced Image Processing: Smart scaling, dithering, positioning
  • Kitty Protocol Features: Virtual placement, layering, Unicode placeholders
  • Terminal Detection: Comprehensive protocol and capability detection

Installation

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

Or build from source:

cd cmd/imgcat
go build

Basic Usage

# Display an image
imgcat image.png

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

# Force a specific protocol
imgcat --protocol kitty image.png
imgcat --protocol sixel image.png

Protocol Detection

# Check what protocols your terminal supports
imgcat --detect

# Show Unicode positioning test grid
imgcat --test-grid

Sizing Options

# Character cell dimensions
imgcat -W 80 -H 40 image.png

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

Advanced Features

Kitty Protocol Features
# Virtual placement (transmit once, place multiple times)
imgcat --virtual image.png

# Layering with z-index
imgcat --z-index 5 --virtual image.png

# Compression and PNG mode
imgcat --compression --png image.png

# Unicode placeholders (for development)
imgcat --unicode image.png
Precise Positioning
# Two-step placement: transmit then position
imgcat --place --x 10 --y 5 --id "myimage" image.png

# With layering
imgcat --place --x 10 --y 5 --z-index 3 image.png
Image Processing
# Enable dithering
imgcat --dither photo.jpg

# Auto-clear after 1 second
imgcat --clear image.png
Terminal Multiplexer Support
# Force tmux passthrough mode
imgcat --tmux image.png

Command Reference

Required Arguments
  • <image> - Path to image file (PNG, JPEG, GIF, etc.)
Basic Options
Flag Short Description
--width -W Width in character cells
--height -H Height in character cells
--protocol -P Force protocol (auto, kitty, sixel, iterm2, halfblocks)
--scale -s Scale mode (none, fit, fill, stretch)
--verbose -V Enable verbose logging
Detection & Testing
Flag Description
--detect Show supported protocols and terminal info
--test-grid Display Unicode positioning test grid
Kitty Protocol Options
Flag Description
--virtual Use virtual placement mode
--z-index Set z-index for layering
--compression Enable zlib compression
--png Use PNG data transfer
--temp Use temporary file transfer
--image-num Set specific image number
--unicode Show Unicode placeholders
Positioning Options
Flag Short Description
--place Use two-step placement mode
--x -x X position in character cells
--y -y Y position in character cells
--id Custom image ID for placement
Other Options
Flag Short Description
--dither -D Enable dithering
--clear -c Clear image after 1 second
--tmux Force tmux passthrough mode

Examples

Basic Display
# Simple display
imgcat screenshot.png

# Sized to fit terminal width
imgcat --scale fit --width 120 photo.jpg
Protocol-Specific Usage
# Force Kitty protocol with virtual placement
imgcat --protocol kitty --virtual --z-index 2 overlay.png

# High-quality Sixel with dithering
imgcat --protocol sixel --dither artwork.png

# Fallback to halfblocks
imgcat --protocol halfblocks logo.png
Advanced Positioning
# Place image at specific coordinates
imgcat --place --x 20 --y 10 --id "background" bg.png

# Layer multiple images
imgcat --place --x 0 --y 0 --z-index 1 --id "bg" background.png
imgcat --place --x 10 --y 5 --z-index 5 --id "fg" foreground.png
Development & Testing
# Check terminal capabilities
imgcat --detect

# Test Unicode positioning
imgcat --test-grid

# Debug with verbose output
imgcat --verbose --protocol auto image.png

Terminal Compatibility

Full Support
  • Kitty - All features including virtual placement, z-index, compression
  • Ghostty - Full Kitty protocol compatibility
Standard Support
  • iTerm2 - Inline images with ECH clearing
  • WezTerm - Inline image protocol
  • Apple Terminal - Basic image support
  • Mintty - Windows terminal with image support
Sixel Support
  • XTerm - With Sixel support enabled
  • MLTerm - Built-in Sixel support
  • Konsole - Recent versions
Universal Fallback
  • Any terminal - Unicode halfblocks rendering (works everywhere)

Building

cd cmd/imgcat
go build -o imgcat

Development

Run tests:

go test -v

Debug mode:

imgcat --verbose --detect

License

MIT License - see LICENSE file for details.

Documentation

Overview

Copyright © 2024 blacktop

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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