The klad drawing format

A klad drawing is a folder whose name ends in .klad, called a bundle. This document describes everything in it, so that any program can read, write and make klad drawings. It is licensed under the MIT License (LICENSE-MIT), unlike klad itself.

From klad 1.0 on, a drawing made by any release opens in every later one with nothing lost: a format change adds a migration that converts, never drops.

klad is the reference: when this text and klad's renders disagree, klad is right and this text is wrong. The data is exact (every key, every byte); how pixels come out of it is described as far as a reader needs to draw a faithful approximation, not to match klad's renders bit for bit.

The folderCopy Anchor Link

Everything outside .cache/ is the drawing. Copy, version or zip those files and the drawing renders the same on another machine. Read the selection and the notes through klad selection --json and klad notes --json, not from .cache/.

Writers replace files atomically (write a temporary file, then rename), so a reader that watches the folder never sees half a file. Nothing in the drawing changes unless the drawing does: doc.json holds no revision or id counter, so an edit to one stroke changes its stroke file and nothing else, and git diffs and merges only what was edited. A program that wants to know whether a drawing changed compares the files (their size and modified time, or their bytes).

ConventionsCopy Anchor Link

• Coordinates are canvas pixels, origin at the top left, y down. Angles are degrees; positive turns clockwise on screen.
• Colours are "#rrggbb" or "#rrggbbaa": sRGB, straight (not premultiplied) alpha.
• Ids are unique across the whole document and use letters, digits, - and _. Ids are case sensitive. klad makes new ones from a prefix (l layer, c cel, n node), a number, and the tag of the copy that made them: l48qa. Each copy of a drawing (a clone, a git worktree: any folder without .cache/copy.json) picks a two-letter tag the first time klad opens it and keeps it in .cache/copy.json, with counters that only go up, so two copies edited apart never make the same id; the copy a drawing was made in has no tag (l48). A folder copied by hand with its .cache/ keeps the tag: delete .cache/ in the copy to give it its own. Ids already in a drawing never change. Writers that make their own ids should do the same or use a long random part. A drawing with an id used twice does not open; klad repair gives every later one a new id.
• JSON is UTF-8, written pretty with a stable key order. Keys at their default value are left out; readers must take the defaults listed below for missing keys. Most objects reject keys they do not know, so writers must not add their own.
• Versions. format names the version of doc.json and everything it implies; this is klad/6. Each version opens the older klad/ drawings and migrates them in memory (written back on the next change). A reader that meets a newer version than it knows should refuse to write the bundle. Drawings from before klad/1 (.draw folders, formats draw-anything/0 to /9) do not open.

doc.jsonCopy Anchor Link

{
  "format": "klad/6",
  "canvas": { "width": 2048, "height": 2048, "background": "#f4efe6" },
  "timeline": { "fps": 12, "frames": 24, "origin": [1024, 1800],
    "clips": [{ "name": "run", "from": 0, "to": 11, "loop": true, "fps": 24 }] },
  "export": { "godot": "../game/art/hero" },
  "palette": [{ "color": "#1b1b1b", "name": "ink" }, { "color": "#5b6ee1" }],
  "layers": [
    { "id": "l3", "name": "lines", "kind": "paint",
      "cels": [{ "id": "c1", "frame": 0, "hold": 2 }, { "id": "c2", "frame": 2, "link": "c1" }] },
    { "id": "l4", "name": "shapes", "kind": "vector", "blend": "multiply",
      "cels": [{ "id": "c4", "frame": 0, "nodes": [
        { "id": "n5", "type": "rect", "x": 0, "y": 0, "w": 2048, "h": 900,
          "fill": { "linear": { "from": [0, 0], "to": [0, 900], "stops": [[0, "#121d31"], [1, "#4a6a8c"]] } } }
      ] }] }
  ]
}

The documentCopy Anchor Link

Strokes and fills store their colour, so the palette is a list of names for colours, never a reference: renaming or recolouring a swatch changes nothing drawn.

The timelineCopy Anchor Link

A clip is name (unique), from and to (both included), loop (false) and fps (the timeline's when absent). Clips may overlap.

LayersCopy Anchor Link

Layers compose bottom to top. Groups compose their children into one image, then blend that with the group's opacity and blend. An adjustment layer changes what is under it inside its group (or, with clip, only its base).

• Clipping. A layer with clip: true shows only where its base, the nearest layer below it in the same list without clip, has alpha. The base and the clipped layers above it draw as one group: each clipped layer blends onto the base with its own blend and opacity, kept inside the base's alpha; the group then blends with the base's blend and opacity. A hidden base hides its clipped layers; the lowest layer of a list is never clipped.
• Masks. mask is a paint layer of its own (own id, cels and stroke files, strokes/<mask id>/...) with opacity 1 and blend normal. Its alpha hides the layer: marks on the mask hide, eraser strokes on it show the layer again, and a frame without a mask cel hides nothing. visible: false on the mask turns it off.
• Lock alpha is recorded on each stroke and fill as it is made (a flag in the stroke file), so turning lockAlpha off later never changes what was drawn. A locked mark composites source-atop: it changes colour where the layer has paint and leaves alpha as it was.

Cels: drawings on the timelineCopy Anchor Link

A cel is a layer's content from frame on.

A cel that is not a link is a drawing; frames no cel covers are blank. Drawing on twos is hold: 2.

tween records an in-between made from two keys: from and to (the keys' drawing ids), t (0 to 1, after spacing), match (order or near when marks were not paired by id), pairs (forced pairs, [first key mark, second key mark]), made (a hash of the marks as made, so klad can tell whether someone drew on it since) and unpaired (pop, pop 0.3, fade or draw-on: how marks found in one key only were shown). The marks themselves are stored like any drawing's; the record only says how to remake them.

pose records a drawing bent from a rest drawing by its layer's skeleton: rest (the rest drawing's id), angles (degrees from rest per bone name), root ([dx, dy], default [0, 0]) and ik (per IK constraint, named by its bone: target, [x, y] in canvas px, and mix, 0 to 1, default 1; see Skeletons). The bones' turns are angles with the IK solved on top of them. Its marks are stored bent, so a reader can draw it without knowing about bones.

Vector nodesCopy Anchor Link

Every node has:

And by type:

Paint is a colour string, "none", {"linear": {"from": [x, y], "to": [x, y], "stops": [[offset, colour], ...]}} or {"radial": {"center": [x, y], "radius": r, "stops": [...]}}, in the node's own coordinates.

EffectsCopy Anchor Link

effects is a list of one-key objects, applied in order to the layer's composed image: [{"glow": {"radius": 24}}, {"outline": {"width": 3}}]. Missing settings take their defaults.

AdjustmentsCopy Anchor Link

An adjustment layer's adjust is one of:

For example {"kind": "adjust", "adjust": {"curves": {"points": [[0, 0], [0.5, 0.3], [1, 0.85]]}}}.

Keys: animated propertiesCopy Anchor Link

Layers, groups and nodes may keep keys: per property (x, y, rotate, sx, sy, opacity) a list of keys sorted by frame.

"keys": { "y": [{ "frame": 0, "value": 0, "ease": "in-out" }, { "frame": 12, "value": -40 }] }

A key is frame, value and ease (linear when absent; in, out, in-out, step, or {"curve": [x1, y1, x2, y2]}, a cubic curve as in CSS). Between two keys the value follows the first key's ease; it holds before the first key and after the last. A layer or group moves about the canvas centre; a node's keyed values replace its transform and opacity at that frame.

SkeletonsCopy Anchor Link

A skeleton lives on a bones layer (kind bones), which draws nothing and has no cels: its bones are each a name (unique in the skeleton), a parent (a bone listed before it; none for a root), a head and a tail ([x, y] in canvas px, at rest). A paint layer anywhere in the drawing moves with a bones layer through its rig: {"skeleton": "<bones layer id>", "bone": "<name>"} attaches it to that bone, so posed it moves rigidly with that bone's frame alone, the way a cut-out limb follows its bone, and the weights do not touch it; without bone it bends by the skeleton's weights. A paint layer without rig is not moved by any pose. Each skeleton has a weights file (below). Posed drawings store their marks already bent (see pose above), so bones and weights are only needed to make new poses.

A pose turns each bone about its head by its angle, its children with it, and moves the root bones by root. A bone's world turn is its angle plus its parent's world turn; a child's head moves with its parent's frame.

ik lists the skeleton's IK constraints, one per bone at most: bone (the end of the limb), chain (2, the default: the bone and its parent, a limb; 1: the bone alone, an aim), bend (clockwise, the default, or counterclockwise: the way the limb's joint bends on screen, as the bone turns relative to its parent) and softness (px, default 0). A pose with an ik entry for a constraint solves it after the pose's angles and root, on top of them:

• Aim (chain 1): the bone turns so its tail points at the target; a target on its head leaves it as it is.
• Limb (chain 2, parent A, bone B): with s the posed head of A, l1 the rest distance from A's head to B's head (B need not start at A's tail), l2 B's length and d the distance from s to the target, the reach r is d eased by the softness (below) and clamped to between |l1 - l2| and l1 + l2. The joint (B's posed head) is the meeting point of the circle of radius l1 about s and the circle of radius l2 about the point r along the line from s to the target, on the bend side: B turns clockwise relative to the line from A's head to B's head for clockwise. A then turns so its head-to-B line points at the joint, and B so its tail is at the target (or, out of reach, straight towards it at full reach).
• Softness s eases the reach: r = d up to l1 + l2 - s; r = d - (d - l1 - l2 + s)^2 / (4 s) up to l1 + l2 + s; then r = l1 + l2. So the limb slows before full reach and is straight only once the target is s past it.
• Mix m blends each turned bone from the pose's angle a to the solved angle b the short way round: a + m wrap(b - a), wrap taking an angle to -180 to 180 degrees.

Constraints are solved parent first, by the position of the limb's top bone (A for a limb, the bone for an aim) in bones, then of its bone; each sees the bones as the ones before it left them. The solve is in 64-bit floats with deterministic maths, so it gives the same turns everywhere. A pose without an entry for a constraint leaves that limb to its angles. In-betweens of two poses of one rest drawing mix the angles, the root, each target and each mix by t, then solve. A constraint in one key only is handed over as turns: that key's limb bones take their solved turns, each within 180 degrees of the other key's angle, and the in-between has no entry for it. Pose angles, root and targets must be finite and mixes within 0 to 1.

Stroke filesCopy Anchor Link

strokes/<layer>/<cel>.strokes holds the marks of one paint drawing, in the order they are drawn: brush strokes and fills. Every mark has an id, unique within its drawing, shared by strokes and fills. A mark's address is <cel>:s<id>. An id is a u32: its top 10 bits name the copy that made it (0 for none, else 1 + 26 × first letter + second letter, with a as 0) and its low 22 bits are a number counted per copy, so s349qa is 349 made by the copy tagged qa, stored as (1 + 16 × 26 + 0) << 22 | 349. Ids from before klad/5, and those of the copy a drawing was made in, are plain numbers: s348. Addresses accept the number in either form.

The file is one zstd frame (any level; klad uses 3). Inside:

There must be nothing after the last mark.

Numbers: a varint is an unsigned LEB128 integer (7 bits per byte, low bits first, the high bit set on every byte but the last). A signed varint is zigzag encoded first ((v << 1) ^ (v >> 63)). u16, u32 and f32 are little-endian. A colour is four u16: red, green, blue, alpha, sRGB with straight alpha, 0 to 65535. A string is a varint length and that many UTF-8 bytes.

StrokesCopy Anchor Link

A column is n signed varints, each the difference from the previous value (the first from 0). Without the tilt or time bit those values are 0. Bit 8 has no data: it marks a stroke made with lock alpha on.

AttachmentsCopy Anchor Link

An eraser, smudge or blender stroke (a brush with "blend": "erase", or a paint of smudge or blend) records the marks it changed when it was drawn: the earlier marks in its drawing with paint under it. It moves, turns, is copied and is deleted with them, and splits when only some of them move.

An attached eraser erases only its marks, as if they were a layer of their own. From the eraser's first mark up to the eraser, klad keeps three layers over the eraser's reach: what was there before its first mark, its marks alone, and the other marks drawn after its first mark, each painted in order as on the drawing (erasers without attachments erase all three; smudges and blenders act on each). Where the eraser has coverage, the pixel becomes the other marks over (its marks erased, over what was there before); elsewhere it stays as drawn. When an eraser is drawn, all paint under it belongs to its marks, so the picture is the same as an eraser that erases whatever is under it. A mark that is not attached and comes under the eraser later sits below all of its marks if it was drawn before the first of them, and above them otherwise. Where two attached erasers overlap, the later one erases the earlier one's marks layer when they share a mark, and its other two layers when it holds marks the earlier one does not. An eraser with a wet stroke (paint of wet), or a smudge or blender with lock alpha, between its first mark and itself on the same area erases in order like an unattached one. Ids that no longer exist in the drawing are ignored, and an eraser with none left erases in order. Height (paint with body) is erased in order.

A reader that ignores attachments draws every drawing as it was when its erasers were drawn, which is the same picture until something attached moves. Smudge and blender strokes always act on whatever is under them; their attachments only say what they move with.

FillsCopy Anchor Link

A fill is drawn from its stored coverage, not recomputed, so it looks the same however the lines around it change (klad refill recomputes it on purpose). Coverage is a box and run-length coded alpha: varints x, y, width, height, a varint count of runs, then each run as a varint length and a u8 alpha, row by row through the box.

CutsCopy Anchor Link

When a lasso cuts across a mark, the mark is not split into new geometry: each part keeps the whole mark plus a cut that shows only its side. Cuts are a varint count, then for each a u8 (0 keep inside, 1 keep outside) and a polygon (a varint n and n pairs of f32). A mark shows only where every one of its cuts keeps it.

BrushesCopy Anchor Link

brushes/<id>.json is the brush that strokes naming <id> were drawn with. A bundle keeps every brush its strokes use, and a brush in a bundle never changes once a stroke uses it, so a drawing renders the same on every version of klad.

A picture named by a tip or grain is brushes/images/<name>.png (dark is paint, or the alpha where there is one) when the bundle has it, and otherwise one of the pictures built into klad.

Drawing a stroke: walk the samples, interpolate between them, stamp the tip every spacing x size along the way, with size, flow and opacity from the pressure (and tilt and speed) through the dynamics, the taper thinning the ends, and the per-dab jitter from the stroke's seed. A program that does not implement klad's brush engine can still draw a fair likeness with a round tip of the stroke's size and colour.

WeightsCopy Anchor Link

weights/<owner>.weights holds the weights of the skeleton of layer or group <owner>: one map per bone over a grid of 4 px cells. The file is one zstd frame holding a line of JSON, a newline, then the maps:

{"width": 512, "height": 256, "bones": ["hip", "thigh", "shin"]}\n
<width x height bytes for "hip"><... for "thigh"><... for "shin">

width and height are the canvas size in cells (rounded up); each map is one byte per cell, 0 to 255, rows top first, in the order of bones. Weights are normalised across bones when used, and a place no bone weighs follows the nearest bone.

Pictures and fontsCopy Anchor Link

images/ holds the pictures image nodes show, as PNG, each named by a hash of its contents so the same picture is stored once. fonts/ holds the font files text nodes name (TrueType or OpenType) with their licence files beside them; text is shaped with HarfBuzz rules (kerning, ligatures, marks) from the file alone, never from fonts installed on the machine.

Format historyCopy Anchor Link