termimg

README

go-termimg

Go terminal image package

Supported

Protocols

• iTerm2 Inline Images Protocol
• Kitty Terminal Graphics Protocol

Image Formats

• PNG
• JPEG
• WEBP

Getting Started

go get github.com/blacktop/go-termimg

Usage

ti, err := termimg.Open("path/to/your/image.png")
if err != nil {
    log.Fatal(err)
}
imgstr, err := ti.Render()
if err != nil {
    log.Fatal(err)
}
fmt.Println(imgstr)

imgcat demo tool

Install

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

Usage

imgcat path/to/your/image.png

TODO

• unicode placeholders
• sixel support
• RequestTermAttributes

License

MIT Copyright (c) 2024 blacktop

Documentation

Overview

Package termimg provides functionality to render images in terminal emulators that support inline image protocols, specifically the iTerm2 Inline Images Protocol and the Kitty Terminal Graphics Protocol.

This package automatically detects which protocol is supported by the current terminal and renders images accordingly. It supports PNG, JPEG, and WebP image formats.

Main features:

• Automatic detection of supported terminal image protocols
• Support for iTerm2 and Kitty image protocols
• Rendering of PNG, JPEG, and WebP images
• Simple API for rendering images in the terminal

Usage:

To use this package, simply call the RenderImage function with the path to your image:

ti, err := termimg.Open("path/to/your/image.png")
if err != nil {
    log.Fatal(err)
}
imgstr, err := ti.Render()
if err != nil {
	log.Fatal(err)
}
fmt.Println(imgstr)

The package will automatically detect the supported protocol and render the image using the appropriate method.

Note that this package requires a terminal that supports either the iTerm2 Inline Images Protocol or the Kitty Terminal Graphics Protocol. If neither protocol is supported, an error will be returned.

For more advanced usage, you can also use the DetectProtocol function to check which protocol is supported:

protocol := termimg.DetectProtocol()
switch protocol {
case termimg.ITerm2:
    fmt.Println("iTerm2 protocol supported")
case termimg.Kitty:
    fmt.Println("Kitty protocol supported")
default:
    fmt.Println("No supported protocol detected")
}

This package is designed to make it easy to add image rendering capabilities to terminal-based Go applications.

Index

• Constants
• Variables
• type KittyResponse
• type Protocol
  • func DetectProtocol() Protocol
  • func (p Protocol) String() string
  • func (p Protocol) Supported() string
• type TermImg
  • func NewTermImg(r io.Reader) (*TermImg, error)
  • func Open(imagePath string) (*TermImg, error)
  • func (ti *TermImg) AsJPEGBytes() ([]byte, error)
  • func (ti *TermImg) AsPNGBytes() ([]byte, error)
  • func (ti *TermImg) Clear() error
  • func (t *TermImg) Close() error
  • func (t *TermImg) Info() string
  • func (ti *TermImg) Print() error
  • func (ti *TermImg) Render() (string, error)

Constants

const (
	DATA_RGBA_32_BIT = ",f=32" // default
	DATA_RGBA_24_BIT = ",f=24"
	DATA_PNG         = ",f=100"

	COMPRESS_ZLIB = ",0=z"

	TRANSFER_DIRECT = ",t=d"
	TRANSFER_FILE   = ",t=f"
	TRANSFER_TEMP   = ",t=t"
	TRANSFER_SHARED = ",t=s"

	SUPPRESS_OK  = ",q=1"
	SUPPRESS_ERR = ",q=2"
)

const ESC_ERASE_DISPLAY = "\x1b[2J\x1b[0;0H"

Variables

var (
	ESCAPE = ""
	START  = ""
	CLOSE  = ""
)

var ErrEmptyResponse = fmt.Errorf("empty response")

Types

type KittyResponse

type KittyResponse struct {
	ID      string
	Message string
}

type Protocol

type Protocol int

const (
	Unsupported Protocol = iota
	ITerm2
	Kitty
)

func DetectProtocol

func DetectProtocol() Protocol

func (Protocol) String

func (p Protocol) String() string

func (Protocol) Supported

func (p Protocol) Supported() string

type TermImg

type TermImg struct {
	// contains filtered or unexported fields
}

func NewTermImg

func NewTermImg(r io.Reader) (*TermImg, error)

func Open

func Open(imagePath string) (*TermImg, error)

func (*TermImg) AsJPEGBytes

func (ti *TermImg) AsJPEGBytes() ([]byte, error)

func (*TermImg) AsPNGBytes

func (ti *TermImg) AsPNGBytes() ([]byte, error)

func (*TermImg) Clear

func (ti *TermImg) Clear() error

func (*TermImg) Close

func (t *TermImg) Close() error

func (*TermImg) Info

func (t *TermImg) Info() string

func (*TermImg) Print

func (ti *TermImg) Print() error

func (*TermImg) Render

func (ti *TermImg) Render() (string, error)