🚗 Advanced OCR Prediction Pipeline

A comprehensive, production-ready OCR system for license plate recognition built with PyTorch. This system includes advanced model architectures, flexible preprocessing, and multiple deployment options.

📁 Project Structure

build_arc/
├── advanced_model.py      # Advanced CNN-Transformer model with residual blocks
├── image_preprocessor.py  # Image preprocessing and augmentation pipeline
├── ocr_predictor.py       # Main OCR prediction class
├── model_export.py        # Model export and deployment utilities
├── predict_plate.py       # Command-line prediction tool
├── config.py             # Configuration management system
├── build_arc.py          # Original training script
├── build_arc1.py         # Simplified training script
└── README.md             # This file

🚀 Quick Start

1. Basic Prediction

# Predict from a single image
python predict_plate.py image.jpg

# With custom model and beam search
python predict_plate.py image.jpg --model results/best.pth --method beam

# Batch prediction
python predict_plate.py image1.jpg image2.jpg image3.jpg --batch

2. Python API Usage

from ocr_predictor import PlateOCRPredictor

# Initialize predictor
predictor = PlateOCRPredictor("results/best.pth", "vocab.json")

# Predict from image file
result = predictor.predict_single("test_plate.jpg", method="beam")
print(f"License Plate: {result.text}")
print(f"Confidence: {result.confidence:.3f}")

# Batch prediction
results = predictor.predict_batch(["plate1.jpg", "plate2.jpg"])
for i, result in enumerate(results.results):
    print(f"Plate {i+1}: {result.text}")

3. Model Export

# Export model for deployment
python model_export.py --model results/best.pth --vocab vocab.json --output exported_model

# Create deployment package
python model_export.py --model results/best.pth --vocab vocab.json --package

🏗️ Architecture

Advanced Model Features

• Residual CNN Backbone: Enhanced feature extraction with residual connections
• Transformer Decoder: State-of-the-art sequence modeling
• Positional Encoding: Improved sequence understanding
• Multiple Decoding: Both greedy and beam search strategies
• Model Compilation: Optimized inference with torch.compile

Key Components

1. AdvancedFastPlateOCR: Main model with residual blocks and positional encoding
2. ImagePreprocessor: Comprehensive image preprocessing pipeline
3. PlateOCRPredictor: Production-ready prediction interface
4. ConfigManager: Flexible configuration management
5. ModelExporter: Deployment-ready model export

📊 Performance Features

Prediction Capabilities

• Single Image Prediction: Fast inference on individual images
• Batch Processing: Efficient processing of multiple images
• Quality Assessment: Automatic image quality evaluation
• Confidence Scoring: Reliability estimation for predictions
• Performance Benchmarking: Built-in speed and accuracy testing

Advanced Features

• Data Augmentation: Comprehensive augmentation pipeline
• Mixed Precision: AMP support for faster training
• Gradient Accumulation: Support for larger effective batch sizes
• Early Stopping: Prevent overfitting with patience-based stopping
• Model Compilation: PyTorch 2.0 compilation for faster inference

🔧 Configuration

Using Configuration Files

from config import ConfigManager, ConfigFactory

# Load from file
manager = ConfigManager("config.yaml")
config = manager.get_config()

# Create preset configurations
training_config = ConfigFactory.create_config("training")
inference_config = ConfigFactory.create_config("inference")

Configuration Options

• Model Architecture: Hidden dimensions, layers, attention heads
• Training Parameters: Learning rate, batch size, epochs
• Data Processing: Image size, augmentation, normalization
• Inference Settings: Decoding method, beam width, quality thresholds
• Export Options: Formats, optimization, packaging

📈 Usage Examples

1. Training with Advanced Features

from advanced_model import AdvancedFastPlateOCR
from config import get_training_config

# Load configuration
config = get_training_config()

# Create model
model = AdvancedFastPlateOCR(
    vocab_size=config.model.vocab_size,
    hidden=config.model.hidden_dim,
    num_layers=config.model.num_layers,
    use_pe=config.model.use_pe
)

# Train with advanced features
# (See build_arc.py for complete training implementation)

2. Custom Preprocessing

from image_preprocessor import ImagePreprocessor, AdvancedAugmentation

# Create preprocessor with augmentation
preprocessor = ImagePreprocessor(
    target_height=96,
    target_width=512,
    augment=True
)

# Process image
img_tensor = preprocessor.preprocess_image("image.jpg", training=True)

3. Model Export and Deployment

from model_export import ModelExporter

# Export model
exporter = ModelExporter("results/best.pth", "vocab.json", "exported_model")
exported_files = exporter.export_all()

# Files created:
# - model_traced.pt (TorchScript)
# - model.onnx (ONNX)
# - vocab.json (Vocabulary)
# - config.json (Configuration)

4. Quality Assessment

from image_preprocessor import ImageQualityAssessor

# Assess image quality
quality_metrics = ImageQualityAssessor.assess_quality(image)
print(f"Quality Score: {quality_metrics['quality_score']:.3f}")
print(f"Sharpness: {quality_metrics['sharpness']:.1f}")
print(f"Contrast: {quality_metrics['contrast']:.1f}")

🎯 Command Line Interface

Basic Usage

# Single image prediction
python predict_plate.py image.jpg

# Batch processing
python predict_plate.py *.jpg --batch

# With visualization
python predict_plate.py image.jpg --visualize

# Save results
python predict_plate.py image.jpg --output results.txt

Advanced Options

# Custom model and method
python predict_plate.py image.jpg --model custom.pth --method beam --beam-width 10

# Performance benchmark
python predict_plate.py image.jpg --benchmark --runs 20

# Quality check
python predict_plate.py image.jpg --quality-check --min-quality 0.5

# Verbose output
python predict_plate.py image.jpg --verbose

📦 Deployment

1. Export Model

# Export all formats
python model_export.py --model results/best.pth --vocab vocab.json --output exported_model

# Export specific format
python model_export.py --model results/best.pth --vocab vocab.json --format torchscript

# Create deployment package
python model_export.py --model results/best.pth --vocab vocab.json --package

2. Production Deployment

# Load exported model
import torch
model = torch.jit.load("exported_model/model_traced.pt")

# Or use ONNX
import onnxruntime as ort
session = ort.InferenceSession("exported_model/model.onnx")

🔍 Model Architecture Details

CNN Backbone

# Enhanced CNN with residual connections
self.cnn = nn.Sequential(
    nn.Conv2d(3, 64, 7, stride=2, padding=3),
    nn.BatchNorm2d(64),
    nn.ReLU(inplace=True),
    nn.MaxPool2d(3, stride=2, padding=1),
    
    # Residual blocks
    self._make_layer(64, 128, 2, stride=2),
    self._make_layer(128, 256, 2, stride=2),
    self._make_layer(256, hidden, 2, stride=2),
    
    nn.AdaptiveAvgPool2d((1, None))
)

Transformer Decoder

# Multi-head attention decoder
decoder_layer = nn.TransformerDecoderLayer(
    d_model=hidden, 
    nhead=nhead, 
    dim_feedforward=hidden * 4,
    dropout=0.1, 
    activation="relu", 
    batch_first=True
)
self.decoder = nn.TransformerDecoder(decoder_layer, num_layers=num_layers)

📊 Performance Metrics

Typical Performance

• Inference Time: ~50ms per image (GPU)
• Memory Usage: ~200MB (GPU)
• Accuracy: >95% on test set
• Model Size: ~50MB (compressed)

Benchmark Results

# Run benchmark
python predict_plate.py image.jpg --benchmark --runs 20

# Output:
# Average time: 0.045s
# Min time: 0.038s
# Max time: 0.052s
# FPS: 22.2

🛠️ Requirements

Core Dependencies

torch>=1.9.0
torchvision>=0.10.0
numpy>=1.21.0
opencv-python>=4.5.0
matplotlib>=3.3.0
tqdm>=4.62.0

Optional Dependencies

onnx>=1.12.0          # For ONNX export
onnxruntime>=1.12.0   # For ONNX inference
pyyaml>=6.0           # For YAML config files
wandb>=0.12.0         # For experiment tracking
tensorboard>=2.8.0    # For training visualization

🚀 Installation

# Clone repository
git clone <repository-url>
cd build_arc

# Install dependencies
pip install -r requirements.txt

# Or install individually
pip install torch torchvision numpy opencv-python matplotlib tqdm

📝 Configuration Files

Example Configuration (YAML)

model:
  vocab_size: 39
  hidden_dim: 256
  num_layers: 4
  nhead: 8
  use_pe: true
  dropout: 0.1

training:
  epochs: 20
  batch_size: 16
  learning_rate: 1e-4
  use_amp: true
  early_stopping: true
  patience: 10

data:
  target_height: 96
  target_width: 512
  use_augmentation: true
  augmentation_prob: 0.5

inference:
  default_method: "beam"
  beam_width: 5
  compile_model: true
  quality_check: true

🔧 Troubleshooting

Common Issues

1. CUDA Out of Memory

   # Reduce batch size
   config.training.batch_size = 8
   config.inference.batch_size = 1

2. Slow Inference

   # Enable model compilation
   config.inference.compile_model = True
   
   # Use greedy decoding
   result = predictor.predict_single(image, method="greedy")

3. Low Accuracy

   # Increase beam width
   result = predictor.predict_single(image, beam_width=10)
   
   # Check image quality
   predictor.predict_single(image, return_quality=True)

📚 API Reference

PlateOCRPredictor

class PlateOCRPredictor:
    def __init__(self, model_path: str, vocab_path: str, device: str = "auto")
    def predict_single(self, image, method: str = "beam", beam_width: int = 5) -> PredictionResult
    def predict_batch(self, images, method: str = "greedy") -> BatchPredictionResult
    def visualize_prediction(self, image, result, save_path: str = None)
    def get_performance_stats(self) -> Dict

AdvancedFastPlateOCR

class AdvancedFastPlateOCR:
    def __init__(self, vocab_size: int, hidden: int = 256, num_layers: int = 4)
    def forward(self, imgs: torch.Tensor, tgt_inp: torch.Tensor) -> torch.Tensor
    def greedy_decode(self, imgs: torch.Tensor, **kwargs) -> List[List[int]]
    def beam_decode(self, imgs: torch.Tensor, **kwargs) -> List[int]
    def get_model_info(self) -> Dict

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• PyTorch team for the excellent deep learning framework
• Transformer architecture from "Attention Is All You Need"
• Residual networks from "Deep Residual Learning for Image Recognition"
• OpenCV for computer vision utilities

---

🌟 Star this repository if you find it helpful!