CKey

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.

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 is the only official home of CKey.

<p align="center"> <img src="docs/gallery/link-plain.png" width="150" alt="A CKey holding a link, black on white"> <img src="docs/gallery/concept.png" width="150" alt="A CKey in the Concept style"> <img src="docs/gallery/contact-evergreen.png" width="150" alt="A CKey holding a contact card, evergreen on paper"> <img src="docs/gallery/dots-navy.png" width="150" alt="A CKey with dotted rings and circle modules"> <img src="docs/gallery/dense.png" width="150" alt="A dense CKey holding about 560 bytes"> </p>

Every image above is rendered by the core and read back by the real decoder. See the gallery for what each one holds and how it certifies.

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 are how they will be: run one and report what you find.

Install

The current release is 0.1.0-build.85. Every package wraps the same C core.

Release archives for every package, with SHA256SUMS and build provenance, are on the GitHub Releases page and at openckey.org/downloads. Check the SHA-256 of anything you download.

Swift

// Package.swift
.package(url: "https://github.com/clearkeysolutions/ckey", from: "0.1.0-build.85"),
.target(name: "MyApp", dependencies: [.product(name: "CKey", package: "ckey")]),

import CKey

let symbol = try CKeySymbol.encode("https://openckey.org")
let image: CGImage = try symbol.cgImage(size: 1024)
let pdf: Data = try symbol.pdfData(widthPoints: 144)        // 2 inches wide

CKeyScanner (module CKeyScanKit) is a scan-only product with no renderer and no telemetry. See sdk/swift.

Web

import { loadCKey } from 'openckey';

const ckey = await loadCKey();
const sym = ckey.encode('https://openckey.org');
ckey.renderToCanvas(sym, document.querySelector('canvas'), { size: 512 });
const png = ckey.renderPNG(sym, { size: 1024 });
sym.free();

See sdk/web.

Android

dependencies {
    implementation("org.openckey:ckey:0.1.0-build.85")
    implementation("org.openckey:ckey-compose:0.1.0-build.85")   // optional: CKeyImage
    implementation("org.openckey:ckey-camerax:0.1.0-build.85")   // optional: CKeyAnalyzer
}

val symbol = CKeySymbol.encode("https://openckey.org")
val bitmap: Bitmap = symbol.toBitmap(sizePx = 600)

See sdk/android.

.NET

using OpenCKey;

CKeySymbol symbol = CKeySymbol.Encode("https://openckey.org");
byte[] png = symbol.ToPng(1024);
string svg = symbol.ToSvg(scale: 8, style: CKeyStyle.Concept);

CKey.Wpf adds a WPF control. See sdk/dotnet.

Command line

ckey encode-scalable --utf8 "https://openckey.org" --raster code.png --size-px 1024
ckey encode-scalable --utf8 "https://openckey.org" --pdf code.pdf --size-in 2
ckey encode-scalable --utf8 "https://openckey.org" --preset concept --modules circle --out styled.svg
ckey encode-scalable --utf8 "https://openckey.org" --layout print --png label.png --size-in 0.25 --dpi 600

Build from source

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure
cmake --install build --prefix /usr/local     # find_package(CKey): CKey::core, CKey::scan, ...

The core is C++20 behind a C ABI, include/ckey/ckey.h. See examples/c for a complete encode, render and scan in C++.

What CKey can do

• 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.
• Four error-correction levels. L, M, Q and H correct about 7, 14, 22 and 30% of each block.
• A print layout. Profile 0.1 has larger marks and gaps for small printed labels (printing guide).
• 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).
• 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.
• Native output. RGBA and grayscale pixels, PNG, SVG and vector PDF, rendered directly from the geometry.
• Scanning. Full-frame localization and decoding of grayscale camera frames, separate from the renderer, so a scanner can ship without it.
• Safe payloads. Readers show what a code holds and act only on a tap (payload conventions). 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).
• Optional telemetry. Aggregate scan counts, never content or identifiers; CKey.telemetry = 0 turns it off (details).

Documentation

Branches and releases

Changelogs: CHANGELOG-STABLE.md for releases, CHANGELOG-COMMUNITY.md for community merges, and CHANGELOG.md for every build. See branches and releases.

Contributing and security

See CONTRIBUTING.md to contribute, and SECURITY.md to report a vulnerability privately.

Licence

MIT. See LICENSE. © 2026 ClearKey Solutions, LLC.