list-decoder-qr 0.1.0

Wu's list decoder for Reed-Solomon / QR codes over GF(2^8)

qr-list-decoder

Wu's list decoder QR codes

Completed as Master's Thesis Project (MTP) in the CSE Department at IIT Bombay.

This library implements Wu's list decoding algorithm, enabling error correction beyond the standard decoding radius of the code. It can recover QR codes with significantly more damage than standard decoders can handle.

Not only does it contain the advanced mathematical backend, but it also includes an end-to-end QR code pipeline (generating matrices, reading images, unmasking, and decoding).

Installation

From PyPI (Recommended):

pip install list-decoder-qr

From Source / Development: If you want to modify the code locally, clone the repository and install it in editable mode:

pip install .
# or for development
pip install -e .

---

What You Can Do With This Library

Here are the main tasks you can perform with qr-list-decoder:

Task 1: Read a QR Code from an Image File

If you have a picture of a QR code and you want to extract the hidden text from it:

from qr_list_decoder import decode_qr_image

# Pass the path to your image
result = decode_qr_image("my_scratched_qr.png")

if result.get('wu_success') or result.get('bm_success'):
    print("Decoded Text:", result.get('wu_text') or result.get('bm_text'))
else:
    print("Decoding failed:", result.get('error'))

Task 2: Batch Process a Whole Folder of Images

If you have a folder containing hundreds of QR code images and want to decode all of them at once:

from qr_list_decoder import decode_folder

# This will scan the folder, process every image, and print the results
decode_folder("./dataset_of_qr_codes")

(You can also do this directly from the command line: python qr_demo.py --folder ./dataset_of_qr_codes)

Task 3: Generate a New QR Code Image

You can use the library to encode text and create your own QR code images:

from qr_list_decoder import qr_encode_text, get_best_qr_matrix, render_qr

# 1. Convert text to bytes (e.g., Version 2 QR)
data_bytes = qr_encode_text("Hi Tejas!", version=2)

# 2. Let the library calculate the ECC bytes and build the best 2D matrix
matrix, mask_used = get_best_qr_matrix(data_bytes, version=2, ecc_level='high')

# 3. Render the matrix into an image and save it!
img = render_qr(matrix, scale=10, fg=(0, 0, 0), bg=(255, 255, 255))
img.save("my_new_qr.png")

Task 4: Decode a Raw 2D Matrix

If you already extracted the binary grid yourself (or generated it) and want to bypass the image processing step:

from qr_list_decoder import decode_raw_matrix

# A 2D list or NumPy array where 1 is black and 0 is white.
my_matrix = [
    [1, 1, 1, 1, 1, 1, 1, 0, 0, 1, ...],
    [1, 0, 0, 0, 0, 0, 1, 0, 1, 1, ...],
    [1, 0, 1, 1, 1, 0, 1, 0, 0, 0, ...],
    # ... rest of the matrix rows
]

result = decode_raw_matrix(my_matrix)
if result.get('wu_success') or result.get('bm_success'):
    print("Decoded Text:", result.get('wu_text') or result.get('bm_text'))

Task 5: Byte-level Decoding

If you don't care about images or matrices, and just want to play with the underlying math:

from qr_list_decoder import rs_encode, wu_decode

# 1. Create a raw codeword
codeword = rs_encode(n=26, k=9, message=[72, 101, 108, 108, 111])

# 2. Simulate data corruption (flip random bytes)
corrupted = codeword.copy()
corrupted[2] ^= 255
corrupted[8] ^= 128
corrupted[14] ^= 42

# 3. Use Wu's algorithm to mathematically recover the original bytes!
candidates = wu_decode(n=26, k=9, received=corrupted)
print("Recovered bytes:", candidates[0])

---

API Reference

The library exposes the following high-level core API components. Please check the source code for more advanced mathematical helper functions.

Function	Description
rs_encode(n, k, message)	Encode a message into an RS(n, k) codeword
rs_syndromes(n, k, received)	Compute syndromes of a received word
berlekamp_massey(syndromes)	Run standard Berlekamp-Massey
wu_decode(n, k, received)	Main math entry point — list-decode a corrupted codeword
decode_qr_image(img_path)	Decode a QR code directly from an image file
decode_raw_matrix(matrix)	Decode a 2D array of 0s and 1s
decode_folder(path)	Batch process a folder of QR images

Dependencies

• Python ≥ 3.8
• NumPy
• Pillow (PIL)
• Optional: OpenCV (opencv-python) for robust perspective-unwarping on camera photos.

Optional C++ Acceleration

The package includes an optional C++ backend (wu_core) built with pybind11 that provides a massive ~20x-50x speedup on hot-path polynomial operations. It is automatically used if compiled:

pip install pybind11
python setup.py build_ext --inplace

License

MIT