How smart-ouassine/moroccoai-data-challenge works
Project Type and Purpose
• This repository implements an end-to-end Automatic Number Plate Recognition (ANPR) system for Moroccan vehicles.
• It consists of two main deliverables:
• A backend REST API (FastAPI) that hosts two Detectron2-based object-detection models: one to locate license plates in images, and another to recognize (OCR) the individual characters on those plates.
• A frontend demo (Streamlit) that allows users to upload images or streams and view recognized plate strings.
File Structure
• Top-level artifacts:
• docker-compose.yml — orchestrates two containerized services (fastapi, streamlit)
• fastapi/ — source code, model-loading logic, endpoints, model weight directories
• streamlit/ — interactive UI code and its Dockerfile
• weights/ — model artifacts for local training or inference
• docs/ — Jupyter notebooks and presentation slides (offline training/demo materials)
• Architectural clues:
• Two distinct Dockerfiles → two services (micro-services)
• fastapi/main.py defines HTTP endpoints: /plate_detector, /plate_ocr
• streamlit/streamlit.py interacts with those endpoints over HTTP
• model artifacts (Detectron2 Faster R-CNN) kept alongside code for versioning
README for Additional Insights
• The README confirms the two-stage detection approach:
a. Detect and crop the license plate region.
b. Crop passed to a second model for character detection.
• Transfer learning via pretrained COCO Faster R-CNN backbones
Main Components & Their Interactions
a. Frontend (Streamlit UI service)
• Runs as its own Docker container
• Presents an interface for image upload or camera stream
• Makes HTTPS/HTTP calls to the FastAPI backend
b. API Gateway / Backend (FastAPI service)
• Hosts two endpoints: plate detection & OCR
• Loads the corresponding Detectron2 model weights at startup
• Receives images, runs inference, applies post-processing, returns JSON responses
c. Model Storage & Weights
• weights/ or fastapi/weights/ folders store .pth, checkpoint, metrics
• Mounted into containers via Docker volumes
d. Data Flow
1. User uploads image via Streamlit
2. Streamlit POSTs raw image to FastAPI’s /plate_detector
4. Streamlit POSTs cropped plate to /plate_ocr
5. API returns ordered character string
6. Streamlit displays final plate string
e. (Optional) Training & Experimentation Notebooks
• docs/*.ipynb used offline in Colab or local for model improvements
Architectural Patterns & Design Principles
• Micro-service separation: UI vs. API vs. data (weights)
• Containerization for reproducibility (Docker + docker-compose)
• Two-stage pipeline pattern (pipeline of inference stages)
• Transfer learning via Detectron2 (reusable pretrained modules)
• Stateless services: each inference request is independent