A powerful and modular Python CLI tool for converting binary files to QR codes and reconstructing them back to the original files. Features compression, error correction, file integrity verification, and a comprehensive modular architecture.

✨ Features

🔄 Bidirectional Conversion: Convert any binary file to QR codes and back
🗜️ Smart Compression: Reduce QR code count with configurable zlib compression
🛡️ Error Correction: Built-in QR code error correction for reliable scanning
🔒 Integrity Verification: SHA-256 hash verification ensures data integrity
🎛️ Flexible Configuration: Customizable chunk sizes, QR versions, and compression levels
⚡ Preset Modes: Fast, compact, and robust presets for different use cases
🏗️ Modular Architecture: Clean, maintainable codebase with separate concerns
🖥️ Cross-Platform: Works on Windows, macOS, and Linux
📊 Progress Analysis: Analyze QR codes before decoding for validation

🚀 Quick Start

Installation

Clone the repository:
```
git clone <repository-url>
cd qrare
```
Install dependencies:
```
pip install -r requirements.txt
```
Install ZBar library (required for QR code reading):
- Ubuntu/Debian: sudo apt-get install libzbar0
- macOS: brew install zbar
- Windows: Download from SourceForge

Basic Usage

Encode a file to QR codes:

python src/qrare_cli.py encode document.pdf -o qrcodes/

Decode QR codes back to file:

python src/qrare_cli.py decode qrcodes/ -o recovered/

Use preset configurations:

# Fast encoding (lower compression, larger chunks)
python src/qrare_cli.py encode data.bin --preset fast

# Compact encoding (maximum compression, minimal QR codes)  
python src/qrare_cli.py encode data.bin --preset compact

# Robust encoding (maximum error correction)
python src/qrare_cli.py encode data.bin --preset robust

📖 Detailed Usage

Command Line Interface

Encode Command

python src/qrare_cli.py encode FILE [OPTIONS]

Options:

-o, --output-dir DIR: Directory to save QR code images (default: ./qrcodes)
-c, --chunk-size BYTES: Size of binary chunks (default: 1024)
--qr-version 1-40: QR code version, higher = more capacity (default: 40)
-z, --compression-level 0-9: Compression level, 0=none, 9=best (default: 9)
--preset {fast,compact,robust}: Use preset configuration

Decode Command

python src/qrare_cli.py decode IMAGES... [OPTIONS]

Options:

-o, --output-dir DIR: Directory to save reconstructed file (default: ./output)
--analyze-only: Only analyze QR codes without reconstructing

Analyze Command

python src/qrare_cli.py analyze IMAGES...

Examine QR codes and report their status without performing reconstruction.

Examples

Encode with custom settings:

python src/qrare_cli.py encode large_file.bin \
  --chunk-size 2048 \
  --qr-version 30 \
  --compression-level 6 \
  -o qr_output/

Decode from directory:

python src/qrare_cli.py decode qr_output/ -o recovered/

Decode from specific files:

python src/qrare_cli.py decode qr_output/*.png -o recovered/

Analyze QR codes first:

python src/qrare_cli.py analyze qr_output/

🏗️ Architecture

The refactored codebase follows a clean, modular architecture:

src/qrare/
├── core/                   # Core functionality
│   ├── config.py          # Configuration management
│   ├── converter.py       # Main converter class
│   ├── encoder.py         # QR encoding logic
│   └── decoder.py         # QR decoding logic
├── cli/                   # Command-line interface
│   ├── main.py           # CLI entry point
│   └── commands.py       # Command implementations
└── utils/                 # Utility modules
    ├── exceptions.py      # Custom exception classes
    ├── file_ops.py       # File operations
    └── path_utils.py     # Path handling utilities

Key Components

🔧 Config System: Centralized configuration with validation and presets
⚡ Encoder/Decoder: Separate, focused classes for encoding and decoding
🛠️ File Operations: Robust file handling with comprehensive error management
🎯 Exception Handling: Specific exception types for better error reporting
📝 CLI Interface: Clean argument parsing and command execution

💻 Programmatic Usage

Basic Example

from qrare import BinaryQRConverter

# Create converter
converter = BinaryQRConverter(chunk_size=1024, compression_level=9)

# Encode file
qr_paths = converter.encode_file("document.pdf", "qr_output/")
print(f"Created {len(qr_paths)} QR codes")

# Decode back
reconstructed = converter.decode_qr_images(qr_paths, "recovered/")
print(f"Reconstructed: {reconstructed}")

Advanced Configuration

from qrare import BinaryQRConverter, QRConfig, CompressionLevel, ErrorCorrectionLevel

# Custom configuration
config = QRConfig(
    chunk_size=2048,
    qr_version=30,
    compression_level=CompressionLevel.BALANCED,
    error_correction=ErrorCorrectionLevel.HIGH,
    box_size=8,
    fill_color="darkblue"
)

converter = BinaryQRConverter(config=config)

Preset Configurations

# Optimized for speed
fast_converter = BinaryQRConverter.create_fast_converter()

# Optimized for minimal QR codes
compact_converter = BinaryQRConverter.create_compact_converter()

# Optimized for error recovery  
robust_converter = BinaryQRConverter.create_robust_converter()

Modular Usage

from qrare.core.encoder import QREncoder
from qrare.core.decoder import QRDecoder
from qrare.core.config import QRConfig

# Use encoder and decoder separately
encoder = QREncoder(QRConfig.create_compact_config())
decoder = QRDecoder()

# Encode
qr_paths = encoder.encode_file("data.bin", "qr_codes/")

# Analyze before decoding
analysis = decoder.analyze_qr_images(qr_paths)
print(f"Analysis: {analysis['readable_qrs']} readable QR codes")

# Decode
result = decoder.decode_qr_images(qr_paths, "output/")

📊 Configuration Options

Chunk Size

Small (512-1024 bytes): More QR codes, better error recovery
Medium (1024-2048 bytes): Balanced approach
Large (2048-4096 bytes): Fewer QR codes, less error recovery

QR Code Version

1-10: Small capacity, simple codes
11-25: Medium capacity, good balance
26-40: High capacity, complex codes

Compression Level

0: No compression (fastest)
1-3: Fast compression
4-6: Balanced compression
7-9: Best compression (slowest)

Error Correction

LOW (~7%): Maximum data capacity
MEDIUM (~15%): Balanced
QUARTILE (~25%): Good error recovery
HIGH (~30%): Maximum error recovery

🧪 Examples

The examples/ directory contains comprehensive usage examples:

basic_usage.py: Core functionality demonstration
advanced_usage.py: Advanced features and error handling

Run examples:

python examples/basic_usage.py
python examples/advanced_usage.py

🔍 How It Works

📁 File Reading: Binary file is read into memory
🗜️ Compression: Data is compressed using zlib to reduce size
✂️ Chunking: Compressed data is split into manageable chunks
📝 Metadata: Each chunk includes index, total count, filename, and hash
🔳 QR Generation: Each chunk becomes a QR code with embedded metadata
💾 Storage: QR codes are saved as PNG images with descriptive names

Reconstruction reverses the process:

🔍 QR Reading: QR codes are scanned and decoded
✅ Validation: Chunks are validated and sorted by index
🔗 Assembly: Chunks are reassembled into compressed data
📦 Decompression: Data is decompressed to original format
🔒 Verification: SHA-256 hash confirms file integrity

🎛️ Advanced Features

Estimation

# Get encoding estimation before processing
python src/qrare_cli.py encode large_file.bin --analyze-only

Batch Processing

files = ["doc1.pdf", "doc2.bin", "doc3.txt"]
for file_path in files:
    qr_paths = converter.encode_file(file_path, f"qr_{file_path.stem}/")
    print(f"{file_path}: {len(qr_paths)} QR codes")

Error Recovery

# Analyze QR codes for completeness
analysis = converter.analyze_qr_images(qr_paths)
for filename, info in analysis['chunk_info'].items():
    if not info['is_complete']:
        missing = set(range(info['total_chunks'])) - set(info['found_chunks'])
        print(f"File {filename} missing chunks: {sorted(missing)}")

🛠️ Troubleshooting

Common Issues

❌ "Missing ZBar library"

Install ZBar using the instructions in the Prerequisites section

❌ "QR code decoding fails"

Ensure QR codes are clear and undamaged
Try increasing error correction level
Check that all QR codes are present

❌ "File too large"

Increase chunk size: --chunk-size 4096
Use higher QR version: --qr-version 40
Consider splitting large files

❌ "Invalid QR version"

Use version between 1-40
Higher versions support more data but need better scanning

Performance Tips

For speed: Use --preset fast or lower compression levels
For size: Use --preset compact or higher compression levels
For reliability: Use --preset robust or higher error correction
For large files: Increase chunk size to reduce QR code count

🏷️ Version History

v0.2.0 (Current)

✨ Complete modular architecture refactoring
✨ New preset configurations (fast/compact/robust)
✨ Enhanced error handling and validation
✨ Separate encoder/decoder classes
✨ Comprehensive configuration system
✨ Analysis and estimation features
✨ Improved CLI with new commands
✨ Extensive documentation and examples
🔧 Backward compatibility maintained

v0.1.0 (Legacy)

🎯 Basic encoding/decoding functionality
🔧 Simple CLI interface
📦 Compression and integrity verification

🤝 Contributing

Contributions are welcome! The modular architecture makes it easy to:

Add new encoding/decoding formats
Implement additional compression algorithms
Create new preset configurations
Enhance error recovery mechanisms
Improve CLI functionality

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

ZBar: QR code reading functionality
qrcode: QR code generation
Pillow: Image processing
Original QRare: Foundation for this enhanced version

QRare v0.2.0 | Modular • Reliable • Extensible