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
- 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
- test wez/iterm img with
- iterm2
- https://www.macterm.net/
Notes
terminal features matrix
| terminal | sixel | iTerm2 format | kitty format |
|---|---|---|---|
| ghostty | Y | ||
| iterm2 | Y | Y | |
| kitty | Y | ||
| rio | Y | 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 |
| ghostty | \x1b[?62;22c |
| guake | \x1b[?65;1;9c |
| iterm2 | \x1b[?62;4c |
| kitty | \x1b[?62;c |
| rio | \x1b[?62;4;6;22c |
| 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 |
| ghostty | \x1b[>1;10;0c |
| guake | \x1b[>65;5402;1c |
| iterm2 | \x1b[>0;95;0c |
| rio | \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" |
| ghostty | TERM="xterm-ghostty" |
| rio | TERM="rio" |
| 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 ItermCopyFileInlineWithOptions(out io.Writer, in io.Reader, opts ItermImgOpts) (E error)
- func ItermWriteImage(out io.Writer, iImg image.Image) error
- func ItermWriteImageWithOptions(out io.Writer, iImg image.Image, opts ItermImgOpts) 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 ItermImgOpts
- type KittyImgOpts
Constants ¶
const ( ITERM_IMG_HDR = "\x1b]1337;File=" 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 ¶ added in v1.1.0
func IsItermCapable ¶ added in v1.1.0
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 ¶ added in v1.1.0
func IsKittyCapable() bool
checks if terminal supports kitty image protocols
func IsSixelCapable ¶
func IsTmuxScreen ¶
func IsTmuxScreen() bool
func ItermCopyFileInline ¶ added in v1.1.0
func ItermCopyFileInlineWithOptions ¶ added in v1.1.2
func ItermWriteImageWithOptions ¶ added in v1.1.2
Encode image using the iTerm2/WezTerm terminal image protocol:
https://iterm2.com/documentation-images.html
func KittyCopyPNGInline ¶ added in v1.1.0
Serialize PNG image from io.Reader into Kitty terminal in-band format.
func KittyWriteImage ¶ added in v1.1.0
Serialize image.Image into Kitty terminal in-band format.
func KittyWritePNGLocal ¶ added in v1.1.0
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 SixelWriteImage ¶ added in v1.1.0
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 ¶ added in v1.0.3
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 ItermImgOpts ¶ added in v1.1.2
type ItermImgOpts struct {
// Filename. Defaults to "Unnamed file".
Name string
// Width to render. See notes below.
Width string
// Height to render. See notes below.
Height string
// File size in bytes. Optional; this is only used by the progress indicator.
Size int64
// If set, the file will be displayed inline. Otherwise, it will be downloaded
// with no visual representation in the terminal session.
DisplayInline bool
// If set, the image's inherent aspect ratio will not be respected.
IgnoreAspectRatio bool
}
func (ItermImgOpts) ToHeader ¶ added in v1.1.2
func (o ItermImgOpts) ToHeader() string
type KittyImgOpts ¶ added in v1.1.0
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 ¶ added in v1.1.0
func (o KittyImgOpts) ToHeader(opts ...string) string
Source Files