rasterm

package module
v0.0.0-...-0066f2a Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2024 License: MIT Imports: 16 Imported by: 0

README

rasterm

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

GoDoc

rasterm sample output

Supported Image Encodings

  • Kitty
  • iTerm2 / WezTerm
  • Sixel

TODO

TESTING

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

Documentation

Index

Constants

View Source 
const (
	ITERM_IMG_HDR = "\x1b]1337;File="
	ITERM_IMG_FTR = "\a"
)
View Source 
const (
	KITTY_IMG_HDR = "\x1b_G"
	KITTY_IMG_FTR = "\x1b\\"
)
View Source 
const (
	SIXEL_MIN byte = 0x3f
	SIXEL_MAX byte = 0x7e
)

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

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

Variables

View Source 
var (
	E_NON_TTY   = errors.New("NON TTY")
	E_TIMED_OUT = errors.New("TERM RESPONSE TIMED OUT")
)

Functions

func DecodeGIF 

func DecodeGIF(r io.Reader) ([]image.Image, []int)

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 ItermCopyFileInlineWithOptions 

func ItermCopyFileInlineWithOptions(out io.Writer, in io.Reader, opts ItermImgOpts) (E error)

func ItermWriteImage 

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

func ItermWriteImageWithOptions 

func ItermWriteImageWithOptions(out io.Writer, iImg image.Image, opts ItermImgOpts) error

Encode image using the iTerm2/WezTerm terminal image protocol: 

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

func KittyClean 

func KittyClean(out io.Writer, opts KittyImgOpts) error

func KittyControlAnimation 

func KittyControlAnimation(out io.Writer, opts KittyImgOpts, delays []int) error

func KittyWriteFrame 

func KittyWriteFrame(out io.Writer, frame image.Image, opts KittyImgOpts, delay int) error

func KittyWriteGIF 

func KittyWriteGIF(out io.Writer, gifReader io.Reader, opts KittyImgOpts) error

Serialize GIF image 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 KittyWritePngReader 

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

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

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 ItermImgOpts 

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 

func (o ItermImgOpts) ToHeader() string

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.