QRustie 🔍

A trusty QR code scanner built with Rust for the Cannlytics COA pipeline.

Introduction

QRustie reliably decodes QR codes from image files using dual decoding engines and intelligent image preprocessing. It is purpose-built for the Cannlytics Certificate of Analysis (COA) data pipeline, where QR codes embedded in lab test PDFs often link back to the original COA portal URL.

Why Rust?

Python QR decoders crash catastrophically on certain COA documents (notably from New York labs), killing the interpreter with no recoverable error. Rust's memory safety guarantees mean that even malformed QR data produces clean errors rather than segfaults.

Design Principles

• Reliable parsing — Dual engines (rqrr + bardecoder) with 4 preprocessing strategies
• Minimal dependencies — Pure Rust where possible, no system library requirements
• Clear interface — JSON output to stdout for clean subprocess integration
• Well-tested — Deterministic exit codes and structured error reporting
• Comprehensive documentation — Every function documented
• Packaged for use — Single binary, easy to build and deploy
• Easy to maintain — Simple, readable code with clear architecture

Installation

Prerequisites

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build

cd qrustie
cargo build --release

The binary will be at target/release/qrustie (or target/release/qrustie.exe on Windows).

Usage

Single Image

# Decode a QR code from an image
qrustie --input image.png

# Output (JSON to stdout):
# {"file":"image.png","found":true,"data":["https://lab.example.com/coa/12345"],"decoder":"rqrr","strategy":"original","error":""}

Batch Mode

# Scan all images in a directory
qrustie --input ./coa_images/ --batch

# Output (JSON):
# {"total":150,"found":42,"results":[...]}

Options

Flag	Short	Description
--input <PATH>	-i	Input image file or directory
--batch	-b	Process all images in directory
--first-only	-f	Return only the first QR code found
--verbose	-v	Print debug info to stderr

Exit Codes

Code	Meaning
0	QR code(s) found and decoded
1	No QR code found (image processed successfully)
2	Error (bad file, invalid image, etc.)

JSON Output Schema

Single file:

{
  "file": "path/to/image.png",
  "found": true,
  "data": ["https://example.com/coa/12345"],
  "decoder": "rqrr",
  "strategy": "original",
  "error": ""
}

Batch mode:

{
  "total": 100,
  "found": 42,
  "results": [
    {"file": "img1.png", "found": true, "data": ["..."], ...},
    {"file": "img2.png", "found": false, "data": [], ...}
  ]
}

Calling from Python

QRustie is designed to be called from Python via subprocess:

import json
import subprocess

def decode_qr(image_path: str, qrustie_path: str = 'qrustie') -> str | None:
    """Decode a QR code from an image using QRustie."""
    try:
        result = subprocess.run(
            [qrustie_path, '--input', image_path, '--first-only'],
            capture_output=True,
            text=True,
            timeout=30,
        )
        if result.returncode == 0:
            data = json.loads(result.stdout)
            if data.get('found') and data.get('data'):
                return data['data'][0]
    except (subprocess.TimeoutExpired, json.JSONDecodeError):
        pass
    return None

Decoding Strategy

QRustie applies 4 image preprocessing strategies in order, each tried with 2 decoder engines, for a total of 8 decode attempts per image:

#	Strategy	Description
1	original	Direct decode at native resolution
2	grayscale	Convert to grayscale first
3	high_contrast	Binary threshold for maximum contrast
4	downscaled	Reduce to ~1000px width (for 300 DPI renders)

The first successful decode is returned immediately (fail-fast on success).

Supported Formats

Format	Extensions
PNG	.png
JPEG	.jpg, .jpeg
BMP	.bmp
TIFF	.tiff, .tif
WebP	.webp

Architecture

scan_qrcodes.py (Python)         qrustie (Rust)
┌────────────────────┐           ┌──────────────────┐
│ PDF Discovery      │           │ Image Loading     │
│ Page → Image       │──image──▶│ Preprocessing     │
│ Caching (Bogart)   │           │ QR Detection      │
│ Hash Computation   │◀──JSON───│ JSON Output       │
│ URL Validation     │           └──────────────────┘
│ Results Merge      │
└────────────────────┘

Tests

cargo test

License

Copyright (c) 2025-2026 Cannlytics

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.