dotcode-decoder 1.0.0__py3-none-any.whl

dotcode/rs.py

@@ -0,0 +1,212 @@
+"""
+Reed-Solomon error correction over GF(113)
+"""
+
+P = 113
+ALPHA = 3
+
+DOT_PATTERNS = [
+    "101010101","010101011","010101101","010110101","011010101","101010110","101011010","101101010",
+    "110101010","010101110","010110110","010111010","011010110","011011010","011101010","100101011",
+    "100101101","100110101","101001011","101001101","101010011","101011001","101100101","101101001",
+    "110010101","110100101","110101001","001010111","001011011","001011101","001101011","001101101",
+    "001110101","010010111","010011011","010011101","010100111","010110011","010111001","011001011",
+    "011001101","011010011","011011001","011100101","011101001","100101110","100110110","100111010",
+    "101001110","101011100","101100110","101101100","101110010","101110100","110010110","110011010",
+    "110100110","110101100","110110010","110110100","111001010","111010010","111010100","001011110",
+    "001101110","001110110","001111010","010011110","010111100","011001110","011011100","011100110",
+    "011101100","011110010","011110100","100010111","100011011","100011101","100100111","100110011",
+    "100111001","101000111","101100011","101110001","110001011","110001101","110010011","110011001",
+    "110100011","110110001","111000101","111001001","111010001","000101111","000110111","000111011",
+    "000111101","001001111","001100111","001110011","001111001","010001111","011000111","011100011",
+    "011110001","100011110","100111100","101111000","110001110","110011100","110111000","111000110",
+    "111001100",
+]
+DOT_TO_VAL = {p: i for i, p in enumerate(DOT_PATTERNS)}
+
+def gf_inv(a): 
+    return pow(a, P-2, P)
+
+def gf_add(a, b): 
+    return (a + b) % P
+
+def gf_sub(a, b): 
+    return (a - b) % P
+
+def gf_mul(a, b): 
+    return (a * b) % P
+
+def gf_div(a, b): 
+    return gf_mul(a, gf_inv(b))
+
+def gf_pow(a, k): 
+    return pow(a, k, P) if k >= 0 else gf_inv(pow(a, -k, P))
+
+def ptrim(p):
+    i = len(p)-1
+    while i > 0 and p[i] % P == 0: 
+        i -= 1
+    return p[:i+1]
+
+def pmul(a, b):
+    out = [0] * (len(a) + len(b) - 1)
+    for i, ai in enumerate(a):
+        if ai % P == 0: 
+            continue
+        for j, bj in enumerate(b):
+            if bj % P == 0: 
+                continue
+            out[i+j] = gf_add(out[i+j], gf_mul(ai, bj))
+    return ptrim(out)
+
+def peval(p, x):
+    acc = 0
+    for c in reversed(p): 
+        acc = gf_add(gf_mul(acc, x), c)
+    return acc
+
+def pder(p):
+    if len(p) <= 1: 
+        return [0]
+    out = [0] * (len(p)-1)
+    for i in range(1, len(p)): 
+        out[i-1] = gf_mul(p[i], i % P)
+    return ptrim(out)
+
+def pmod_xk(p, k):
+    q = p[:k] if len(p) > k else p[:]
+    if len(q) < k: 
+        q += [0] * (k - len(q))
+    return q
+
+def syndromes(r, NC):
+    S = []
+    for i in range(1, NC+1):
+        s = 0
+        for j, rj in enumerate(r):
+            if rj % P == 0: 
+                continue
+            s = gf_add(s, gf_mul(rj, gf_pow(ALPHA, i * j)))
+        S.append(s)
+    return S
+
+def erasure_locator(pos):
+    L = [1]
+    for j in pos: 
+        L = pmul(L, [1, gf_sub(0, gf_pow(ALPHA, j))])
+    return L
+
+def berlekamp_massey(S):
+    N = len(S)
+    if N == 0: 
+        return [1]
+    
+    def s(k): 
+        return S[k] if 0 <= k < N else 0
+    
+    C = [0]*(N+1)
+    C[0] = 1
+    B = [0]*(N+1)
+    B[0] = 1
+    L, m, b = 0, 1, 1
+    
+    for n in range(N):
+        d = s(n)
+        for i in range(1, L+1): 
+            d = gf_add(d, gf_mul(C[i], s(n-i)))
+        
+        if d % P == 0:
+            m += 1
+            continue
+        
+        fac = gf_div(d, b)
+        sB = [0]*(N+1)
+        for k in range(N+1-m): 
+            sB[k+m] = B[k]
+        
+        Cn = C[:]
+        for k in range(N+1): 
+            Cn[k] = gf_sub(Cn[k], gf_mul(fac, sB[k]))
+        
+        if 2*L <= n:
+            L = n+1-L
+            B = C[:]
+            b = d
+            m = 1
+            C = Cn
+        else:
+            m += 1
+            C = Cn
+    
+    idx = N
+    while idx > 0 and C[idx] % P == 0:
+        idx -= 1
+    C = C[:idx+1]
+    
+    if C and C[0] % P != 1:
+        inv = gf_inv(C[0])
+        C = [gf_mul(c, inv) for c in C]
+    
+    return C
+
+def rs_correct(mask_sym, vals, ND, NC, era_idx):
+    NW = len(vals)
+    r = [mask_sym] + [(v if v is not None else 0) for v in vals]
+    era = [1 + i for i in era_idx if 0 <= i < NW]
+    S = syndromes(r, NC)
+    
+    if all(s % P == 0 for s in S) and not era:
+        return [v if v is not None else 0 for v in vals], []
+    
+    if len(era) > NC:
+        return None
+    
+    Le = erasure_locator(era)
+    SLe = pmod_xk(pmul(S[:], Le), NC)
+    Lu = berlekamp_massey(SLe)
+    Lam = ptrim(pmul(Le, Lu))
+    Om = pmod_xk(pmul(S[:], Lam), NC)
+    Ld = pder(Lam)
+    
+    err_pos = []
+    err_mag = {}
+    
+    for j in range(len(r)):
+        x = gf_pow(ALPHA, -j)
+        if peval(Lam, x) % P == 0:
+            if j == 0:
+                continue
+            num = peval(Om, x)
+            den = peval(Ld, x)
+            if den % P == 0:
+                continue
+            mag = gf_sub(0, gf_div(num, den))
+            if mag % P != 0:
+                err_pos.append(j)
+                err_mag[j] = mag
+    
+    rc = r[:]
+    for j in err_pos:
+        rc[j] = gf_sub(rc[j], err_mag[j])
+    
+    Sa = syndromes(rc, NC)
+    if any(s % P != 0 for s in Sa):
+        return None
+    
+    return rc[1:], [p-1 for p in err_pos]
+
+def solve_ND_NC(NW):
+    for ND in range(0, NW+1):
+        NC = 3 + ((ND+1)//2)
+        if ND + NC == NW:
+            return (ND, NC)
+    
+    for ND in range(0, NW+1):
+        NC = 3 + (ND//2)
+        if ND + NC == NW:
+            return (ND, NC)
+    
+    return None, None
+
+def mask_step(mid):
+    return [0, 3, 7, 17][mid]

dotcode/setup.py

@@ -0,0 +1,26 @@
+from setuptools import find_packages, setup
+
+setup(
+    name="dotcode-decoder",
+    version="1.0.0",
+    description="Fast DotCode 2D barcode decoder with iterative regression",
+    author="Anish karki",
+    packages=find_packages(),
+    install_requires=[
+        "opencv-python>=4.5.0",
+        "numpy>=1.19.0",
+    ],
+    python_requires=">=3.7",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Topic :: Multimedia :: Graphics",
+        "Topic :: Scientific/Engineering :: Image Recognition",
+    ],
+    keywords="barcode dotcode decoder 2d",
+)

dotcode/utils.py

@@ -0,0 +1,36 @@
+"""
+Shared types, constants, and result objects
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+# Constants
+GRID_ROWS = 10
+GRID_COLS = 47
+MIN_DOTS = 12
+EARLY_EXIT_CONFIDENCE = 0.30
+REGRESSION_ITERATIONS = 2
+
+class DecodeStage(Enum):
+    REGRESSION = 1
+    ANGLE_SWEEP = 2
+    INVERT = 3
+
+@dataclass
+class DecodeResult:
+    success: bool
+    message: Optional[str] = None
+    error: Optional[str] = None
+    file: Optional[str] = None
+    method: Optional[str] = None
+    elapsed_ms: float = 0.0
+    stage: Optional[DecodeStage] = None
+    confidence: float = 0.0
+    timed_out: bool = False
+    
+    def __repr__(self):
+        if self.success:
+            return f"DecodeResult(success=True, msg='{self.message}', time={self.elapsed_ms:.0f}ms)"
+        return f"DecodeResult(success=False, error='{self.error}', time={self.elapsed_ms:.0f}ms)"

dotcode_decoder-1.0.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: dotcode-decoder
+Version: 1.0.0
+Summary: Fast DotCode 2D barcode decoder
+Author: Anish karki
+Keywords: barcode dotcode decoder 2d
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: scipy>=1.7.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# DotCode Decoder
+
+[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/badge/pypi-v1.0.0-orange.svg)](https://pypi.org/project/dotcode)
+
+**Fast, accurate DotCode 2D barcode decoder for industrial and commercial applications.**
+
+---
+
+## 📦 Installation
+
+```bash
+pip install dotcode
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/dotcode.git
+cd dotcode
+pip install -e .
+```
+
+---
+
+## 🚀 Quick Start
+
+```python
+from dotcode import decode, DecodeResult
+
+# Single image
+result = decode("image.jpg")
+print(result.message)  # "25E13KXUKSXG1313"
+
+# With details
+result: DecodeResult = decode("image.jpg")
+print(f"Message: {result.message}")
+print(f"Time: {result.elapsed_ms:.0f}ms")
+print(f"Confidence: {result.confidence:.2f}")
+print(f"Method: {result.method}")
+
+# Batch decode
+results = decode_batch(["img1.jpg", "img2.jpg", "img3.jpg"])
+for r in results:
+    print(f"{r.file}: {r.message} ({r.elapsed_ms:.0f}ms)")
+```
+
+---
+
+## ⚙️ Advanced Usage
+
+```python
+from dotcode import DotCodeDecoder
+
+# Custom configuration
+decoder = DotCodeDecoder(
+    timeout_ms=500,      # Max time per image
+    confidence=0.35,     # Confidence threshold (0.20-0.40)
+    fast_mode=True,      # Fast decode (6 angles) or accurate (12 angles)
+    use_sauvola=False    # Sauvola thresholding for poor lighting
+)
+
+# Decode with custom settings
+result = decoder.decode("image.jpg")
+print(result.message)
+
+# Disable fast mode for better accuracy on difficult images
+decoder = DotCodeDecoder(fast_mode=False)
+```
+
+---
+
+## 📊 Performance
+
+| Metric | Value |
+|--------|-------|
+| **Accuracy** | **96.2%** (381/396 images) |
+| **Average Speed** | **41ms** per image |
+| **Success Rate** | 96%+ |
+| **Timeout** | 300ms (configurable) |
+| **Stage Distribution** | Regression: 27% \| Angle Sweep: 73% |
+
+### Performance by Stage
+
+| Stage | Images | Avg Time | Description |
+|-------|--------|----------|-------------|
+| **Regression** | 103 (27%) | ~20ms | Fast path - direct grid fit |
+| **Angle Sweep** | 278 (73%) | ~45ms | Slower path - angle correction |
+| **Invert Fallback** | 0 | N/A | Last resort for inverted images |
+
+---
+
+## 🔧 How It Works
+
+1. **Dot Detection**  
+   Extracts dot centroids using adaptive thresholding (Otsu/fixed) with morphological erosion to separate touching dots.
+
+2. **Iterative Regression**  
+   Straightens tilted/skewed grids using per-row polynomial fitting with early exit when angle stabilizes.
+
+3. **Grid Snapping**  
+   Fits detected dots to a 10×47 checkerboard grid using k-means clustering (or optional Procrustes + RANSAC for difficult images).
+
+4. **Reed-Solomon Error Correction**  
+   Corrects errors in the extracted bitstream using Reed-Solomon decoding over GF(113) - handles up to 7 errors per code.
+
+5. **Text Decoding**  
+   Converts corrected values to readable text using DotCode code sets (A, B, C) with state machine for character encoding.
+
+---
+
+## 📁 Project Structure
+
+```
+dotcode/
+├── __init__.py          # Main exports
+├── decoder.py           # Core decoding logic
+├── image.py             # Image processing (thresholding, blob detection)
+├── codes.py             # DotCode code sets (A, B, C)
+├── rs.py                # Reed-Solomon error correction
+└── utils.py             # Utility classes and constants
+
+examples/
+├── basic_usage.py       # Simple decode example
+└── batch_usage.py       # Batch processing example
+
+tests/
+└── test_decoder.py      # Unit tests
+```
+
+---
+
+## 🔬 Algorithm Details
+
+### Reed-Solomon Error Correction
+- Field: **GF(113)**
+- Primitive element: **3**
+- Corrects up to **~5-7 errors** per code
+- Uses Berlekamp-Massey algorithm for error location
+
+### Iterative Regression
+- **2 iterations** (configurable)
+- **Early exit** when angle change < 0.1°
+- **Per-row quadratic fit** for curvature correction
+
+### Threshold Selection
+- **Otsu's method** (automatic)
+- **Fixed thresholds**: 105, 115, 125, 135, 145, 155, 165, 175
+- **Sauvola threshold** (local adaptive) - optional
+
+---
+
+## 🛠️ Requirements
+
+- Python 3.7+
+- OpenCV >= 4.5.0
+- NumPy >= 1.19.0
+- SciPy >= 1.7.0 (for KDTree)
+
+---
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Submit a pull request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/dotcode.git
+cd dotcode
+
+# Install in development mode
+pip install -e .
+
+# Run tests
+python test.py
+```
+
+---
+
+## 📚 References
+
+- [DotCode Specification (AIM)](https://www.aimglobal.org/dotcode)
+- [Wikipedia: DotCode](https://en.wikipedia.org/wiki/DotCode)
+- [Reed-Solomon Error Correction](https://en.wikipedia.org/wiki/Reed%E2%80%93Solomon_error_correction)
+
+---
+
+## 📧 Contact
+
+For questions or support:
+- GitHub Issues: [https://github.com/yourusername/dotcode/issues](https://github.com/yourusername/dotcode/issues)
+- Email: your.email@example.com
+
+---
+
+## ⭐ Acknowledgments
+
+This project builds on research in 2D barcode decoding and industrial computer vision. Special thanks to:
+
+- The open-source community for OpenCV, NumPy, and SciPy
+- AIM Global for the DotCode specification
+- Contributors who helped test and improve the decoder
+
+---
+
+**Made with ❤️ for industrial automation and barcode enthusiasts.**

dotcode_decoder-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+dotcode/__init__.py,sha256=fg8H7arLGK6Yj_mbvCqSsehUWM_cXSEx4mRNW6mQomQ,256
+dotcode/code.py,sha256=EhVIS3BIMy1esjIrSQcyTM2EOFLrJwDMiD1XkQVMwsE,35755
+dotcode/codes.py,sha256=9I9R9pCj8uV2PFdN3XDIunZMVj5H6QcqopPTrtzxM8M,6445
+dotcode/decoder.py,sha256=eyl4ODb6fLxIvXO1aOR-jfVv-bICqrqsn9-c0iF9I8s,37055
+dotcode/decoder_90.py,sha256=v99mhQX_WS1zuNLC5XiZt_mk5ml_R2FIQKqSzuQhbfQ,15138
+dotcode/image.py,sha256=N7RuvnPHusTEF0RlEbN1wS350qA_-J_IYkY55DmTK7o,87
+dotcode/images.py,sha256=o59vWCrrdUD_CKh4eKdFCn5BDn7LWNEHb2p2LDV8oUw,6255
+dotcode/rs.py,sha256=p6u7kAknqcpVulYigJ-XrfG0E36qqd1LhvoinxWxvSQ,5876
+dotcode/setup.py,sha256=yLk8trMdvHNSAPr47lr1hD2je-kGMdCMsZWZpzzKODo,891
+dotcode/utils.py,sha256=jL8e03M_027OTKzHwHhJACzDBOtuQC6yromc20mL6Cs,920
+dotcode_decoder-1.0.0.dist-info/METADATA,sha256=Xjq8im_7UibDLSXHQ97UPprIxKGiW4UDVFsAVHf5Dnc,6727
+dotcode_decoder-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+dotcode_decoder-1.0.0.dist-info/top_level.txt,sha256=2hWaRw8BGxQazH72zDHPMH8vrPyPQe5v81kJKxB7uzo,8
+dotcode_decoder-1.0.0.dist-info/RECORD,,

dotcode_decoder-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dotcode_decoder-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dotcode