Viewing is open to everyone. Downloading and starring need a GitHub sign-in.
Sign in with GitHub
README.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 Reader for iPhone |
| 2 | |
| 3 | This is an early native camera test app for CKey Profiles 1–3. It locks capture to the physical rear wide camera, finds bright and dark connected border candidates, and refines each candidate continuously against the printed Grid, Ring, Ray, and finder keys before trying the shared C ABI decoders. A generated synthetic-data ranker only orders candidate components; it never accepts a payload. There are no fixed symbol-size ladders, and successful reads still require native framing, Reed–Solomon, and CRC validation. `src/ckey.cpp` is compiled directly into the app so there is no second encoder/decoder implementation. Profile 1 has optical fixtures; Profiles 2 and 3 are experimental camera paths and require physical testing before any reliability claim. |
| 4 | |
| 5 | ## Run on a phone |
| 6 | |
| 7 | 1. On a Mac with Xcode, open `ios/CKeyReader.xcodeproj`. |
| 8 | 2. Connect and unlock the iPhone, then select it as the run destination. |
| 9 | 3. In **Signing & Capabilities**, choose your Apple development team. The bundle identifier is `solutions.clearkey.CKeyReader`; change it if your team requires a unique identifier. |
| 10 | 4. Press **Run** and allow camera access when iOS asks. |
| 11 | 5. Display a CKey symbol on a separate screen or print it. Keep the whole symbol in view and move closer until the key and module details are clear. |
| 12 | |
| 13 | ## Verify the build has the current core |
| 14 | |
| 15 | The version line under the title must read **`0.1.0-build.85`**, which is `ckey_get_software_version()` from the compiled core. If it shows an older version, Xcode built a stale copy: run **Product → Clean Build Folder** (⇧⌘K) and rebuild. |
| 16 | |
| 17 | Then confirm, with symbols generated by a CKey Renderer built from the same commit: |
| 18 | |
| 19 | - **P0 decodes at every size.** Generate Profile 0 symbols in the renderer (the default profile). The reader shows `Profile 0 · v<N>`; the version comes from the symbol's keys. |
| 20 | - **P1, P2, and P3 each decode.** Older P2/P3 renders (formats 0.23/0.24, from before dev.49) do not decode from images; regenerate them. |
| 21 | - **P3 decodes only when the symbol is large in the frame.** The reader prefers 4K capture, and P3 needs at least 11 camera pixels per symbol unit, so its border must span at least about 60% of the frame's short side. Its whole border must stay in view; at 1080p capture it cannot decode P3 at all. The live diagnostics show the measured border side. |
| 22 | - **Rotation doesn't matter.** Border finding and refinement now run in the shared core (`ckey_find_borders_gray8`, `ckey_refine_quad_gray8`), and the simulated-reader test decodes symbols rotated up to 33° with keystone and blur. |
| 23 | |
| 24 | The result is shown as hexadecimal text, with the profile label and payload length. **Detection** timing measures candidate localization; **CKey** timing measures shared-core image decoding. They are per-successful-frame timings, not benchmark statistics. |
| 25 | |
| 26 | ## Current limits |
| 27 | |
| 28 | - All three profile decoders are tried on each candidate; the shared core's profile framing, Reed–Solomon code, and CRC gate successful reads. |
| 29 | - It scans grayscale Y planes from the camera (4K when the device supports it, otherwise 1080p) and supports either symbol polarity through the shared core. The border search samples about 960 × 540 points at any capture size. |
| 30 | - The app has not been compiled or run on an Apple device in the current build environment. The C++ core's image fixture tests do not verify AVFoundation camera behavior. |
| 31 | - Lighting, distance, blur, rotation, perspective, glare, minimum module size, and device latency have not been characterized. No sub-200 ms or camera-reliability claim is made. |
| 32 | - Full-frame localization is based on mathematical border/key fitting but still needs a labelled real-camera corpus, including lens-distortion, distance, blur, damage, and noise captures. Profiles 2 and 3 need physical-device tests before any end-to-end speed or reliability claim. |