Viewing is open to everyone. Downloading and starring need a GitHub sign-in.
Sign in with GitHub
CKey-Format-v0.11.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 locator format v0.11.0 (draft) |
| 2 | |
| 3 | Status: experimental reference format. The emitted locator frame has `format=11` |
| 4 | (`0B`) and `profile=1`. Format 8 remains a historical decoder-compatibility |
| 5 | format; it is not emitted by this revision. |
| 6 | |
| 7 | ## Geometry |
| 8 | |
| 9 | The canonical field is 29 by 29 units with origin at the upper-left and centre |
| 10 | `(14.5,14.5)`. A rounded-square structural border runs from `(0.5,0.5)` to |
| 11 | `(28.5,28.5)`, radius 3.5, width 0.65. Coordinates are shared by renderer and |
| 12 | decoder; colour is decorative only. |
| 13 | |
| 14 | Each corner finder is an **inset, edge-oriented three-arc set**, not a |
| 15 | border-sized leaf. In local top-left coordinates its centre is `(2.75,2.75)`. |
| 16 | The three circular centerline radii are `1.45`, `2.20`, and `2.95`; all have |
| 17 | width `0.42` and rounded caps. Top-right, bottom-right, and bottom-left are |
| 18 | exact reflections and each has three continuous quarter arcs. The top-left |
| 19 | finder has the same three arcs, but every arc is divided at the 45-degree |
| 20 | diagonal with a `0.85`-unit visible clear gap (including cap compensation). |
| 21 | This split is the orientation signature. The physical 6 by 6 corner envelope |
| 22 | remains non-payload, so data never touches a finder. |
| 23 | |
| 24 | The polar field remains four dot rings at radii `3.6 + .8r`, `r=0...3`, and a |
| 25 | separate ray band from radius 7.6 to 9.5. There are 72 equally-spaced angular |
| 26 | slots, clockwise from 12:00. The Grid Key is a 2 by 2 Cartesian block at rows |
| 27 | 11--12 / columns 2--3. Ray Key slots 0, 54, 55 have lengths 100%, 50%, 75%. |
| 28 | The outer ring's Ring Key is dots at slots 18,19,21; empty at 20; and one |
| 29 | round-capped connected arc in slots 22--25. Ring dots and arc width are 0.30; |
| 30 | the arc's visible length is exactly four slots. These structures are reserved. |
| 31 | |
| 32 | ## Framing and placement |
| 33 | |
| 34 | The payload is exactly 16 bytes. Frame bytes are `C7 4B 0B 01 00 10`, payload, |
| 35 | then CRC-32C over bytes 0--21. The 26-byte frame is systematic shortened |
| 36 | RS(77,26) over GF(256), primitive polynomial `0x11D`, primitive element 2, |
| 37 | roots `alpha^0...alpha^50`, high-degree-first coefficients, with 51 appended |
| 38 | parity bytes. It corrects up to 25 unknown byte errors. CRC-32C is separate |
| 39 | integrity detection, not error correction. |
| 40 | |
| 41 | The 616 codeword bits are placed MSB-first by the same alternating |
| 42 | Cartesian/polar sequence specified in v0.8.0: Cartesian sites are angularly |
| 43 | interleaved; all 69 data ray slots precede round-robin inner ring sites. A |
| 44 | light mark represents one. The Grid, Ray, Ring, boundary, finders, and center |
| 45 | radius 10.4 are reserved. The central region inside radius 3.3 is logo-safe; |
| 46 | no logo may overwrite a structural, payload, or parity site. |
| 47 | |
| 48 | ## Reader requirements |
| 49 | |
| 50 | An image reader rectifies a caller-supplied cyclic quadrilateral, normalizes |
| 51 | monochrome polarity from the permanent keys, and must require Grid/Ray/Ring |
| 52 | evidence, RS correction, and CRC-32C. The inset finder arcs are included as |
| 53 | continuous localization evidence; the top-left diagonal clear gaps contribute |
| 54 | orientation evidence. Candidate acceptance remains cryptographically grounded |
| 55 | in framing/CRC and mathematically grounded in RS, rather than in visual |
| 56 | finder matching alone. Full-frame localization and physical robustness limits |
| 57 | remain implementation work, not format claims. |
| 58 | |
| 59 | ## Compatibility fixture |
| 60 | |
| 61 | `tests/vectors/locator-v11.json` is the byte interoperability fixture for |
| 62 | payload `00 01 ... 0F`. The current renderer and C ABI must produce and decode |
| 63 | it exactly. |