Skip to content

Image Encoding

Mikkel edited this page May 6, 2026 · 3 revisions

Image Encoding

The JSON Drawing Protocol uses a compact indexed image format for image rendering operations.

Images are transported as Base64 encoded packed pixel data.


Encoding Overview

Images use:

  • Indexed colors
  • 4 bits per pixel
  • 2 pixels packed per byte
  • Base64 transport encoding

The encoded image data is used by:


Pixel Format

Each pixel is represented by a 4-bit palette index.

Bits Description
4 bits One pixel

Because each pixel uses 4 bits:

  • 2 pixels fit inside 1 byte

Palette Values

Value Meaning
0 black
1 white
2 yellow
3 red
4 transparent

See:


Byte Packing

Each byte stores two pixels.

Example:

High nibble = first pixel
Low nibble  = second pixel

Example byte:

0010 0001

Represents:

Nibble Value Meaning
0010 2 yellow
0001 1 white

Image Data Flow

Image
  ↓
Indexed pixels
  ↓
Packed 4-bit pixels
  ↓
Binary byte stream
  ↓
Base64 encoding
  ↓
JSON transport

Base64 Encoding

The binary pixel stream is Base64 encoded before transport.

Example:

{
  "data": "BASE64_DATA"
}

Renderers should:

  1. Decode Base64
  2. Unpack pixel nibbles
  3. Convert palette indexes to colors
  4. Render pixels sequentially

Transparency

Palette value 4 represents transparency.

Transparent pixels:

  • Are skipped during rendering
  • Do not overwrite framebuffer contents

Example:

Pixel Value Behavior
0–3 Draw pixel
4 Skip pixel

Image Dimensions

Image dimensions are provided separately:

{
  "width": 100,
  "height": 100
}

The renderer uses these values to determine:

  • Row width
  • Pixel count
  • Buffer traversal

Example

{
  "cmd": "draw_image",
  "args": {
    "x": 100,
    "y": 0,
    "width": 100,
    "height": 100,
    "data": "BASE64_DATA"
  }
}

Renderer Recommendations

Renderers should:

  • Validate decoded data length
  • Ignore invalid pixel indexes safely
  • Prevent framebuffer overflow
  • Skip transparent pixels
  • Handle malformed Base64 safely

Data Size Calculation

Because each pixel uses 4 bits:

pixels / 2 = bytes

Example:

Resolution Pixel Count Raw Bytes
100×100 10,000 5,000 bytes

Base64 encoding increases payload size slightly.

Related Pages

Clone this wiki locally