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 |
| 2 | |
| 3 | CKey is an open, independent 2D optical code. A rounded-square field with corner finders surrounds a polar centre of rays, dots, rings and arcs. It carries links, text, contact cards and any bytes, protected by Reed–Solomon error correction, and it can be styled without breaking scanning. |
| 4 | |
| 5 | This repository holds the reference implementation: the C core, SDKs for Swift, the web, Android and .NET, a command-line tool, and the format specifications. It is MIT-licensed. [openckey.org](https://openckey.org) is the only official home of CKey. |
| 6 | |
| 7 | <p align="center"> |
| 8 | <img src="docs/gallery/link-plain.png" width="150" alt="A CKey holding a link, black on white"> |
| 9 | <img src="docs/gallery/concept.png" width="150" alt="A CKey in the Concept style"> |
| 10 | <img src="docs/gallery/contact-evergreen.png" width="150" alt="A CKey holding a contact card, evergreen on paper"> |
| 11 | <img src="docs/gallery/dots-navy.png" width="150" alt="A CKey with dotted rings and circle modules"> |
| 12 | <img src="docs/gallery/dense.png" width="150" alt="A dense CKey holding about 560 bytes"> |
| 13 | </p> |
| 14 | |
| 15 | Every image above is rendered by the core and read back by the real decoder. See the [gallery](docs/gallery/README.md) for what each one holds and how it certifies. |
| 16 | |
| 17 | > **Status: experimental.** The formats are drafts and may change before 1.0. Decoding is tested on rendered and simulated camera images; real-camera robustness and speed have not been measured yet, so no claims are made about them. The [field tests](field-tests/README.md) are how they will be: run one and report what you find. |
| 18 | |
| 19 | ## Install |
| 20 | |
| 21 | The current release is **`0.1.0-build.85`**. Every package wraps the same C core. |
| 22 | |
| 23 | | Platform | Package | Install | |
| 24 | |---|---|---| |
| 25 | | iOS, macOS (Swift) | Swift package `CKey` | Xcode: **File → Add Package Dependencies…** → `https://github.com/clearkeysolutions/ckey` | |
| 26 | | Web, Node (WebAssembly) | npm `openckey` | `npm install openckey` | |
| 27 | | Android (Kotlin) | Maven `org.openckey:ckey` | `implementation("org.openckey:ckey:0.1.0-build.85")` | |
| 28 | | .NET | NuGet `CKey` | `dotnet add package CKey` | |
| 29 | | Command line | Homebrew `ckey` | `brew install clearkeysolutions/ckey/ckey` | |
| 30 | | C and C++ | CMake package `CKey` | Build from source (below), then `find_package(CKey)` | |
| 31 | |
| 32 | Release archives for every package, with `SHA256SUMS` and build provenance, are on the [GitHub Releases](https://github.com/clearkeysolutions/ckey/releases) page and at [openckey.org/downloads](https://openckey.org/downloads). Check the SHA-256 of anything you download. |
| 33 | |
| 34 | ### Swift |
| 35 | |
| 36 | ```swift |
| 37 | // Package.swift |
| 38 | .package(url: "https://github.com/clearkeysolutions/ckey", from: "0.1.0-build.85"), |
| 39 | .target(name: "MyApp", dependencies: [.product(name: "CKey", package: "ckey")]), |
| 40 | ``` |
| 41 | |
| 42 | ```swift |
| 43 | import CKey |
| 44 | |
| 45 | let symbol = try CKeySymbol.encode("https://openckey.org") |
| 46 | let image: CGImage = try symbol.cgImage(size: 1024) |
| 47 | let pdf: Data = try symbol.pdfData(widthPoints: 144) // 2 inches wide |
| 48 | ``` |
| 49 | |
| 50 | `CKeyScanner` (module `CKeyScanKit`) is a scan-only product with no renderer and no telemetry. See [sdk/swift](sdk/swift/README.md). |
| 51 | |
| 52 | ### Web |
| 53 | |
| 54 | ```js |
| 55 | import { loadCKey } from 'openckey'; |
| 56 | |
| 57 | const ckey = await loadCKey(); |
| 58 | const sym = ckey.encode('https://openckey.org'); |
| 59 | ckey.renderToCanvas(sym, document.querySelector('canvas'), { size: 512 }); |
| 60 | const png = ckey.renderPNG(sym, { size: 1024 }); |
| 61 | sym.free(); |
| 62 | ``` |
| 63 | |
| 64 | See [sdk/web](sdk/web/README.md). |
| 65 | |
| 66 | ### Android |
| 67 | |
| 68 | ```kotlin |
| 69 | dependencies { |
| 70 | implementation("org.openckey:ckey:0.1.0-build.85") |
| 71 | implementation("org.openckey:ckey-compose:0.1.0-build.85") // optional: CKeyImage |
| 72 | implementation("org.openckey:ckey-camerax:0.1.0-build.85") // optional: CKeyAnalyzer |
| 73 | } |
| 74 | ``` |
| 75 | |
| 76 | ```kotlin |
| 77 | val symbol = CKeySymbol.encode("https://openckey.org") |
| 78 | val bitmap: Bitmap = symbol.toBitmap(sizePx = 600) |
| 79 | ``` |
| 80 | |
| 81 | See [sdk/android](sdk/android/README.md). |
| 82 | |
| 83 | ### .NET |
| 84 | |
| 85 | ```csharp |
| 86 | using OpenCKey; |
| 87 | |
| 88 | CKeySymbol symbol = CKeySymbol.Encode("https://openckey.org"); |
| 89 | byte[] png = symbol.ToPng(1024); |
| 90 | string svg = symbol.ToSvg(scale: 8, style: CKeyStyle.Concept); |
| 91 | ``` |
| 92 | |
| 93 | `CKey.Wpf` adds a WPF control. See [sdk/dotnet](sdk/dotnet/README.md). |
| 94 | |
| 95 | ### Command line |
| 96 | |
| 97 | ```sh |
| 98 | ckey encode-scalable --utf8 "https://openckey.org" --raster code.png --size-px 1024 |
| 99 | ckey encode-scalable --utf8 "https://openckey.org" --pdf code.pdf --size-in 2 |
| 100 | ckey encode-scalable --utf8 "https://openckey.org" --preset concept --modules circle --out styled.svg |
| 101 | ckey encode-scalable --utf8 "https://openckey.org" --layout print --png label.png --size-in 0.25 --dpi 600 |
| 102 | ``` |
| 103 | |
| 104 | ### Build from source |
| 105 | |
| 106 | ```sh |
| 107 | cmake -S . -B build -DCMAKE_BUILD_TYPE=Release |
| 108 | cmake --build build -j |
| 109 | ctest --test-dir build --output-on-failure |
| 110 | cmake --install build --prefix /usr/local # find_package(CKey): CKey::core, CKey::scan, ... |
| 111 | ``` |
| 112 | |
| 113 | The core is C++20 behind a C ABI, [`include/ckey/ckey.h`](include/ckey/ckey.h). See [`examples/c`](examples/c) for a complete encode, render and scan in C++. |
| 114 | |
| 115 | ## What CKey can do |
| 116 | |
| 117 | - **One design at 31 sizes.** Profile 0 runs from version 1 (29 modules across, 27 bytes at level M) to version 31 (232 across, 4,619 bytes). The reader identifies the version from the symbol itself. |
| 118 | - **Four error-correction levels.** L, M, Q and H correct about 7, 14, 22 and 30% of each block. |
| 119 | - **A print layout.** Profile 0.1 has larger marks and gaps for small printed labels ([printing guide](spec/CKey-Printing.md)). |
| 120 | - **Styles that still scan.** Colours, vignette, metallic sheen, accent colours, transparency, module shapes, joined or dotted rings, bevel, depth, grain and a centre logo ([design system](spec/CKey-Design-System.md)). |
| 121 | - **Certification.** The core photographs a styled code in a model (tilted, blurred, noisy, under glare), reads it back with the real decoder, and grades it against plain black on white. A model, not a guarantee. |
| 122 | - **Native output.** RGBA and grayscale pixels, PNG, SVG and vector PDF, rendered directly from the geometry. |
| 123 | - **Scanning.** Full-frame localization and decoding of grayscale camera frames, separate from the renderer, so a scanner can ship without it. |
| 124 | - **Safe payloads.** Readers show what a code holds and act only on a tap ([payload conventions](spec/CKey-Payload-Conventions.md)). The one exception is a **Safe Action**: a code signed by a known site for a known app, which the official SDKs verify before anything runs, and which still needs the person's confirmation when it approves something on another device ([Safe Actions](spec/CKey-Safe-Actions.md)). |
| 125 | - **Optional telemetry.** Aggregate scan counts, never content or identifiers; `CKey.telemetry = 0` turns it off ([details](docs/adoption-and-telemetry.md)). |
| 126 | |
| 127 | ## Documentation |
| 128 | |
| 129 | | | | |
| 130 | |---|---| |
| 131 | | [Technical overview](docs/OVERVIEW.md) | The formats, libraries and tools, with commands | |
| 132 | | [Gallery](docs/gallery/README.md) | Rendered examples and how to rebuild them | |
| 133 | | [Field tests](field-tests/README.md) | Real-world tests anyone can run and report; results are public at [openckey.org/tests](https://openckey.org/tests) | |
| 134 | | [Profile 0 Format 0.27.0](spec/CKey-Format-v0.27.0.md) | The scalable family | |
| 135 | | [Profile 0.1 Format 0.28.0](spec/CKey-Format-v0.28.0.md) | The print layout | |
| 136 | | [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), [Profile 3 Format 0.26.0](spec/CKey-Format-v0.26.0.md) | The locator, text and extended profiles | |
| 137 | | [`.ckey` interchange](spec/CKey-Interchange-v1.md) | The optional `.ckey` file | |
| 138 | | [Payload conventions](spec/CKey-Payload-Conventions.md) | What a reader shows and offers for each kind of payload | |
| 139 | | [Safe Actions](spec/CKey-Safe-Actions.md) | Signed actions a reader may run without asking first, and how they are verified | |
| 140 | | [Rendering, SDK, distribution and telemetry specification](docs/SPECIFICATION-rendering-sdk-distribution-telemetry.md) | What the SDKs and releases must do; status in [implementation status](docs/IMPLEMENTATION-STATUS.md) | |
| 141 | | [Platform integration](docs/platform-integration.md) | Adding the scanner to a camera platform | |
| 142 | | [Release and versioning map](docs/RELEASE-AND-VERSIONING-MAP.md) | Versions, formats, ABI history and the release procedure | |
| 143 | | [Publishing](docs/PUBLISHING.md) | How each package is published from a release tag | |
| 144 | | [Research and licence audit](spec/RESEARCH.md) | The research behind the design, and dependency licences | |
| 145 | |
| 146 | ## Branches and releases |
| 147 | |
| 148 | | Branch | Purpose | |
| 149 | |---|---| |
| 150 | | `Stable-Release` | The supported source. Every release is an immutable tag here, such as `v0.1.0-build.85`. Fork from here. | |
| 151 | | `community` | Experimental contributions. Unstable: do not depend on it in production. | |
| 152 | | `scratch` | The maintainer's working branch. | |
| 153 | |
| 154 | Changelogs: [`CHANGELOG-STABLE.md`](CHANGELOG-STABLE.md) for releases, [`CHANGELOG-COMMUNITY.md`](CHANGELOG-COMMUNITY.md) for community merges, and [`CHANGELOG.md`](CHANGELOG.md) for every build. See [branches and releases](docs/BRANCHES-AND-RELEASES.md). |
| 155 | |
| 156 | ## Contributing and security |
| 157 | |
| 158 | See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute, and [SECURITY.md](SECURITY.md) to report a vulnerability privately. |
| 159 | |
| 160 | ## Licence |
| 161 | |
| 162 | MIT. See [LICENSE](LICENSE). © 2026 ClearKey Solutions, LLC. |