qrism/
lib.rs

1//! # qrism
2//!
3//! A Rust library for generating and reading QR codes with Reed-Solomon error correction.
4//! Supports traditional monochromatic QR codes with additional experimental multicolor QR
5//! support for enhanced storage capacity.
6//!
7//! ## Features
8//!
9//! - **QR Code Generation**: Create QR codes with customizable versions, error correction levels, and capacity
10//! - **QR Code Reading**: Detect and decode QR codes from images with robust error correction
11//! - **Reed-Solomon Error Correction**: Built-in error correction with configurable levels (L, M, Q, H)
12//! - **High Capacity QR Support**: Experimental polychromatic QR codes with 3x storage capacity
13//! - **Image Processing**: Advanced binarization and geometric correction for reliable detection
14//!
15//! ## Quick Start
16//!
17//! ### Simple QR Code Generation
18//!
19//! ```rust
20//! use qrism::QRBuilder;
21//!
22//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
23//! // Simplest usage - provide only data, all other settings are automatically chosen
24//! let qr = QRBuilder::new(b"Hello, World!")
25//!     .build()?;
26//!
27//! let img = qr.to_image(4);  // 4x scale factor
28//! img.save("simple_qr.png")?;
29//! # Ok(())
30//! # }
31//! ```
32//!
33//! ### Full Configuration
34//!
35//! ```rust
36//! use qrism::{QRBuilder, ECLevel, Version, MaskPattern};
37//!
38//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
39//! let data = "Hello, World!";
40//! let qr = QRBuilder::new(data.as_bytes())
41//!     .version(Version::Normal(2))  // QR version (size) - if not provided, finds smallest version to fit data
42//!     .ec_level(ECLevel::M)         // Error correction level - if not provided, defaults to ECLevel::M
43//!     .high_capacity(false)         // Standard capacity mode - if not provided, defaults to false
44//!     .mask(MaskPattern::new(3))    // Mask pattern - if not provided, finds best mask based on penalty score
45//!     .build()?;
46//!
47//! let img = qr.to_image(4);  // 4x scale factor
48//! img.save("configured_qr.png")?;
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! ### Reading a QR Code
54//!
55//! ```rust,no_run
56//! use qrism::reader::detect_qr;
57//!
58//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
59//! // Load and prepare image
60//! let img = image::open("qr_code.png")?;
61//!
62//! // Detect and decode QR codes
63//! let mut res = detect_qr(&img);
64//! if let Some(symbol) = res.symbols().first_mut() {
65//!     let (metadata, message) = symbol.decode()?;
66//!     println!("Decoded: {}", message);
67//! }
68//! # Ok(())
69//! # }
70//! ```
71//!
72//! ### Reading a high capacity multi color QR
73//!
74//! ```rust,no_run
75//! use qrism::reader::detect_hc_qr;
76//!
77//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
78//! // Load and prepare image
79//! let img = image::open("qr_code.png")?;
80//!
81//! // Detect and decode QR codes
82//! let mut res = detect_hc_qr(&img);
83//! if let Some(symbol) = res.symbols().first_mut() {
84//!     let (metadata, message) = symbol.decode()?;
85//!     println!("Decoded: {}", message);
86//! }
87//! # Ok(())
88//! # }
89//! ```
90//!
91//! ## QR Code Components
92//!
93//! ### Versions
94//! - **Micro QR**: Versions 1-4 for small data (experimental)
95//! - **Normal QR**: Versions 1-40, with sizes from 21x21 to 177x177 modules
96//!
97//! ### Error Correction Levels
98//! - **L (Low)**: ~7% error correction
99//! - **M (Medium)**: ~15% error correction  
100//! - **Q (Quartile)**: ~25% error correction
101//! - **H (High)**: ~30% error correction
102//!
103//! ## High Capacity QR Codes
104//!
105//! High capacity QR codes are an extension of traditional QR codes that achieve **3x the storage capacity**
106//! by leveraging color channels for data encoding. Unlike standard monochromatic QR codes that use only black and white modules,
107//! high capacity QR codes utilize the full RGB color spectrum.
108//!
109//! ### How It Works
110//!
111//! The technology works by **multiplexing three separate QR codes** into a single visual code by
112//! encoding one in each of the red, green and blue color channels.
113//! Each color channel carries its own independent QR code with full Reed-Solomon error correction.
114//! When decoded, the three separate data streams are combined to reconstruct the original data,
115//! effectively tripling the storage capacity compared to traditional QR codes.
116//!
117//! ### Example Usage
118//!
119//! ```rust
120//! use qrism::QRBuilder;
121//!
122//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
123//! // Create a high capacity QR code with 3x storage
124//! let large_data = "Large dataset that would not fit in a standard QR code...".repeat(10);
125//! let qr = QRBuilder::new(large_data.as_bytes())
126//!     .high_capacity(true)  // Enable high capacity mode
127//!     .build()?;
128//!
129//! let img = qr.to_image(4);
130//! img.save("high_capacity_qr.png")?;
131//! # Ok(())
132//! # }
133//! ```
134
135#![allow(
136    clippy::items_after_test_module,
137    unused_variables,
138    dead_code,
139    mixed_script_confusables,
140    clippy::suspicious_arithmetic_impl,
141    clippy::suspicious_op_assign_impl
142)]
143
144pub mod builder;
145pub(crate) mod common;
146pub mod reader;
147
148pub use builder::QRBuilder;
149pub use common::mask::MaskPattern;
150pub use common::metadata::{ECLevel, Version};
151pub(crate) use common::*;
152pub use reader::*;
153
154#[cfg(test)]
155pub(crate) use builder::Module;
qrism/lib.rs

qrism/
lib.rs
