build_cmd(options) -> cmd

Build a kitty graphics protocol command string

build_data(data, options) -> payload

Build a kitty graphics data payload with base64 encoding and chunking

Base64-encodes data and splits it into 4096-byte chunks as required by the Kitty graphics protocol. All chunks except the last carry m=1 (more data follows); the final chunk uses m=0. Returns a single string containing all APC sequences ready for io.write.

build_shm(shm_name, options) -> payload

Build a kitty graphics shared memory payload

send_data(data, options, use_sync)

Send image data to the terminal via direct transmission

send_data_shm(data, options, use_sync) -> ok, err

Send image data to the terminal via POSIX shared memory

Creates a POSIX shared memory object with an auto-generated name (/lilush-<nanoid>), writes data into it, then sends the Kitty graphics command with t=s (shared memory transport) and S=<size> added to options automatically. When use_sync is true the write is wrapped in synchronized output mode escapes to prevent tearing. Returns nil and an error string if the shared memory object cannot be created.

build_file(file_path, options) -> payload

Build a kitty graphics file transmission payload

Base64-encodes the file path (not the file contents) and builds a Kitty graphics command with t=f (file transmission medium). The terminal reads the file directly from disk, avoiding the overhead of sending image data through the escape sequence stream.

send_data_file(file_path, options, use_sync)

Send image data to the terminal via file transmission

Sends a Kitty graphics command with t=f (file transmission). The payload is the base64-encoded absolute path to the image file on disk. The terminal reads the file directly. When use_sync is true the write is wrapped in synchronized output mode escapes.

send_cmd(options)

Send a kitty graphics command without data payload

build_png(data_or_path, options) -> payload

Build a kitty graphics PNG transmission payload

Builds the escape sequence(s) for transmitting a PNG image. Sets f=100 (PNG format) and a defaults to "T" (transmit and display). The first argument is interpreted based on options.t:

• "f" — file path; the terminal reads the file from disk

• "s" — raw PNG data; transmitted via POSIX shared memory

• default — raw PNG data; transmitted inline via base64 chunks

For shared memory (t="s") this function has the side-effect of creating a shared memory object. Defaults q=2 (suppress OK responses); override with q=1 to get all responses or q=0 to restore default protocol verbosity.

send_png(data_or_path, options, use_sync) -> ok, err

Send a PNG image to the terminal

Transmits a PNG image using the Kitty graphics protocol. Sets f=100 (PNG format) and a defaults to "T" (transmit and display). Routes to the appropriate transport based on options.t:

• "f" — data_or_path is a file path on disk

• "s" — data_or_path is raw PNG data, sent via shared memory

• default — data_or_path is raw PNG data, sent inline

Common options: i (image ID), c/r (display columns/rows), z (z-index), C=1 (no cursor movement). Defaults q=2 (suppress OK responses).

build_place(image_id, options) -> cmd

Build a kitty graphics image placement command

Returns the escape sequence for placing an already-transmitted image. Common options: c/r (display columns/rows), X/Y (pixel offset within cell), z (z-index), C=1 (no cursor movement), p (placement ID).

place_image(image_id, options)

Place an already-transmitted image at the current cursor position

build_delete(options) -> cmd

Build a kitty graphics image deletion command

Returns the escape sequence for deleting images. The d key in options controls the deletion scope:

• "a" / "A" — all visible placements (uppercase frees data)

• "i" / "I" — by image ID (i=<id> required)

• "p" / "P" — at cursor position

• "z" / "Z" — by z-index (z=<index> required)

Uppercase variants also free the stored image data when no other placements reference it.

delete_images(options)

Delete displayed images from the terminal

new_canvas(config) -> canvas

Create a new pixel canvas for drawing and displaying images

Returns a canvas object with drawing methods (fill, pixel, line, circle, rect) and display methods (send, display). Config fields: width (default 800), height (default 600), colors.bg (RGBA background, default transparent {0,0,0,0}), colors.main (RGBA foreground, default near-white {252,252,252,255}). The canvas is pre-filled with colors.bg on creation.

png_dimensions(path) -> width, height

Read pixel dimensions from a PNG file header

Reads the IHDR chunk from a PNG file to extract the image width and height in pixels. Returns two numbers on success, or nil if the file cannot be read or is not a valid PNG.