list-decoder-qr 0.1.0__tar.gz

list_decoder_qr-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include requirements.txt
+include qr_list_decoder/wu_core.cpp

list_decoder_qr-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: list-decoder-qr
+Version: 0.1.0
+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

list_decoder_qr-0.1.0/README.md

@@ -0,0 +1,148 @@
+# 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

list_decoder_qr-0.1.0/list_decoder_qr.egg-info/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: list-decoder-qr
+Version: 0.1.0
+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

list_decoder_qr-0.1.0/list_decoder_qr.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+setup.py
+list_decoder_qr.egg-info/PKG-INFO
+list_decoder_qr.egg-info/SOURCES.txt
+list_decoder_qr.egg-info/dependency_links.txt
+list_decoder_qr.egg-info/requires.txt
+list_decoder_qr.egg-info/top_level.txt
+qr_list_decoder/__init__.py
+qr_list_decoder/matrix.py
+qr_list_decoder/wu_core.cpp
+qr_list_decoder/wu_qr.py
+tests/test_decoder.py

list_decoder_qr-0.1.0/list_decoder_qr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

list_decoder_qr-0.1.0/list_decoder_qr.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy
+Pillow

list_decoder_qr-0.1.0/list_decoder_qr.egg-info/top_level.txt

@@ -0,0 +1 @@
+qr_list_decoder

list_decoder_qr-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=64", "pybind11>=2.10"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "list-decoder-qr"
+version = "0.1.0"
+description = "Wu's list decoder for Reed-Solomon / QR codes over GF(2^8)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+dependencies = ["numpy", "Pillow"]
+
+[project.urls]
+Homepage = "https://github.com/Tejas423/List-Decoding-of-QR-codes"

list_decoder_qr-0.1.0/qr_list_decoder/__init__.py

@@ -0,0 +1,101 @@
+"""
+qr_list_decoder — Wu's list decoder for Reed-Solomon / QR codes.
+
+This package provides a pure-Python (with optional C++ acceleration)
+implementation of Wu's rational interpolation-based list decoder for
+Reed-Solomon codes over GF(2^8), targeting QR-code applications.
+
+Quick start::
+
+    from qr_list_decoder import wu_decode, rs_encode, rs_syndromes
+
+    # Encode a message
+    codeword = rs_encode(n=26, k=9, message=[72, 101, 108, 108, 111])
+
+    # Decode a corrupted codeword (list decoding beyond t0)
+    candidates = wu_decode(n=26, k=9, received=corrupted_cw)
+"""
+
+from .wu_qr import (
+    # --- Encoding ---
+    rs_generator,
+    rs_encode,
+
+    # --- Syndrome computation ---
+    rs_syndromes,
+
+    # --- Berlekamp-Massey ---
+    berlekamp_massey,
+
+    # --- Wu list decoder (main entry point) ---
+    wu_decode,
+    wu_params,
+
+    # --- Sub-components (for advanced users) ---
+    build_interp,
+    nullspace,
+    hensel_series,
+    rr_series,
+    recover_from_series,
+    chien_search,
+    decode_from_positions,
+
+    # --- GF(2^8) arithmetic utilities ---
+    gf_mul,
+    gf_inv,
+    gf_div,
+    gf_pow,
+
+    # --- Polynomial utilities ---
+    padd,
+    pmul,
+    peval,
+    pdeg,
+)
+
+from .matrix import (
+    decode_raw_matrix,
+    decode_qr_image,
+    make_qr_matrix,
+    get_best_qr_matrix,
+    read_qr_image,
+    qr_encode_text,
+    qr_decode_text,
+    extract_qr_data,
+    render_qr,
+    decode_folder,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "rs_generator",
+    "rs_encode",
+    "rs_syndromes",
+    "berlekamp_massey",
+    "wu_decode",
+    "wu_params",
+    "build_interp",
+    "nullspace",
+    "hensel_series",
+    "rr_series",
+    "recover_from_series",
+    "chien_search",
+    "decode_from_positions",
+    "gf_mul",
+    "gf_inv",
+    "gf_div",
+    "gf_pow",
+    "padd",
+    "pmul",
+    "peval",
+    "pdeg",
+    "decode_raw_matrix",
+    "decode_qr_image",
+    "make_qr_matrix",
+    "read_qr_image",
+    "qr_encode_text",
+    "qr_decode_text",
+    "extract_qr_data",
+    "render_qr",
+    "decode_folder",
+]