Expand description
§forgesworn-qr
A QR code encoder and image decoder with no runtime dependencies. Encode text or bytes, decode greyscale or RGBA pixels, and render SVG or terminal text. Rust 1.96 or newer is required. Licensed under MIT.
[dependencies]
forgesworn-qr = "0.3"use forgesworn_qr::{encode, render, symbol};
let code = encode::encode("Made with QR", &encode::Options::default())?;
let svg = render::to_svg(&code, &render::SvgOptions::default());
assert!(svg.starts_with("<svg"));
let decoded = symbol::decode_modules(&code.modules, code.size)
.expect("the generated grid is readable");
assert_eq!(decoded.payload.text, "Made with QR");For pictures, use decode::decode. Pass a byte slice, width, height, channels
(1 for greyscale or 4 for RGBA), row stride in pixels, an
Inversion choice, and None for optional work counters. Transparent RGBA
pixels are blended onto white. The returned Reading includes payload,
orientation, polarity and finder locations. There is no camera integration,
PNG/JPEG loader or canvas renderer in the crate.
§API and input contracts
The supported application entry points are encode::encode,
decode::decode, symbol::decode_modules, render::to_svg and
render::to_terminal, together with their option and result types.
Version 0.3 is a pre-1.0 release: breaking API changes require a new minor
version. The publicly accessible pipeline stages (front, binarise,
locate, place, refine, tables and low-level symbol routines) are
implementation APIs. They require valid dimensions, buffers and intermediate
state; they can panic on malformed inputs and are not the recommended entry
points for untrusted images.
- Encoding validates options and QR capacity and returns
Result. - Picture decoding validates channels, dimensions, stride and buffer length,
including overflow. Invalid input and an unreadable image both return
None. - Grid decoding accepts legal QR side lengths from 21 to 177 in steps of four
and rejects invalid dimensions or short buffers with
None. Nonzero module bytes mean dark. Both ordinary and transposed grids are tried. - Renderers require an unmodified
QrCodereturned by the encoder. Their string options are escaped for XML. A margin whose resulting side cannot fit inusizecauses an explicit panic. Bound caller-supplied margins: terminal output grows quadratically, and ordinary allocation limits still apply. Public struct fields do not validate manually constructed values.
The decoder reads one symbol per call. It reports structured-append metadata but does not assemble multiple symbols. As with any parser working on large images, applications should impose input-size and resource limits appropriate to their environment.
§Character sets and WebAssembly
Native Rust and the default standalone WebAssembly build contain no character tables. Kanji and most ECI text follow the SPEC platform-without-tables rules; Hanzi symbols are refused. Payload bytes and decoded text are distinct fields; do not assume every supported byte sequence has decoded Unicode text.
The host-text feature is for the packaged JavaScript WebAssembly adapter. On
WebAssembly it requires that adapter’s text-decoding import; it is not a
general native character-set feature. The npm package @forgesworn/qr supplies
the browser/worker adapter and separately qualified WASM asset.
§Conformance and evidence
The TypeScript, Kotlin and Rust implementations share a specified decoder and generated conformance vectors. The published crate includes self-contained library unit tests and this doctest. The repository’s larger cross-language tests, photo corpus and benchmark harnesses live in the repository and are not included in the crate archive.
Measured results and limitations identify exact builds, corpora and hardware. WebAssembly measurements are not native Rust latency measurements; synthetic images are not physical-camera qualification. QR does not claim to outperform ZXing on every workload.
Project documentation · Source and issues · Security reporting
Modules§
- binarise
- Greyscale, binarisation, inversion and reduction (SPEC.md decoder steps 1, 2 and 9).
- decode
- The whole decoder: the ordinary search in each polarity (SPEC.md steps 3 to 7), the second look (step 8) and the reduced-size pass (step 9).
- encode
- The encoder, written from SPEC.md (Input to Output): mode and segment choice, version choice, the bit stream, padding, Reed-Solomon, the matrix, masks and their penalties, format and version information.
- locate
- Row edges and the finder scan (SPEC.md decoder step 3).
- place
- Finder triples, size estimates and sampling maps (SPEC.md decoder steps 4 and 5).
- refine
- The second look (SPEC.md, decoder step 8): when the ordinary search finds nothing, a few maps whose format information already agrees are read again with their module centres moved onto the edges the picture shows, sampling grey rather than black and white.
- render
- Renderers: a standalone SVG document and block characters for a terminal.
Both give exactly the strings the TypeScript
toSvgandtoTerminalgive for the same options. There is no canvas renderer. - symbol
- Reading a module grid: format and version information, bit placement, unmasking, de-interleaving, Reed-Solomon, and the segments (SPEC.md decoder steps 6 and 7).
- tables
- Error correction blocks (ISO/IEC 18004:2015 Table 9) and alignment pattern centres (Annex E).
Constants§
- MIN_
REDUCED - A reduced picture narrower or shorter than this cannot hold a version 1 symbol.
- REDUCTIONS
- The reduction factors, coarse to fine.
- TOLERANCES
- The two tolerances of the finder scan, strict then looser.
Functions§
- front
- What the decoder does on a frame that yields no finder triple: greyscale,
then the scan at full size and at each reduced size that can hold a symbol.
Returns the number of finder candidates found in all.
channelsis 4 (RGBA) or 1 (grey); rows arewidthpixels apart.