QR Toolkit

An educational QR encoder and decoder implemented in Python. Rather than delegating the format to a QR library, the project works through finder-pattern detection, matrix extraction, masking, bitstream parsing, and Reed-Solomon correction directly.

Decoder pipeline

1. Load and threshold a QR image with OpenCV.
2. Detect finder patterns and infer module size.
3. Extract and orient the QR matrix.
4. Read format information and remove the data mask.
5. Traverse the data region in QR zig-zag order.
6. Apply Reed-Solomon correction where supported.
7. Decode numeric, alphanumeric, byte, or Kanji mode data.

Encoder pipeline

1. Encode the input message and character count.
2. Add terminator and padding bits.
3. Generate Reed-Solomon correction codewords.
4. Place functional patterns and message bits in the matrix.
5. Evaluate mask candidates and apply the best-scoring mask.
6. Render the final matrix as an image.

Project layout

File	Responsibility
read.py	finder-pattern detection, module extraction, and orientation
mask.py	format parsing, mask removal/application, and penalty scoring
decode.py	data traversal and message decoding
correction.py	error-correction level parsing and Reed-Solomon recovery
matrix_to_photo.py	message encoding, matrix construction, and rendering
utils.py	version, alignment, timing, and reserved-area helpers

Run locally

git clone https://github.com/Radu028/qr-toolkit.git
cd qr-toolkit
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python __main__.py

Choose 0 to decode an image from the current directory or 1 to generate a QR image from a message.

Scope

This is a learning-oriented implementation of the QR pipeline, not a drop-in replacement for a production QR library. Images with heavy perspective distortion or unsupported format combinations may require preprocessing.

Team

• Ionuț-Adelin Bâcă
• Radu-Stefan Popa
• Iulia-Maria Popescu

References

• Creating a QR Code step by step — Project Nayuki
• Thonky QR Code Tutorial
• QR Code Decoder