Open CKey Make a CKey
Menu
Viewing is open to everyone. Downloading and starring need a GitHub sign-in. Sign in with GitHub

OVERVIEW.md

v0.1.0-build.85 Latest Commit ede38f5

Size
13 KB
Lines
167
Language
markdown
SHA-256
d257ce81e1a4…
View on GitHub

Sign in with GitHub to download. Each download is recorded with your GitHub username.

1# CKey technical overview
2
3A tour of the formats, the libraries and the tools, with the commands that exercise each one. For installing a package, start with the [README](../README.md).
4
5## Current milestone
6
7The locator core defines a fixed 29 × 29 profile, byte framing, CRC-32C, shortened Reed–Solomon coding and correction, deterministic Cartesian/polar placement, SVG rendering, and grayscale image decoding. Read the current draft formats — [Profile 0 Format 0.27.0](../spec/CKey-Format-v0.27.0.md), [Profile 0.1 Format 0.28.0](../spec/CKey-Format-v0.28.0.md), [Profile 1 Format 0.14.0](../spec/CKey-Format-v0.14.0.md), [Profile 2 Format 0.25.0](../spec/CKey-Format-v0.25.0.md), and [Profile 3 Format 0.26.0](../spec/CKey-Format-v0.26.0.md) — before treating any bytes or geometry as interoperable. It is a draft and may change before 1.0.
8
9## Build and use
10
11```sh
12cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
13cmake --build build
14ctest --test-dir build --output-on-failure # checks are always on, including Release
15./build/ckey encode --hex 00112233445566778899aabbccddeeff --out locator.svg
16```
17
18`ckey encode` accepts exactly 16 bytes for the locator profile. The C ABI `ckey_decode_gray8` decodes a one-channel 8-bit grayscale crop when the caller supplies the symbol quadrilateral. It rectifies projective perspective, checks the Grid/Ray/Ring calibration keys and both monochrome polarities, samples the matrix, and validates the payload through Reed–Solomon and CRC-32C. The caller supplies the symbol's four corners, or finds them with the core's full-frame localization: `ckey_find_borders_gray8` returns border candidates from a whole frame, and `ckey_refine_quad_gray8` fits each to a profile's field. The pipeline is tested on simulated camera frames, not yet on a labelled real-camera corpus. Lens-distortion correction and known-erasure recovery are not implemented. The committed optical image fixture decodes a browser-rendered capture at 670 × 670 pixels, and also checks rotated corner order and inverted polarity. This is evidence of the image sampling path, not a real-camera robustness claim. RS(77,26) is genuine Reed–Solomon error correction over GF(256); it is not masking.
19
20The experimental text profile accepts up to 200 UTF-8 bytes or arbitrary bytes and is intentionally separate from the compact locator:
21
22```sh
23./build/ckey encode-text --utf8 "a message up to 200 UTF-8 bytes" --out text.svg
24./build/ckey encode-text --hex 001122334455 --out binary.svg
25```
26
27It implements a real RS(255,210) frame with 45 parity bytes, a dense Cartesian/polar renderer, connected multi-unit ring arcs, and the canonical one-arc-per-corner finder geometry. See [Format 0.25.0](../spec/CKey-Format-v0.25.0.md). Short frames use deterministic visual fill, protected by the same RS block; every optical site carries a whitened value, so no region of the symbol is left empty, and payload modules keep a declared clearance from every structural mark. The projective grayscale decoder reads clean renders from about 10 px per unit (round-trip tested in CI); physical camera scans still need validation.
28
29The experimental extended profile accepts 1–2,048 bytes. Seven capacity tiers (256, 384, 512, 768, 1,024, 1,536, and 2,048 bytes) trade payload room for Reed–Solomon parity while keeping the full 2,550-byte symbol populated. It uses ten byte-interleaved tiered RS(255,k) blocks, 34 polar rings, and an eight-state ray alphabet (four Gray-coded lengths × two calibrated widths):
30
31```sh
32./build/ckey encode-extended --utf8 "large payload" --out extended.svg
33./build/ckey encode-extended --hex <up-to-4096-hex-chars> --out extended.svg
34./build/ckey encode-extended --tier 512 --utf8 "payload with a 512-byte ceiling" --out extended-512.svg
35```
36
37See [Profile 2 Format 0.25.0](../spec/CKey-Format-v0.25.0.md) and [Profile 3 Format 0.26.0](../spec/CKey-Format-v0.26.0.md). The encoder automatically chooses the smallest Profile 3 tier that fits, or callers can select a tier explicitly through the C ABI and CLI. The projective decoder reads clean renders of the 2,048-byte tier from about 11 px per unit (round-trip tested in CI); physical camera decode is not yet validated.
38
39## Libraries, SDKs and services
40
41The core is C++20 behind a C ABI ([`include/ckey/ckey.h`](../include/ckey/ckey.h), ABI 4). It is split so an app links only what it needs ([`src/README.md`](../src/README.md)):
42
43| Library | Purpose |
44|---|---|
45| `ckey_codec` | encode and decode codewords; the `.ckey` file format |
46| `ckey_scan` | full-frame localization and decoding; needs only `ckey_codec` |
47| `ckey_render` | canonical geometry; native RGBA/gray raster, PNG, PDF, SVG, print |
48| `ckey_certify` | style certification through a modelled camera scan |
49| `ckey_telemetry` | optional aggregate scan counters ([details](adoption-and-telemetry.md)) |
50
51`cmake --install` provides a CMake package (`find_package(CKey)`, targets `CKey::core`, `CKey::scan` and so on); see [`examples/c`](../examples/c).
52
53| SDK | Package | Location | Verified |
54|---|---|---|---|
55| Swift (iOS, macOS) | SwiftPM `CKey` (this repository's URL) | [`sdk/swift`](../sdk/swift) | in CI on macOS |
56| Web (WASM) | npm `openckey` | [`sdk/web`](../sdk/web) | JS here; wasm in CI |
57| Android | Maven `org.openckey:ckey` | [`sdk/android`](../sdk/android) | JNI here; Gradle in CI |
58| .NET | NuGet `CKey` | [`sdk/dotnet`](../sdk/dotnet) | native library here; C# in CI |
59| CLI | Homebrew `ckey` (formula generated per release) | [`packaging/homebrew`](../packaging/homebrew) | |
60
61Install commands for every package are in the [README](../README.md#install).
62
63Every SDK wraps the same core. Each gives you:
64
65- headless rendering to native images, plus a UI view;
66- a scanner;
67- payload actions per the [conventions](../spec/CKey-Payload-Conventions.md);
68- telemetry mode `0`/`1`/`2`, default `1`. Opting out takes one line: `CKey.telemetry = 0`.
69
70[openckey.org](https://openckey.org) is the project's hosted site. It runs separately from this repository and is not open source. It provides:
71
72- the browser renderer;
73- downloads of the packages above (MIT, built from this repository);
74- `/text/{id}` and `/sq/{id}` destinations;
75- the telemetry endpoint the SDKs report to. It keeps aggregates only and stores no IPs, as `docs/adoption-and-telemetry.md` requires.
76
77### Rendering, certification and verification
78
79```sh
80./build/ckey encode-scalable --utf8 "https://openckey.org" --raster code.png --size-px 1024 # native pixels
81./build/ckey encode-scalable --utf8 "https://openckey.org" --raster code.png --transparent yes # alpha 0 where unpainted
82./build/ckey encode-scalable --utf8 "https://openckey.org" --pdf code.pdf --size-in 2 # vector PDF
83```
84
85- **Default look:** black on white.
86- **Style policies** (the `policy` field of `ckey_style`):
87 - `strict` (default): refuses styles that could fail to scan;
88 - `adaptive`: repairs them and reports the changes;
89 - `override`: renders anything, but never certifies it.
90- **Certification:** `ckey_certify_scalable_style` certifies a style by decoding it through a modelled camera, not by contrast ratio. A transparent symbol needs the host's backdrop to be certified ([design system](../spec/CKey-Design-System.md#policies-and-certification)).
91- **Conformance:** vectors in [`tests/vectors/conformance-v1.json`](../tests/vectors/conformance-v1.json) ([how](../tools/conformance/README.md)).
92- **Benchmarks:** synthetic, with QR and Data Matrix comparison in CI ([`docs/benchmarks`](benchmarks)).
93- **Status:** the full requirement-by-requirement map is in [`docs/IMPLEMENTATION-STATUS.md`](IMPLEMENTATION-STATUS.md).
94
95## Profile 0: the scalable family
96
97Profile 0 ([Format 0.27.0](../spec/CKey-Format-v0.27.0.md)) is one design at 31 sizes. Every version keeps the same frame, finders, rings and dial, and only the module pitch changes. It runs from Profile 1-sized modules (v1, 29 across, 27 bytes at level M) to Profile 3 density (v31, 232 across, 4,619 bytes), about 7% finer per step. It removes the appearance jumps between Profiles 1, 2 and 3: a 33-character URL becomes v2, which still looks like a locator.
98
99The Grid, Ring and Ray Keys are drawn at each version's own pitch, so the reader identifies the version from them. Four correction levels (L/M/Q/H) trade capacity for robustness. Profiles 1–3 remain available and unchanged.
100
101```sh
102./build/ckey encode-scalable --utf8 "https://citeory.com/tour?ref=ckey" --out p0.svg
103./build/ckey encode-scalable --utf8 "a longer message" --version 12 --level Q --out p0-v12.svg
104```
105
106## Design system
107
108Profile 0 symbols can be branded without breaking scanning; see the [CKey Design System](../spec/CKey-Design-System.md):
109
110- **Mark shapes:** modules rounded, square, circle or diamond; rings joined or dotted; rays round or flat.
111- **Paint:** metallic sheen, vignette, accent colours, bevel, depth and grain.
112- **Logo:** in the centre.
113- **Fixed:** the frame, finders and keys.
114
115A built-in check enforces contrast and effect limits and the logo's error-correction budget.
116
117```sh
118./build/ckey encode-scalable --utf8 "https://citeory.com/tour" --preset concept --modules circle --logo logo.png --out branded.svg
119```
120
121## Printing
122
123Small prints need dark marks on paper, a device-grid bitmap printed at actual size, and, for small or dense symbols, the print-robust **Profile 0.1** layout ([Format 0.28.0](../spec/CKey-Format-v0.28.0.md)). See the [printing guide](../spec/CKey-Printing.md).
124
125```sh
126./build/ckey encode-scalable --utf8 "https://citeory.com/tour" --layout print --png p01.png --size-in 0.25 --dpi 600
127./build/ckey print-sheet --out sheet.png # calibration ladder for your printer and paper
128```
129
130## Payload conventions
131
132Payloads are bytes. [CKey Payload Conventions](../spec/CKey-Payload-Conventions.md) (informative) defines how readers interpret text payloads:
133
134- Standard URI forms: `https:`, `mailto:`, `tel:`, `sms:`, `geo:`, and vCard.
135- One CKey convention, `address:`, which carries a free-text street address for the map app.
136- Safety rules: nothing happens until the user taps, and only allowlisted forms get an action.
137
138## iPhone reader
139
140An experimental SwiftUI camera reader is in [`ios/CKeyReader.xcodeproj`](../ios/CKeyReader.xcodeproj). It compiles the same `src/ckey.cpp` core into the app, locks capture to the physical wide rear camera, ranks thresholded border components, and refines each quadrilateral against the printed Grid, Ring, Ray, and finder keys before passing grayscale samples to the C ABI. Its small generated ranker only prioritizes candidates; key agreement plus Reed–Solomon and CRC remain the acceptance gate. Open the project in Xcode and follow [`ios/README.md`](../ios/README.md) to run it on an iPhone. Camera scanning is an early test build; the supported capture envelope and device performance have not been established.
141
142The companion Mac laboratory is [`macos/CKeyRenderer.xcodeproj`](../macos/CKeyRenderer.xcodeproj). It invokes the same C++ encoders and SVG renderer, then applies non-normative color, blur, damage, noise, rotation, and resolution reduction. The preview runs each rendered raster through the same C++ image decoder and reports pass/fail; this controlled crop test does not replace full-frame camera localization or held-out phone captures.
143
144## Autonomous synthetic-camera training
145
146The candidate ranker can be rebuilt without holding a phone up to a display:
147
148```sh
149python3 tools/train_synthetic_locator.py --samples 1500 --keep-images
150```
151
152The command compiles the current C++ encoder, makes actual Profile 1/2/3 SVG artifacts with varied payload sizes, rasterizes them, applies deterministic perspective, lighting, blur, noise, damage, polarity-adjacent contrast, scale, and clutter variation, records the expected payload/profile/corners, derives candidate measurements from those captures, and emits `ios/CKeyReader/LocatorRanker.swift`. It requires Inkscape for exact SVG rasterization. The result ranks border candidates only; mathematical key fitting plus RS/CRC remains the only payload-acceptance authority.
153
154## Milestones
155
1561. **Format and deterministic core (current):** frozen-enough draft framing/geometry, reference encoder, SVG, independent test vectors, C ABI.
1572. **Decoder and image normalization:** RS error/erasure correction, structured diagnostics, grayscale image acquisition, geometric localization and perspective normalization, real-camera corpus.
1583. **Interop and SDKs:** Swift, Kotlin, JS/TS, WASM; wrappers call the same core rather than reimplementing the format.
1594. **Laboratory and hardening:** browser test lab, perturbation suite, fuzzing, license audit, reproducible release and measured device benchmarks.
160
161Every release milestone must report tests run, real-capture conditions, latency distributions, and limits. No performance target is considered achieved without published benchmark data.
162
163## License and research provenance
164
165The repository already used MIT at the start of this work; it is retained to preserve existing repository intent. Apache-2.0 is also permissive and adds an explicit patent grant, which may be preferable if the project later needs stronger patent clarity. Changing the repository license requires an owner decision and contributor-rights review; no research implementation is copied into this milestone.
166
167Research informing the independent design is summarized in [the research and license audit](../spec/RESEARCH.md). Cited ideas are not copied source code. Each dependency must have its license recorded before adoption.