Metadata-Version: 2.4
Name: list-decoder-qr
Version: 0.1.1
Summary: Wu's list decoder for Reed-Solomon / QR codes over GF(2^8)
Author: Tejas
License: MIT
Project-URL: Homepage, https://github.com/Tejas423/List-Decoding-of-QR-codes
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: Pillow
Dynamic: author
Dynamic: requires-python

# 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):**
```bash
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:
```bash
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```bash
pip install pybind11
python setup.py build_ext --inplace
```

## License

MIT
