Viewing is open to everyone. Downloading and starring need a GitHub sign-in.
Sign in with GitHub
CKey-Format-v0.17.0.md
v0.1.0-build.85
Latest
Commit ede38f5
Sign in with GitHub to download. Each download is recorded with your GitHub username.
| 1 | # CKey Format v0.17.0 — Profile 3 Capacity and ECC Tiers |
| 2 | |
| 3 | Status: experimental profile. This revision emits `format=17` (`11`), |
| 4 | `profile=3`; decoders continue to accept Profile 3 Formats 0.10 and 0.16. |
| 5 | The optical geometry and fixed 2,550-byte interleaved codeword do not change. |
| 6 | |
| 7 | ## Frame and tiers |
| 8 | |
| 9 | The frame is `C7 4B 11 03 TT LLhi LLlo payload CRC32C padding`. `TT` is the |
| 10 | one-based tier number (1–7). The CRC-32C covers magic through payload. The |
| 11 | frame is followed by deterministic visual fill through ten equal data blocks. |
| 12 | The fill is not encryption and is not relied on for integrity; RS protects it |
| 13 | and CRC validates the payload frame. |
| 14 | |
| 15 | | Tier | Payload capacity | Data bytes per RS block | Parity bytes | Unknown byte errors correctable per block | |
| 16 | |---:|---:|---:|---:|---:| |
| 17 | | 1 | 256 | 27 | 228 | 114 | |
| 18 | | 2 | 384 | 40 | 215 | 107 | |
| 19 | | 3 | 512 | 53 | 202 | 101 | |
| 20 | | 4 | 768 | 78 | 177 | 88 | |
| 21 | | 5 | 1,024 | 104 | 151 | 75 | |
| 22 | | 6 | 1,536 | 155 | 100 | 50 | |
| 23 | | 7 | 2,048 | 206 | 49 | 24 | |
| 24 | |
| 25 | Each block is a systematic RS(255,k) code over GF(256), primitive polynomial |
| 26 | `0x11D`, primitive element 2, roots `alpha^0` through `alpha^(254-k)`, |
| 27 | high-degree coefficient first, parity appended. The ten 255-byte blocks are |
| 28 | byte-interleaved in the public codeword. Higher tiers trade correction |
| 29 | strength for payload capacity while all tiers fill the same visual lattice. |
| 30 | The default encoder selects the smallest tier that fits; callers may request a |
| 31 | larger tier explicitly. The maximum remains 2,048 payload bytes. |
| 32 | |
| 33 | ## Deterministic visual fill |
| 34 | |
| 35 | Let `frame_end` be the byte immediately after CRC-32C. Initialize a 32-bit |
| 36 | state to CRC-32C of the complete frame through that CRC. For each padding byte, |
| 37 | update `state += 0x9E3779B9` modulo 2^32, then apply: |
| 38 | |
| 39 | 1. `z = (state xor (state >> 16)) * 0x85EBCA6B` modulo 2^32 |
| 40 | 2. `z = (z xor (z >> 13)) * 0xC2B2AE35` modulo 2^32 |
| 41 | 3. `z = z xor (z >> 16)` |
| 42 | 4. emit the low byte of `z` |
| 43 | |
| 44 | The state is seeded from the frame, making fill deterministic. It decorrelates |
| 45 | unused capacity from the black/white appearance of zero-filled padding; it |
| 46 | provides no secrecy or additional error correction. |
| 47 | |
| 48 | ## Geometry and decoding |
| 49 | |
| 50 | The v0.16 116-unit geometry, 232×232 Cartesian grid, 24 rings, 576 calibrated |
| 51 | ray bearings, and one inward-facing rounded arc per corner are unchanged. |
| 52 | Decoders first use the Grid Key to establish sampling scale, read the fixed |
| 53 | codeword lattice, try the declared tier's RS parameters, then validate tier, |
| 54 | length, deterministic fill, and CRC. Legacy v0.10/v0.16 frames use ten |
| 55 | RS(255,223) blocks. Camera image decoding and full-frame localization remain |
| 56 | experimental and require physical-capture validation. |