README
¶
kittyimg
kittyimg is a Go library that allows to display images in terminal emulators implementing kitty's terminal graphics protocol.
✨ Features
A basic API
(Fprint,
Fprintln,
Transcode) allows to display an image (loaded with stdlib's image package) at the cursor position.
go get github.com/dolmen-go/kittyimg@latest
A command-line tool (icat) is provided.
go install github.com/dolmen-go/kittyimg/cmd/icat@latest
icat <image> works the same as Kitty's command kitten icat --transfer-mode=stream --align=left <image>.
🏗️ Status
Production ready.
🔄 See also
The Go Playground has support for displaying images with its own protocol: IMAGE: prefix followed by base64 image file data.
Display tools for images on terminals:
- tycat:
Similar tool to
icat, but for the Enlightenment Terminology app (which uses a different terminal protocol). - timg
- viu
- chafa
🛡️ License
Copyright 2021-2026 Olivier Mengué
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation
¶
Overview ¶
Package kittyimg provides utilities to show image in a graphic terminal emulator supporting kitty's "terminal graphics protocol".
Example ¶
package main
import (
"bytes"
"image"
"os"
"github.com/dolmen-go/kittyimg"
_ "image/png"
)
// Source: https://go.dev/play/p/XN6x3L23Vok
var favicon = []byte{
0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n',
0, 0, 0, 13, 'I', 'H', 'D', 'R',
0x00, 0x00, 0x00, 0x10, 0x00, 0x00, 0x00, 0x0f, 0x04, 0x03, 0x00, 0x00, 0x00,
0x1f, 0x5d, 0x52, 0x1c,
0, 0, 0, 15, 'P', 'L', 'T', 'E',
0x7a, 0xdf, 0xfd, 0xfd, 0xff, 0xfc, 0x39, 0x4d, 0x52, 0x19, 0x16, 0x15, 0xc3, 0x8d, 0x76,
0xc7, 0x36, 0x2c, 0xf5,
0, 0, 0, 64, 'I', 'D', 'A', 'T',
0x08, 0xd7, 0x95, 0xc9, 0xd1, 0x0d, 0xc0, 0x20, 0x0c, 0x03, 0xd1, 0x23, 0x5d, 0xa0, 0x49, 0x17,
0x20, 0x4c, 0xc0, 0x10, 0xec, 0x3f, 0x53, 0x8d, 0xc2, 0x02, 0x9c, 0xfc, 0xf1, 0x24, 0xe3, 0x31,
0x54, 0x3a, 0xd1, 0x51, 0x96, 0x74, 0x1c, 0xcd, 0x18, 0xed, 0x9b, 0x9a, 0x11, 0x85, 0x24, 0xea,
0xda, 0xe0, 0x99, 0x14, 0xd6, 0x3a, 0x68, 0x6f, 0x41, 0xdd, 0xe2, 0x07, 0xdb, 0xb5, 0x05, 0xca,
0xdb, 0xb2, 0x9a, 0xdd,
0, 0, 0, 0, 'I', 'E', 'N', 'D', 0xae, 0x42, 0x60, 0x82,
}
func main() {
f := bytes.NewReader(favicon)
img, _, err := image.Decode(f)
if err != nil {
panic(err)
}
kittyimg.Fprintln(os.Stdout, img)
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Transcode ¶
Transcode transforms the image file into the Kitty protocol representation for display on a terminal.
The supported input image formats depend on the formats registered with the image framework (see image/png, image/gif, image/jpeg).
Example (Gif) ¶
package main
import (
"embed"
"os"
"github.com/dolmen-go/kittyimg"
_ "image/gif"
)
//go:embed dolmen.gif
var files embed.FS
func main() {
f, err := files.Open("dolmen.gif")
if err != nil {
panic(err)
}
defer f.Close()
kittyimg.Transcode(os.Stdout, f)
os.Stdout.WriteString("\n")
}
Output:
Example (Png) ¶
package main
import (
"bytes"
"os"
"github.com/dolmen-go/kittyimg"
_ "image/png"
)
// Source: https://go.dev/play/p/XN6x3L23Vok
var favicon = []byte{
0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n',
0, 0, 0, 13, 'I', 'H', 'D', 'R',
0x00, 0x00, 0x00, 0x10, 0x00, 0x00, 0x00, 0x0f, 0x04, 0x03, 0x00, 0x00, 0x00,
0x1f, 0x5d, 0x52, 0x1c,
0, 0, 0, 15, 'P', 'L', 'T', 'E',
0x7a, 0xdf, 0xfd, 0xfd, 0xff, 0xfc, 0x39, 0x4d, 0x52, 0x19, 0x16, 0x15, 0xc3, 0x8d, 0x76,
0xc7, 0x36, 0x2c, 0xf5,
0, 0, 0, 64, 'I', 'D', 'A', 'T',
0x08, 0xd7, 0x95, 0xc9, 0xd1, 0x0d, 0xc0, 0x20, 0x0c, 0x03, 0xd1, 0x23, 0x5d, 0xa0, 0x49, 0x17,
0x20, 0x4c, 0xc0, 0x10, 0xec, 0x3f, 0x53, 0x8d, 0xc2, 0x02, 0x9c, 0xfc, 0xf1, 0x24, 0xe3, 0x31,
0x54, 0x3a, 0xd1, 0x51, 0x96, 0x74, 0x1c, 0xcd, 0x18, 0xed, 0x9b, 0x9a, 0x11, 0x85, 0x24, 0xea,
0xda, 0xe0, 0x99, 0x14, 0xd6, 0x3a, 0x68, 0x6f, 0x41, 0xdd, 0xe2, 0x07, 0xdb, 0xb5, 0x05, 0xca,
0xdb, 0xb2, 0x9a, 0xdd,
0, 0, 0, 0, 'I', 'E', 'N', 'D', 0xae, 0x42, 0x60, 0x82,
}
func main() {
f := bytes.NewReader(favicon)
kittyimg.Transcode(os.Stdout, f)
os.Stdout.WriteString("\n")
}
Output:
Types ¶
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder is an image.Image encoder, like image/png.Encoder.
Using an Encoder explicitely allows to reuse resources (memory buffers) when encoding multiple images sequentially.
Source Files
Directories