tools/problems.md

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.