Examples on KGP

Basic Image Display

Mon, 01 Jan 0001 00:00:00 +0000

PNG from File

 go
 
 
package main

import (
 "fmt"
 "os"
 "github.com/SerenaFontaine/kgp"
)

func main() {
 data, err := os.ReadFile("image.png")
 if err != nil {
 panic(err)
 }

 cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(data).
 Build()

 fmt.Print(cmd.Encode())
}

RGBA with Dimensions

PNG embeds dimensions; RGB and RGBA require explicit dimensions.

 go
 
 
rgbaData := kgp.SolidColorImage(800, 600, 255, 0, 0, 255) // Red

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatRGBA).
 Dimensions(800, 600).
 TransmitDirect(rgbaData).
 Build()
fmt.Print(cmd.Encode())

RGB (24-bit, no alpha)

 go
 
 
import "image"

img := loadYourImage()
rgbData := kgp.ImageToRGB(img)
width, height := img.Bounds().Dx(), img.Bounds().Dy()

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatRGB).
 Dimensions(width, height).
 TransmitDirect(rgbData).
 Build()
fmt.Print(cmd.Encode())

From image.Image (Convenience)

 go
 
 
img, _ := image.Decode(file)
cmd, err := kgp.TransmitImage(img)
if err != nil {
 panic(err)
}
fmt.Print(cmd.Encode())

Multiple Placements

Mon, 01 Jan 0001 00:00:00 +0000

Transmit once, display many times. Saves bandwidth and memory.

Transmit Then Put

 go
 
 
// 1. Transmit image (no display)
transmitCmd := kgp.NewTransmit().
 ImageID(10).
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 Build()
fmt.Print(transmitCmd.Encode())

// 2. Create placements
placement1 := kgp.NewPut(10).
 DisplaySize(20, 15).
 ZIndex(1).
 Build()
fmt.Print(placement1.Encode())

placement2 := kgp.NewPut(10).
 DisplaySize(10, 7).
 CellOffset(5, 5).
 Build()
fmt.Print(placement2.Encode())

Same Image, Different Sizes

 go
 
 
transmitCmd := kgp.NewTransmit().
 ImageID(100).
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 Build()
fmt.Print(transmitCmd.Encode())

// Small
fmt.Print(kgp.NewPut(100).DisplaySize(5, 5).Build().Encode())
fmt.Print(" ")

// Medium
fmt.Print(kgp.NewPut(100).DisplaySize(8, 8).Build().Encode())
fmt.Print(" ")

// Large
fmt.Print(kgp.NewPut(100).DisplaySize(12, 12).Build().Encode())
fmt.Println()

Placement IDs for Targeting

Use PlacementID when you need to delete or update specific placements.

Cropping and Scaling

Mon, 01 Jan 0001 00:00:00 +0000

Source Rect (Crop)

Display only a portion of the source image.

 go
 
 
// Display top-left 400×300 region
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 SourceRect(0, 0, 400, 300).
 Build()
fmt.Print(cmd.Encode())

Display Size (Scale)

Control how many terminal cells the image occupies.

 go
 
 
// Crop center 100×100, display in 10×10 cells
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(largePNG).
 SourceRect(50, 50, 100, 100).
 DisplaySize(10, 10).
 Build()
fmt.Print(cmd.Encode())

Put with Crop and Scale

 go
 
 
// Already transmitted image ID 20
place := kgp.NewPut(20).
 SourceRect(100, 100, 200, 200). // Crop
 DisplaySize(15, 15). // Scale
 Build()
fmt.Print(place.Encode())

Cell Offset

Position the image within the starting cell.

Z-Index Layering

Mon, 01 Jan 0001 00:00:00 +0000

Control whether images appear above or below text.

Negative z-index: below text (background)
Positive z-index: above text (overlay)
Zero: default (implementation-defined)

Background Image

 go
 
 
bgCmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(bgData).
 ZIndex(-10).
 CursorMovement(false).
 Build()
fmt.Print(bgCmd.Encode())
fmt.Println("Text rendered on top of the image")

Foreground Overlay

 go
 
 
fgCmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(iconData).
 ZIndex(10).
 Build()
fmt.Print(fgCmd.Encode())

Layered Composition

 go
 
 
// Back layer
fmt.Print(kgp.NewTransmitDisplay().
 ImageID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(bgData).
 ZIndex(-2).
 CursorMovement(false).
 Build().Encode())

// Middle layer
fmt.Print(kgp.NewTransmitDisplay().
 ImageID(2).
 Format(kgp.FormatPNG).
 TransmitDirect(midData).
 ZIndex(-1).
 CursorMovement(false).
 Build().Encode())

// Front layer
fmt.Print(kgp.NewTransmitDisplay().
 ImageID(3).
 Format(kgp.FormatPNG).
 TransmitDirect(fgData).
 ZIndex(1).
 Build().Encode())

Deletion

Mon, 01 Jan 0001 00:00:00 +0000

Delete All Placements

Keep image data in memory for reuse:

 go
 
fmt.Print(kgp.DeleteAll().Encode())

Free everything:

 go
 
fmt.Print(kgp.DeleteAllFree().Encode())

Delete by Image ID

 go
 
 
fmt.Print(kgp.DeleteImage(10).Encode()) // Preserve data
fmt.Print(kgp.DeleteImageFree(10).Encode()) // Free memory

Delete at Cursor

 go
 
fmt.Print(kgp.DeleteAtCursor().Encode())

Delete by Z-Index

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByZIndex).
 ZIndex(5).
 Build()
fmt.Print(cmd.Encode())

Delete by Placement ID

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByPlacementID).
 ImageID(100).
 PlacementID(2).
 Build()
fmt.Print(cmd.Encode())

Delete by Cell Coordinates

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByCell).
 Cell(10, 5).
 Build()
fmt.Print(cmd.Encode())

Delete by Image ID Range

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByIDRange).
 IDRange(10, 50).
 Build()
fmt.Print(cmd.Encode())

Free memory for a range of image IDs:

Animation

Mon, 01 Jan 0001 00:00:00 +0000

Basic Animation Flow

Transmit base frame (or first frame)
Add frames with NewFrame
Create placement
Control playback with NewAnimate or helpers

Transmit Base, Add Frames

 go
 
 
// Base image (frame 0)
baseCmd := kgp.NewTransmit().
 ImageID(20).
 Format(kgp.FormatPNG).
 TransmitDirect(frame0Data).
 Build()
fmt.Print(baseCmd.Encode())

// Frame 1
frame1Cmd := kgp.NewFrame(20).
 FrameData(frame1Data).
 Gap(100).
 Build()
fmt.Print(frame1Cmd.Encode())

// Frame 2 with composition
frame2Cmd := kgp.NewFrame(20).
 Format(kgp.FormatRGBA).
 Dimensions(80, 80).
 FrameData(frame2Data).
 Gap(100).
 BackgroundFrame(0).
 Composition(kgp.CompositionBlend).
 Build()
fmt.Print(frame2Cmd.Encode())

Playback Control

 go
 
 
// Play once
fmt.Print(kgp.PlayAnimation(20).Encode())

// Loop infinitely
fmt.Print(kgp.PlayAnimationLoop(20).Encode())

// Stop at current frame
fmt.Print(kgp.StopAnimation(20).Encode())

// Reset to first frame
fmt.Print(kgp.ResetAnimation(20).Encode())

Custom Loop Count

Loop count follows the Kitty protocol: 0 is ignored, 1 means infinite, and N>1 loops N-1 times.

Relative Positioning

Mon, 01 Jan 0001 00:00:00 +0000

Place child images relative to a parent placement. Useful for overlays, badges, and anchored UI elements.

Parent and Child

 go
 
 
// Parent image
parentCmd := kgp.NewTransmitDisplay().
 ImageID(100).
 PlacementID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(parentData).
 Build()
fmt.Print(parentCmd.Encode())

// Child: 10 cells right, 0 cells down from parent
childCmd := kgp.NewPut(100).
 PlacementID(2).
 RelativeTo(100, 1, 10, 0).
 Build()
fmt.Print(childCmd.Encode())

RelativeTo Parameters

 go
 
RelativeTo(parentImageID, parentPlacementID uint32, offsetH, offsetV int)

parentImageID — Image ID of the parent
parentPlacementID — Placement ID of the parent
offsetH — Horizontal offset in cells (positive = right)
offsetV — Vertical offset in cells (positive = down)

Badge on Avatar

 go
 
 
// Avatar (parent)
avatarCmd := kgp.NewTransmitDisplay().
 ImageID(50).
 PlacementID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(avatarData).
 Build()
fmt.Print(avatarCmd.Encode())

// Transmit badge (no display)
fmt.Print(kgp.NewTransmit().
 ImageID(51).
 Format(kgp.FormatPNG).
 TransmitDirect(badgeData).
 Build().Encode())

// Badge (child) — top-right of avatar
badgeCmd := kgp.NewPut(51).
 PlacementID(1).
 DisplaySize(2, 2).
 RelativeTo(50, 1, 8, -1).
 Build()
fmt.Print(badgeCmd.Encode())

Chunked Transmission

Mon, 01 Jan 0001 00:00:00 +0000

For large images or remote connections (e.g., SSH), split the payload into chunks. The terminal reassembles them.

Basic Chunking

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(largePNGData).
 Build()

chunks := cmd.EncodeChunked(4096)
for _, chunk := range chunks {
 fmt.Print(chunk)
}

Chunk Size Requirements

Maximum: 4096 bytes per chunk
Alignment: Must be divisible by 4 (base64 encoding)

 go
 
 
// Valid
cmd.EncodeChunked(4096)
cmd.EncodeChunked(2048)
cmd.EncodeChunked(1024)

// Invalid — will panic
cmd.EncodeChunked(4097) // > 4096
cmd.EncodeChunked(1002) // not divisible by 4

When to Use Chunking

Large PNG or RGBA payloads that exceed terminal limits
Slow or unreliable connections (SSH, serial)
Some terminal implementations enforce payload size limits

Compression

Mon, 01 Jan 0001 00:00:00 +0000

ZLIB compression reduces payload size for raw RGB/RGBA data. PNG is already compressed.

Compress RGBA

 go
 
 
rgbaData := kgp.SolidColorImage(800, 600, 255, 0, 0, 255)
compressed, err := kgp.CompressZlib(rgbaData)
if err != nil {
 panic(err)
}

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatRGBA).
 Dimensions(800, 600).
 Compress().
 TransmitDirect(compressed).
 Build()
fmt.Print(cmd.Encode())

TransmitImageRGBA Helper

 go
 
 
// With compression
cmd, err := kgp.TransmitImageRGBA(img, true)
if err != nil {
 panic(err)
}
fmt.Print(cmd.Encode())

// Without compression
cmd, err = kgp.TransmitImageRGBA(img, false)

When to Compress

Raw RGBA/RGB: Often benefits from compression, especially for gradients or similar colors
PNG: Already compressed; no need for Compress()
Solid colors: Compression may not help much; test for your use case

File and Shared Memory Transmission

Mon, 01 Jan 0001 00:00:00 +0000

Alternatives to embedding data directly in escape sequences.

Transmit from File

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitFile("/path/to/image.png").
 Build()
fmt.Print(cmd.Encode())

File with Offset and Size

Read a byte range from the file:

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitFileWithOffset("/path/to/image.png", 1024, 50000).
 Build()
fmt.Print(cmd.Encode())

Temporary File

The terminal deletes the file after reading. Path must contain tty-graphics-protocol for security.

 go
 
 
path := "/tmp/tty-graphics-protocol-" + strconv.Itoa(os.Getpid()) + ".png"
_ = os.WriteFile(path, pngData, 0644)
defer os.Remove(path)

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitTemp(path). // panics if path is invalid
 Build()
fmt.Print(cmd.Encode())

Temporary File (Non-Panicking)

 go
 
 
path := "/tmp/tty-graphics-protocol-" + strconv.Itoa(os.Getpid()) + ".png"
_ = os.WriteFile(path, pngData, 0644)
defer os.Remove(path)

tb := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG)

if _, err := tb.TryTransmitTemp(path); err != nil {
 log.Fatal(err)
}

cmd := tb.
 Build()
fmt.Print(cmd.Encode())

Shared Memory (POSIX)

Most efficient for local applications. Create a shared memory object and pass its name and size.

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

Parse terminal responses to detect and handle errors.

Basic Parsing

 go
 
 
resp, err := kgp.ParseResponse(responseStr)
if err != nil {
 fmt.Println("Invalid response format:", err)
 return
}

if resp.Success {
 fmt.Printf("Image ID: %d, Placement ID: %d\n", resp.ImageID, resp.PlacementID)
} else {
 fmt.Printf("Error: %s - %s\n", resp.ErrorCode, resp.Message)
}

Error Code Handling

 go
 
 
resp, err := kgp.ParseResponse(responseStr)
if err != nil {
 return err
}

if !resp.Success {
 switch resp.ErrorCode {
 case "ENOSPC":
 // Storage quota exceeded — delete old images
 fmt.Print(kgp.DeleteAllFree().Encode())
 // Retry...
 case "ENOENT":
 // Image not found — may have been deleted
 case "EINVAL":
 // Invalid parameters — check your command
 case "EIO":
 // I/O error — terminal problem
 default:
 fmt.Printf("Unknown error: %s - %s\n", resp.ErrorCode, resp.Message)
 }
}

Suppressing OK Responses

Reduce response traffic when you don’t need confirmation:

Demo Application

Mon, 01 Jan 0001 00:00:00 +0000

The examples/demo package provides an interactive walkthrough of KGP features.

Running the Demo

 bash
 
 
cd examples/demo
go run .

Place a file named sf.png in the demo directory for the external PNG loading demo.

Demo Sequence

Image Formats — PNG, RGBA, RGB
Compression — ZLIB compressed RGBA
External PNG — Load from sf.png
Cropping and Scaling — Source rect and display size
Multiple Placements — One image, multiple displays
Placement Sizes — Same image at different cell sizes
Z-Index — Background image behind text
Query Support — Check terminal capabilities
Animation — Color-changing square with movement

Code Structure

 go
 
 
// Clear screen
fmt.Print("\x1b[2J\x1b[H")

// Create image data
redSquare := createColoredSquare(100, 100, color.RGBA{R: 255, G: 0, B: 0, A: 255})
pngData, _ := kgp.ImageToPNG(redSquare)

// Transmit and display
cmd := kgp.NewTransmitDisplay().
 ImageID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 ResponseSuppression(kgp.ResponseErrorsOnly).
 Build()
fmt.Print(cmd.Encode())

Helper Functions in Demo

createColoredSquare(width, height, color) — Solid color image
createGradientSquare(width, height) — Gradient for cropping demo
clearScreen() — ANSI clear and home
waitForEnter(reader) — Pause for user input