| # 🧠 Project Context: ID Maker Studio (EL HELAL Pipeline) |
|
|
| This document provides a high-level overview of the project's intent, architecture, and critical technical state for developers and AI agents. |
|
|
| --- |
|
|
| ## 🎯 Project Intent |
| **ID Maker Studio** is a professional-grade image processing pipeline designed for **EL HELAL Studio**. Its primary goal is to automate the conversion of raw student portraits into high-resolution (300 DPI), print-ready ID sheets. |
|
|
| The system handles everything from blemish removal and color grading to complex Arabic typography and branding. |
|
|
| --- |
|
|
| ## 🏗 High-Level Architecture |
|
|
| The project is strictly modular, separating core business logic from user interfaces. |
|
|
| ### 1. The Brain (`/core`) |
| - **Pipeline Orchestration:** Sequentially runs 5 critical steps. |
| - **AI Logic:** |
| - **Crop:** OpenCV-based face detection (5:7 ratio). |
| - **Background Removal:** BiRefNet (RMBG-2.0) running on CPU (quantized). |
| - **Retouching:** MediaPipe Face Mesh + Frequency Separation (preserves 100% skin texture). |
| - **Color Steal:** Custom algorithm to learn and apply professional color curves. |
| - **Layout Engine:** Composite engine using Pillow. Handles complex Arabic script via manual shaping and reordering. |
|
|
| ### 2. The Interfaces |
| - **Web Interface (`/web`):** The primary production tool. Built with FastAPI and a localized Arabic (RTL) frontend. |
| - **3-Column Layout:** Queue (Right) — Preview (Center) — Options & Settings (Left). |
| - **Dark/Light Theme:** Toggleable via header button, persisted in localStorage. |
| - **Batch Processing Counter:** Shows `1/5`, `2/5`... overlay with dim background during batch processing. |
| - **Per-Image Delete:** Hover delete button on each queue item. |
| - **Settings API:** Real-time slider-based tuning of retouch sensitivity, skin smoothing, font sizes — saved to `config/settings.json`. |
| - **Keyboard Shortcuts:** Arrow navigation, Delete, Enter (save & next), Ctrl+S (process), Escape. |
| - **Before/After Toggle:** Quick comparison between original and processed result. |
| - **Zoom Modal:** Scroll-wheel zoom for detailed inspection. |
| - **Mobile Drawer:** Responsive drawer for queue on mobile devices. |
| - **Desktop GUI (`/gui`):** Legacy Tkinter application for offline machine usage. |
|
|
| ### 3. Data & Config |
| - **`/storage`:** Managed directory for uploads, processing, and results. |
| - **`/config`:** Centralized `settings.json` for real-time layout tuning (DPI, margins, font sizes). |
| - **`/assets`:** Branding marks and font files. |
|
|
| --- |
|
|
| ## 🚀 Deployment & Environment |
|
|
| - **Infrastructure:** Optimized for **Docker** and **Hugging Face Spaces**. |
| - **Hardware Context:** Targeted for **2 CPUs / 16GB RAM**. |
| - RAM allows for large image buffers. |
| - CPU is the bottleneck; inference is sequential and quantized. |
| - **Binary Management:** Uses a hybrid approach. Smaller assets in Git; critical fonts are **automatically downloaded from GitHub** during Docker build to bypass Git LFS issues. |
|
|
| --- |
|
|
| ## ⚠️ Critical Technical "Gotchas" |
|
|
| - **Arabic Rendering:** In the container environment (standard LTR), Arabic is rendered by: |
| 1. Reshaping characters (connecting letters). |
| 2. **Manually reversing** the string characters to ensure correct visual flow without requiring `libraqm`. |
| - **MediaPipe Stability:** Explicitly imports submodules and includes safety checks to skip retouching if binary dependencies fail to initialize. |
| - **Transformers Monkeypatch:** Contains deep patches in `process_images.py` to handle `transformers 4.50+` tied-weight and meta-tensor bugs on CPU. |
| - **Dynamic Config:** `layout_engine.py` reloads `settings.json` on every request to allow "live" tuning of the output. |
|
|
| --- |
|
|
| ## 📂 Quick File Map |
| - `web/server.py`: FastAPI entry point. Includes Settings API (`GET/POST /settings`). |
| - `web/web_storage/index.html`: 3-column RTL frontend (Queue | Preview | Options). |
| - `core/layout_engine.py`: Final sheet composition logic. |
| - `core/retouch.py`: Advanced skin processing. |
| - `config/settings.json`: Live-reloadable settings (retouch sensitivity, font sizes, etc.). |
| - `Dockerfile`: Production environment definition. |
| - `tools/problems.md`: Historical log of technical hurdles and fixes. |
|
|
| --- |
|
|
| *Last Updated: February 2026 — Web UI v2 (3-Column Layout, Batch Counter, Theme Toggle)* |
|
|
