Repository navigation
Image Encoding
Mikkel edited this page May 6, 2026
·
3 revisions
The JSON Drawing Protocol uses a compact indexed image format for image rendering operations.
Images are transported as Base64 encoded packed pixel data.
Images use:
- Indexed colors
- 4 bits per pixel
- 2 pixels packed per byte
- Base64 transport encoding
The encoded image data is used by:
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
| Value | Meaning |
|---|---|
| 0 | black |
| 1 | white |
| 2 | yellow |
| 3 | red |
| 4 | transparent |
See:
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
↓
Indexed pixels
↓
Packed 4-bit pixels
↓
Binary byte stream
↓
Base64 encoding
↓
JSON transport
The binary pixel stream is Base64 encoded before transport.
Example:
{
"data": "BASE64_DATA"
}Renderers should:
- Decode Base64
- Unpack pixel nibbles
- Convert palette indexes to colors
- Render pixels sequentially
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 are provided separately:
{
"width": 100,
"height": 100
}The renderer uses these values to determine:
- Row width
- Pixel count
- Buffer traversal
{
"cmd": "draw_image",
"args": {
"x": 100,
"y": 0,
"width": 100,
"height": 100,
"data": "BASE64_DATA"
}
}Renderers should:
- Validate decoded data length
- Ignore invalid pixel indexes safely
- Prevent framebuffer overflow
- Skip transparent pixels
- Handle malformed Base64 safely
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.