File size: 7,494 Bytes
e64ee47 b6dd390 e64ee47 b6dd390 e64ee47 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | # 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.
|