| # 📜 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* |
|
|
