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://domterm.org/
  • https://www.macterm.net/
• test wez/iterm img with
  • iterm2
  • https://www.macterm.net/

Notes

terminal features matrix

terminal	sixel	iTerm2 format	kitty format
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
terminology	\x1b[?64;1;9;15;18;21;22c
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
terminology	TERM_PROGRAM=terminology
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 IsItermCapable() bool
• func IsKittyCapable() bool
• func IsSixelCapable() (bool, error)
• func IsTmuxScreen() bool
• func ItermCopyFileInline(out io.Writer, in io.Reader, nLen int64) (E error)
• func ItermWriteImage(out io.Writer, iImg image.Image) error
• func KittyCopyPNGInline(out io.Writer, in io.Reader, opts KittyImgOpts) error
• func KittyWriteImage(out io.Writer, iImg image.Image, opts KittyImgOpts) error
• func KittyWritePNGLocal(out io.Writer, pngFileName string, opts KittyImgOpts) error
• func RequestTermAttributes() (sAttrs []int, E error)
• func SixelWriteImage(out io.Writer, pI *image.Paletted) (E error)
• func TermRequestResponse(fileIN, fileOUT *os.File, sRq string) (sRsp []byte, E error)
• type KittyImgOpts
  • func (o KittyImgOpts) ToHeader(opts ...string) string

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 (~)

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

Variables

var (
	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 IsItermCapable

func IsItermCapable() bool

NOTE: uses $TERM_PROGRAM, which isn't passed through tmux or ssh checks if iterm inline image protocol is supported

func IsKittyCapable

func IsKittyCapable() bool

checks if terminal supports kitty image protocols

func IsSixelCapable

func IsSixelCapable() (bool, error)

func IsTmuxScreen

func IsTmuxScreen() bool

func ItermCopyFileInline

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

func ItermWriteImage

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

Encode image using the iTerm2/WezTerm terminal image protocol:

https://iterm2.com/documentation-images.html

func KittyCopyPNGInline

func KittyCopyPNGInline(out io.Writer, in io.Reader, opts KittyImgOpts) error

Serialize PNG image from io.Reader into Kitty terminal in-band format.

func KittyWriteImage

func KittyWriteImage(out io.Writer, iImg image.Image, opts KittyImgOpts) error

Serialize image.Image into Kitty terminal in-band format.

func KittyWritePNGLocal

func KittyWritePNGLocal(out io.Writer, pngFileName string, opts KittyImgOpts) error

Display local PNG file - pngFileName must be directly accesssible from Kitty instance - pngFileName must be an absolute path

func RequestTermAttributes

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

func SixelWriteImage

func 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/

Since SIXEL does not support alpha transparency, any alpha > 0 will be treated as fully opaque.

SIXEL is a paletted format. To keep dependencies to a minimum, this only supports paletted images. Palette entries beyond index 255 are ignored. 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/

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.

Types

type KittyImgOpts

type KittyImgOpts struct {
	SrcX        uint32 // x=
	SrcY        uint32 // y=
	SrcWidth    uint32 // w=
	SrcHeight   uint32 // h=
	CellOffsetX uint32 // X= (pixel x-offset inside terminal cell)
	CellOffsetY uint32 // Y= (pixel y-offset inside terminal cell)
	DstCols     uint32 // c= (display width in terminal columns)
	DstRows     uint32 // r= (display height in terminal rows)
	ZIndex      int32  // z=
	ImageId     uint32 // i=
	ImageNo     uint32 // I=
	PlacementId uint32 // p=
}

func (KittyImgOpts) ToHeader

func (o KittyImgOpts) ToHeader(opts ...string) string