rasterm

README

rasterm

Encodes images to iTerm / Kitty / SIXEL (terminal) inline graphics protocols.

Supported Image Encodings

• Kitty
• iTerm2 / WezTerm
• Sixel

TODO

• mintty:
  • detection for iTerm format: https://github.com/mintty/mintty/issues/881
• iTerm2:
  • support: name, width, height, preserveAspectRatio options
• Kitty:
  • support animation
  • support image placement /dims
• perhaps query tmux directly: TMUX=/tmp/tmux-1000/default,3218,4
• improve terminal identification 19:VT340 ESC[>0c = 19;344:0c https://invisible-island.net/xterm/ctlseqs/ctlseqs-contents.html

TESTING

• test sixel with
  • https://github.com/liamg/aminal
  • https://domterm.org/
  • https://www.macterm.net/
• test wez/iterm img with
  • iterm2
  • https://www.macterm.net/
  • mintty

Notes

terminal features matrix

terminal	sixel	iTerm2 format	kitty format
aminal	Y
iterm2	Y	Y
kitty			Y
mintty	Y	Y
mlterm	Y	Y
putty
rlogin	Y	Y
wezterm	Y	Y
xterm	Y

known responses

CSI 0 c

terminal	response
apple terminal	\x1b[?1;2c
guake	\x1b[?65;1;9c
iterm2	\x1b[?62;4c
kitty	\x1b[?62;c
mintty	\x1b[?64;1;2;4;6;9;15;21;22;28;29c
mlterm	\x1b[?63;1;2;3;4;7;29c
putty	\x1b[?6c
rlogin	\x1b[?65;1;2;3;4;6;7;8;9;15;18;21;22;29;39;42;44c
st	\x1b[?6c
vimterm	\x1b[?1;2c
wez	\x1b[?65;4;6;18;22c
xfce	\x1b[?65;1;9c
xterm	\x1b[?63;1;2;4;6;9;15;22c

CSI > 0 c

terminal	response
apple terminal	\x1b[>1;95;0c
guake	\x1b[>65;5402;1c
iterm2	\x1b[>0;95;0c
kitty	\x1b[>1;4000;19c
mintty	\x1b[>77;30104;0c
mlterm	\x1b[>24;279;0c
putty	\x1b[>0;136;0c
rlogin	\x1b[>65;331;0c
st	NO RESPONSE
vimterm	\x1b[>0;100;0c
wez	\x1b[>0;0;0c
xfce	\x1b[>65;5402;1c
xterm	\x1b[>19;344;0c

identifications

terminal	values
apple terminal	TERM_PROGRAM="Apple_Terminal"
apple terminal	__CFBundleIdentifier="com.apple.Terminal"
guake
iterm2	LC_TERMINAL="iTerm2"
kitty	TERM="xterm-kitty"
mintty	TERM="mintty"
mlterm
putty
rlogin
st
vimterm	VIM_TERMINAL is set
wez	TERM_PROGRAM="wezterm"
xfce
xterm

opinions

• Sixel is a primitive and wasteful format. Most sixel terminals also support the iTerm2 format--fewer bytes, full color instead of paletted, and no pixel re-processing required. Much better!

go stuff

go tool pprof -http=:8080 ./name.prof
godoc -http=:8099 -goroot="$HOME/go"
go test -v
go mod tidy
https://blog.golang.org/pprof

more reading

• kitty inline images: https://sw.kovidgoyal.net/kitty/graphics-protocol.html
• iterm2 inline images: https://iterm2.com/documentation-images.html
• xterm ctl seqs: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
• sixel ctl seqs: https://vt100.net/docs/vt3xx-gp/chapter14.html
• libsixel: https://saitoha.github.io/libsixel/

Documentation

Index

• Constants
• Variables
• func GetEnvIdentifiers() map[string]string
• func GetTtyPath(pF *os.File) (string, error)
• func IsSixelCapable() (bool, error)
• func IsTermItermWez() bool
• func IsTermKitty() bool
• func IsTmuxScreen() bool
• func RequestTermAttributes() (sAttrs []int, E error)
• func TermRequestResponse(fileIN, fileOUT *os.File, sRq string) (sRsp []byte, E error)
• func TmuxOscOpenClose(opn, cls string) (string, string)
• type CustomWriFunc
• type Settings
  • func (S Settings) ItermCopyFileInline(out io.Writer, in io.Reader, nLen int64) (E error)
  • func (S Settings) ItermWriteImage(out io.Writer, iImg image.Image) error
  • func (S Settings) KittyCopyPNGInline(out io.Writer, in io.Reader, nLen int64) (E error)
  • func (S Settings) KittyWriteImage(out io.Writer, iImg image.Image) error
  • func (S Settings) SixelWriteImage(out io.Writer, pI *image.Paletted) (E error)
• type WriteChunker
  • func NewWriteChunker(iWri io.Writer, chunkSize int) WriteChunker
  • func (pC *WriteChunker) Flush() (E error)
  • func (pC *WriteChunker) Write(src []byte) (int, error)

Constants

const (
	ITERM_IMG_HDR = "\x1b]1337;File=inline=1"
	ITERM_IMG_FTR = "\a"
)

const (
	KITTY_IMG_HDR = "\x1b_G"
	KITTY_IMG_FTR = "\x1b\\"
)

const (
	SIXEL_MIN byte = 0x3f
	SIXEL_MAX byte = 0x7e
)

NOTE: valid sixel encodeds are in range 0x3F (?) TO 0x7E (~)

Variables

var (
	ESC_ERASE_DISPLAY = "\x1b[2J\x1b[0;0H"
	E_NON_TTY         = errors.New("NON TTY")
	E_TIMED_OUT       = errors.New("TERM RESPONSE TIMED OUT")
)

Functions

func GetEnvIdentifiers

func GetEnvIdentifiers() map[string]string

func GetTtyPath

func GetTtyPath(pF *os.File) (string, error)

func IsSixelCapable

func IsSixelCapable() (bool, error)

func IsTermItermWez

func IsTermItermWez() bool

NOTE: uses $TERM_PROGRAM, which isn't passed through

tmux or ssh

func IsTermKitty

func IsTermKitty() bool

NOTE: uses $TERM, which is overwritten by tmux

func IsTmuxScreen

func IsTmuxScreen() bool

func RequestTermAttributes

func RequestTermAttributes() (sAttrs []int, E error)

func TermRequestResponse

func TermRequestResponse(fileIN, fileOUT *os.File, sRq string) (sRsp []byte, E error)

Handles request/response terminal control sequences like <ESC>[0c

STDIN & STDOUT are parameterized for special cases. os.Stdin & os.Stdout are usually sufficient.

`sRq` should be the request control sequence to the terminal.

NOTE: only captures up to 1KB of response

NOTE: when println debugging the response, probably want to go-escape it, like:

fmt.Printf("%#v\n", sRsp)

since most responses begin with <ESC>, which the terminal treats as another control sequence rather than text to output.

func TmuxOscOpenClose

func TmuxOscOpenClose(opn, cls string) (string, string)

transforms given open/close terminal escapes to pass through tmux to parent terminal

Types

type CustomWriFunc

type CustomWriFunc func(io.Writer, []byte) (int, error)

Used by WriteChunker to optionally transform chunks before sending them on to the underlying io.Writer.

type Settings

type Settings struct {
	EscapeTmux    bool
	X, Y          int
	Rows, Columns int
	MoveCursor    bool
}

func (Settings) ItermCopyFileInline

func (S Settings) ItermCopyFileInline(out io.Writer, in io.Reader, nLen int64) (E error)

func (Settings) ItermWriteImage

func (S Settings) ItermWriteImage(out io.Writer, iImg image.Image) error

Encode image using the iTerm2/WezTerm terminal image protocol: https://iterm2.com/documentation-images.html

func (Settings) KittyCopyPNGInline

func (S Settings) KittyCopyPNGInline(out io.Writer, in io.Reader, nLen int64) (E error)

Encode raw PNG data into Kitty terminal format

func (Settings) KittyWriteImage

func (S Settings) KittyWriteImage(out io.Writer, iImg image.Image) error

Encode image using the Kitty terminal graphics protocol: https://sw.kovidgoyal.net/kitty/graphics-protocol.html

func (Settings) SixelWriteImage

func (S Settings) SixelWriteImage(out io.Writer, pI *image.Paletted) (E error)

Encodes a paletted image into DECSIXEL format. Forked & heavily modified from https://github.com/mattn/go-sixel/

This does not support transparency. Alpha values in the palette will be ignored.

SIXEL is a paletted format. To keep dependencies to a minimum, this only supports paletted images. To handle non-paletted images, please pre-dither from the caller.

For more information on DECSIXEL format:

https://www.vt100.net/docs/vt3xx-gp/chapter14.html
https://saitoha.github.io/libsixel/

type WriteChunker

type WriteChunker struct {
	CustomWriFunc
	// contains filtered or unexported fields
}

Wraps an io.Writer interface to buffer/flush in chunks that are `chunkSize` bytes long. Optional `CustomWriFunc` in struct allows for additional []byte processing before sending each chunk to the underlying writer. Currently used for encoding to Kitty terminal's image format.

func NewWriteChunker

func NewWriteChunker(iWri io.Writer, chunkSize int) WriteChunker

func (*WriteChunker) Flush

func (pC *WriteChunker) Flush() (E error)

func (*WriteChunker) Write

func (pC *WriteChunker) Write(src []byte) (int, error)