# 📜 ID Maker Studio: Technical Master Documentation

This document serves as the comprehensive technical map for the **EL HELAL Studio Photo Pipeline**.

---

## 🏗 High-Level Architecture

The system is a modular Python-based suite designed to automate the conversion of raw student portraits into professional, print-ready ID sheets. It bridges the gap between complex AI models and a production studio environment.

### 🧩 Component Breakdown
- **`/core` (The Brain):** Pure logic and AI processing. It is UI-agnostic and handles image math, landmark detection, and layout composition.
- **`/web` (The Primary Interface):** A modern FastAPI backend coupled with a localized Arabic (RTL) frontend for batch processing.
- **`/storage` (The Data):** Centralized storage for uploads, processed images, and final results.
- **`/config` (The Settings):** Stores `settings.json` for global configuration.
- **`/tools` (The Utilities):** Dev scripts, troubleshooting guides, and verification tools.
- **`/assets` (The Identity):** Centralized storage for branding assets (logo), typography (Arabic fonts), and color grading LUTs.
- **`/gui` (Legacy):** A Tkinter desktop wrapper for offline/workstation usage.

---

## 🚀 The 5-Step AI Pipeline

Every photo processed by the studio follows a strictly sequenced pipeline:

### 1. Auto-Crop & Face Detection (`crop.py`)
- **Technology:** OpenCV Haar Cascades.
- **Logic:** Detects the largest face, centers it, and calculates a 5:7 (4x6cm) aspect ratio crop.
- **Fallback:** Centers the crop if no face is detected to ensure the pipeline never breaks.

### 2. AI Background Removal (`process_images.py`)
- **Model:** **BiRefNet (RMBG-2.0)**.
- **Optimization:** Automatically detects and utilizes CUDA/GPU. In CPU environments (like HF Spaces), it uses dynamic quantization for speed.
- **Resilience:** Includes critical monkeypatches for `transformers 4.50+` to handle tied weights and meta-tensor materialization bugs.

### 3. Color Grading Style Transfer (`color_steal.py`)
- **Mechanism:** Analyzes "Before" and "After" pairs to learn R, G, and B curves.
- **Smoothing:** Uses **Savitzky-Golay filters** to prevent color banding.
- **Application:** Applies learned styles via vectorized NumPy operations for near-instant processing.

### 4. Surgical Retouching (`retouch.py`)
- **Landmarking:** Uses **MediaPipe Face Mesh** (468 points) to generate a precise skin mask, excluding eyes, lips, and hair.
- **Frequency Separation:** Splits the image into **High Frequency** (texture/pores) and **Low Frequency** (tone/color).
- **Blemish Removal:** Detects anomalies on the High-Freq layer and inpaints them using surrounding texture. 
- **Result:** Pores and skin texture are 100% preserved; only defects are removed.

### 5. Layout Composition (`layout_engine.py`)
- **Rendering:** Composes a 300 DPI canvas for printing.
- **Localization:** Uses `arabic_reshaper` and `python-bidi` for correct Arabic script rendering.
- **Dynamic Assets:** Overlays IDs with specific offsets and studio branding (logos).

---

## ⚙️ Configuration & Real-Time Tuning

The system is controlled by `core/settings.json`.
- **Hot Reloading:** The layout engine reloads this file on **every request**. You can adjust `id_font_size`, `grid_gap`, or `retouch_sensitivity` and see the changes in the next processed photo without restarting the server.

---

## 🐳 Deployment & Cloud Readiness

The project is optimized for high-availability environments.

### Docker Environment
- **Base:** `python:3.10-slim`.
- **System Deps:** Requires `libgl1` (OpenCV), `libraqm0` (Font rendering), and `libharfbuzz0b` (Arabic shaping).

### Hugging Face Spaces
- **Transformers Fix:** Patches `PretrainedConfig` to allow custom model loading without attribute errors.
- **LFS Support:** Binary files (`.ttf`, `.cube`, `.png`) are managed via Git LFS to ensure integrity.

---

## 🛠 Troubleshooting (Common Pitfalls)

| Issue | Root Cause | Solution |
|-------|------------|----------|
| **"Tofu" Boxes in Text** | Missing or corrupted fonts. | Ensure `assets/arialbd.ttf` is not a Git LFS pointer (size > 300KB). |
| **Meta-Tensor Error** | Transformers 4.50+ CPU bug. | Handled by `torch.linspace` monkeypatch in `process_images.py`. |
| **Slow Processing** | CPU bottleneck. | Ensure `torch` is using multiple threads or enable CUDA. |

---

*Last Updated: February 2026 — EL HELAL Studio Engineering*