# 📜 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).
- **Customization:** Supports dynamic frame color selection (passed via API) for the large side panel.

---

## ⚙️ 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.

### 💾 Backup & Restoration
The system supports full state backup via the web interface.
- **Export:** Creates a ZIP file containing:
    - Global `settings.json`.
    - All custom assets (frames, logos) in `assets/`.
    - Client-side preferences (theme, saved colors).
- **Import:** Restores the configuration and assets from a ZIP file and refreshes the client state.

---

## 🐍 Environment & Dependency Management

The project requires a carefully managed Python environment to avoid common AI library conflicts.

### Known Conflicts & Fixes
- **TensorFlow vs. Transformers:** Standard installations of `tensorflow` (especially nightly versions) conflict with `transformers` and `numpy 2.x`, causing `AttributeError: module 'numpy' has no attribute 'dtypes'` and Protobuf descriptor errors.
- **Resolution:** **Uninstall TensorFlow.** The pipeline is 100% PyTorch-based. Removing TensorFlow resolves these import crashes immediately.
- **Pinned Versions:** 
  - `numpy < 2.0.0`: Required for compatibility with `basicsr` and older `torchvision` utilities.
  - `protobuf <= 3.20.3`: Prevents "Double Registration" errors in multi-model environments.

### Environment Setup (Conda)
```bash
conda create -n idmaker python=3.10
conda activate idmaker
pip install -r requirements.txt
# Ensure no conflicting packages remain
pip uninstall tensorflow tb-nightly tensorboard
```

---

## ☁️ CodeFormer Restoration API

The `id-maker` system integrates with an external **CodeFormer** service for high-fidelity face restoration. This is handled via a dedicated REST API.

### Endpoint: `/api/restore` (POST)
The API accepts an image and returns a JSON response containing a URL to the restored result.

**Request Parameters (`multipart/form-data`):**
- `image`: The source image file (JPG/PNG).
- `fidelity`: (Float, 0.0 - 1.0) Controls the balance between restoration quality (1.0) and fidelity to the original (0.0).
- `upscale`: (Integer, 1-4) Final output magnification.
- `background_enhance`: (Boolean string, "true"/"false") Whether to enhance the non-face areas using Real-ESRGAN.
- `face_upsample`: (Boolean string, "true"/"false") Whether to apply dedicated face upsampling.

**Success Response (JSON):**
```json
{
    "status": "success",
    "results": [
        { "image_url": "https://service-url/static/results/result_uuid.png" }
    ],
    "message": "Restoration complete"
}
```

### Configuration
The target API URL is controlled in `id-maker/config/settings.json` under `api.codeformer_url` or via the `CODEFORMER_API_URL` environment variable.

---

## 🐳 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). |
| **NumPy AttributeError** | Conflict between NumPy 2.x and TensorFlow/Transformers. | Uninstall `tensorflow` and ensure `numpy < 2.0.0` is installed. |
| **[Errno 10048] Socket Bind** | Port 7860 is already in use by another server process. | Close the previous server instance or set a new `PORT` environment variable. |
| **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*