CKey Format v0.27.0 — Profile 0: the scalable family

Status: draft. Added alongside Profiles 1–3; none of them changes.

Encoders emit frame format byte 0x1B (decimal 27), profile byte 0x00.

Why this profile exists

Profiles 1–3 are three fixed points: 16 bytes, up to 200 bytes, and 256–2,048 bytes. Between them, capacity jumps about 12× and then 16× in area. A 33-character URL jumped straight from Profile 1's look to Profile 2's density.

Profile 0 replaces those jumps with 31 versions. All versions share one skeleton (frame, finders, polar centre and dial position). Each version has a finer module pitch than the last, about 7% finer per step. Capacity rises smoothly from 27 bytes (v1) to 4,619 bytes (v31) at level M. No step more than doubles it, and most steps add 7–30%.

The fixed calibration keys identify the version. The Grid, Ring and Ray Keys are drawn at each version's own module pitch and slot pitch, so a reader recognizes the version from them. The error-corrected frame then repeats the version number.

Version table (normative)

The canonical field is [0,29]², exactly as in Profiles 1 and 2. Version v has G(v) modules across and module pitch p = 29 / G(v).

The following per-version integers are normative. They approximate a geometric series, but implementations must use the table rather than recompute it, because v9 and v11 fall on rounding ties.

Derived values:

• G, S and R follow G = round(29·2^((v−1)/10)), S = 8·round(9G/29), and R = ⌊(4.2 − 2.38p)/(0.86p)⌋ + 1.
• The Grid Key position follows c₀ = round(3G/29) − 1 and r₀ = round(12G/29) − 1. The one exception is v1's row, raised to 10 so the key keeps one pitch of clearance from the dial.
• Version 11 has exactly Profile 2's density, and version 31 has Profile 3's.

Geometry

Fixed at every version (identical to Profile 2):

• Frame: a rect at (0.5, 0.5), 28 × 28, rx 3.5, stroke 0.65.
• Finders: an arc of radius 2.3 about each corner inset 4, stroke 0.8, round caps. The top-left arc is split about 225° with a 0.95 clear gap.
• Polar anchors: ring 0 at r = 3.4, and dial rays starting at r = 7.6.

Scaled by the pitch p:

Slot k of S lies at angle 2πk/S, clockwise from 12:00. The SVG viewBox is −1 −1 31 31.

Safe area and sites

Cartesian sites. A cell is a site when its slack under the Format 0.25 rule is strictly positive, with:

• module half-size 0.34p;
• frame and finder clearance max(0.375, p);
• Grid Key clearance p;
• radial clearance p, from the data-ray outer ink edge at r = 7.6 + 2.3p and from each Ray Key stroke (half-width 0.22p).

Polar sites.

• Dial: every slot except the three Ray Key slots.
• Rings: every slot on every ring except the three Ray Key slots. On ring R−1, slots K…K+15 (the Ring Key) are also excluded.

Order and value.

• Identities: sites use Format 0.25's identities, with kinds 0 (Cartesian), 1 (dial) and 2 (ring).
• Order: sites are sorted by lowbias32(id XOR lowbias32(0x434B5030 XOR v)).
• Whitening: the stream starts from SplitMix32 state 0x434B5730 + v.

Codeword. The codeword length is C = ⌊sites / 8⌋ bytes. Site i < 8C carries codeword bit i, most significant bit first; at most 7 trailing sites carry whitening only. There is no fill waste: every other site carries data or parity.

Frame and error correction

Frame layout:

Reed–Solomon blocks. The C codeword bytes form B = ⌈C / 255⌉ blocks. Block b has n_b = ⌊C/B⌋ + (1 if b < C mod B), so longer blocks come first. Its parity is 2·⌊(pct·n_b + 100) / 200⌋, minimum 2, with pct = 14 (L), 28 (M), 44 (Q) or 60 (H). Each level therefore corrects about 7, 14, 22 or 30% of each block.

The RS code is the project's usual one (primitive polynomial 0x11D, roots α⁰…). Frame bytes fill the blocks' data portions in order. The coded blocks are then byte-interleaved: index j outer, block b inner, skipping blocks shorter than j.

Choosing a version. The encoder chooses the smallest version whose capacity (K − 12 bytes) fits the payload, unless the caller names a version.

Capacity (payload bytes)

Reading (informative)

1. Find borders. ckey_find_borders_gray8 finds border candidates and ranks them by how well the shared skeleton fits.
2. Align the frame. ckey_refine_quad_gray8(…, CKEY_FIELD_SCALABLE) aligns on both edges of the frame stroke, with the sample separation shrinking from about 6 px to 0.5 px as the search step shrinks (coarse-to-fine). It then picks the version whose keys fit best and fine-tunes against them. In simulated 4K frames this resolves v31 corners to 0.06–0.22 modules.
3. Identify the version and decode. ckey_decode_scalable_gray8 gates each orientation on the skeleton. It then gates each version on its own key pattern: the Grid Key on that version's lattice, the Ring Key at its slot pitch, and the Ray Keys. The decoder fully samples only versions that pass, best first. Reed–Solomon, the frame's version byte and CRC-32C decide.

Measured on synthetic renders: all 31 versions decode at 6 px per module clean and at 8 px per module after a 3×3 blur. Full 1080p/4K camera frames with clutter, rotation up to 33°, 8% keystone, blur and inverted polarity also decode.

Conformance vectors

FNV-1a-64 over every site in placement order of (identity little-endian, printed value), for payload "CKey renderer test" at level M: