Skip to main content

Crate forgesworn_qr

Crate forgesworn_qr 

Source
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 QrCode returned by the encoder. Their string options are escaped for XML. A margin whose resulting side cannot fit in usize causes 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 toSvg and toTerminal give 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. channels is 4 (RGBA) or 1 (grey); rows are width pixels apart.