dotcode-decoder 1.0.0__tar.gz

dotcode_decoder-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,219 @@
+# 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/dotcode/__init__.py

@@ -0,0 +1,9 @@
+"""
+DotCode Decoder - Fast 2D barcode reader (Conveyor ready)
+"""
+
+from .decoder import DotCodeDecoder, decode
+from .utils import DecodeResult, DecodeStage
+
+__version__ = "1.0.0"
+__all__ = ['DotCodeDecoder', 'decode', 'DecodeResult', 'DecodeStage']