| # Resolved Technical Issues & Deployment Guide | |
| This document tracks critical problems encountered during development and deployment (especially for Docker and Hugging Face Spaces) and their corresponding solutions. | |
| ## 1. Font Rendering & Layout Consistency | |
| ### Problem: "Boxes" instead of Arabic Text | |
| - **Symptom**: Arabic names appeared as empty boxes (tofu) or incorrectly rendered characters. | |
| - **Cause**: The system was attempting to load Windows-specific font paths (e.g., `C:/Windows/Fonts/...`) which do not exist in Linux/Docker environments. | |
| - **Solution**: | |
| - Implemented platform-agnostic font discovery in `core/layout_engine.py`. | |
| - Added automatic detection of bundled fonts in the `assets/` directory. | |
| - Prioritized `arialbd.ttf` for Arabic support over legacy fonts. | |
| ### Problem: Settings Changes Not Reflecting | |
| - **Symptom**: Changing `id_font_size` in `settings.json` had no effect until the app was restarted. | |
| - **Cause**: Settings were loaded once at module import time and cached as global constants. | |
| - **Solution**: Modified `generate_layout` to call `load_settings()` at the start of every execution, ensuring real-time updates from the JSON file. | |
| --- | |
| ## 2. Hugging Face Spaces (Docker) Deployment | |
| ### Problem: Obsolete `libgl1-mesa-glx` | |
| - **Symptom**: Docker build failed with `E: Package 'libgl1-mesa-glx' has no installation candidate`. | |
| - **Cause**: The base Debian image (Trixie/Sid) used by HF has obsoleted this package. | |
| - **Solution**: Updated `Dockerfile` to use `libgl1` which provides the necessary OpenGL libraries for OpenCV. | |
| ### Problem: Transformers 4.50+ Compatibility (BiRefNet/RMBG-2.0) | |
| - **Symptom**: `AttributeError: 'BiRefNet' object has no attribute 'all_tied_weights_keys'` or `'NoneType' object has no attribute 'keys'`. | |
| - **Cause**: The custom model code for BiRefNet/RMBG-2.0 is incompatible with internal changes in recent `transformers` versions regarding tied weight tracking. | |
| - **Solution**: | |
| - Applied a robust monkeypatch in `core/process_images.py` to the `PreTrainedModel` class. | |
| - Forced `all_tied_weights_keys` to always return an empty dictionary `{}` instead of `None`. | |
| - Pinned `transformers==4.48.2` in `requirements.txt` for a stable environment. | |
| ### Problem: Meta-Tensor Initialization Bug | |
| - **Symptom**: Model failed to load on CPU due to "meta tensors" not being correctly materialized. | |
| - **Cause**: A bug in how `torch.linspace` interacts with transformers' `low_cpu_mem_usage` flag for custom models. | |
| - **Solution**: Monkeypatched `torch.linspace` in `core/process_images.py` to force materialization on CPU when a meta-tensor is detected. | |
| --- | |
| ## 3. Git & LFS Management | |
| ### Problem: Binary File Rejection | |
| - **Symptom**: `remote: Your push was rejected because it contains binary files.` | |
| - **Cause**: Pushing large `.jpg`, `.png`, or `.cube` files directly to Hugging Face without Git LFS, or having them in the Git history from previous commits. | |
| - **Solution**: | |
| - Configured `.gitattributes` to track `*.png`, `*.TTF`, `*.npz`, and `*.cube` with LFS. | |
| - Used `git filter-branch` to purge large binaries (`raw/`, `white/`, and root `.jpg` files) from the entire Git history to reduce repo size and satisfy HF hooks. | |
| --- | |
| ## 5. Image Processing Pipeline & Dependencies | |
| ### Problem: `KeyError: 'setting text direction... not supported without libraqm'` | |
| - **Symptom**: Application crashes on Windows when attempting to render Arabic text in the layout. | |
| - **Cause**: Pillow's `direction` and `features` parameters require the `libraqm` library, which is difficult to install on Windows. | |
| - **Solution**: | |
| - Added a safety check using `PIL.features.check("raqm")`. | |
| - Implemented a fallback that relies on `arabic-reshaper` and `python-bidi` for manual shaping/reordering when `raqm` is missing. | |
| ### Problem: Background Removal failing when Retouching is enabled | |
| - **Symptom**: Background removal appeared "ignored" or reverted to original background after processing. | |
| - **Cause**: The `retouch_image_pil` function in `core/retouch.py` was converting the image to RGB for OpenCV processing, stripping the Alpha channel (transparency) created by the BG removal step. | |
| - **Solution**: | |
| - Updated `retouch_image_pil` to detect and save the Alpha channel before processing. | |
| - Modified the logic to restore the Alpha channel to the final retouched PIL image before returning it to the pipeline. | |
| ### Problem: BiRefNet Model Inference Error | |
| - **Symptom**: `TypeError` or indexing errors during background removal inference. | |
| - **Cause**: Inconsistent model output formats (list of tensors vs. a single tensor) depending on the environment or `transformers` version. | |
| - **Solution**: Updated `remove_background` in `core/process_images.py` to check if output is a list/tuple and handle both cases robustly. | |
| ### Problem: `AttributeError: module 'mediapipe' has no attribute 'solutions'` | |
| - **Symptom**: Skin retouching fails in the Docker container with this error. | |
| - **Cause**: Inconsistent behavior of the `mediapipe` package initialization in some Linux environments. | |
| - **Solution**: | |
| - Explicitly imported submodules like `mediapipe.solutions.face_mesh` at the top of the file. | |
| - Switched from `python:3.10-slim` to the full `python:3.10` image to ensure a complete build environment. | |
| - Added `libprotobuf-dev` and `protobuf-compiler` to the `Dockerfile`. | |
| ### Problem: Arabic/English Text appearing as "Boxes" (Tofu) | |
| - **Symptom**: All text on the print layout appears as empty squares in the Hugging Face Space. | |
| - **Cause**: The container lacked fonts with proper character support, and binary `.ttf` files were often corrupted as 130-byte Git LFS pointers. | |
| - **Solution**: | |
| - **Automated Downloads**: Updated `Dockerfile` to use `wget` to pull real binary fonts directly from GitHub during the build. | |
| - **Deep Search**: Implemented a recursive font discovery system in `core/layout_engine.py` that scans `/usr/share/fonts`. | |
| - **System Fallbacks**: Installed `fonts-noto-extra` and `fonts-dejavu-core` as guaranteed system-level backups. | |
| ### Problem: Arabic Text appearing "Connected but Reversed" | |
| - **Symptom**: Arabic letters connect correctly but flow from Left-to-Right (e.g., "م ح م د" instead of "محمد"). | |
| - **Cause**: Inconsistent behavior between local Windows (missing `libraqm`) and Docker Linux (has `libraqm`). Using `get_display` in an environment that already supports complex scripts causes a "double-reversal". | |
| - **Solution**: | |
| - **Intelligent Detection**: Updated `_reshape_arabic` in `core/layout_engine.py` to check for Raqm support via `PIL.features.check("raqm")`. | |
| - **Conditional Reordering**: The system now only applies `python-bidi` reordering if Raqm is **absent**. This ensures perfect rendering in both environments without manual code changes. | |
| ### Problem: Manual Cropping ignored or shifted | |
| - **Symptom**: After manually adjusting the crop in the web interface, the result still looked like the AI auto-crop or was completely wrong. | |
| - **Cause**: The backend was using `cv2.imdecode` which ignores EXIF orientation tags. Since the frontend cropper works on correctly oriented thumbnails, the coordinates sent to the backend didn't match the raw image orientation on disk. | |
| - **Solution**: Updated `core/crop.py` to use a `_load_image_exif_safe` helper that uses PIL to transpose the image before converting it to OpenCV format. This ensures coordinates from the web UI always match the backend image state. | |