Metadata-Version: 2.4
Name: list-decoder-qr
Version: 0.1.3
Summary: List Decoder for QR codes
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 for 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. 

## 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)
- OpenCV (`opencv-python`)

## Optional C++ Acceleration

The package includes an optional C++ backend (`wu_core`) built with pybind11 that provides a massive speedup. It is automatically used if compiled:

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

## License

MIT
