Fri, 03 Jul 2026 00:16 - Add Qwen face hair detailer

README.md

@@ -7,10 +7,10 @@ sdk_version: 5.49.1
 app_file: app.py
 pinned: false
 license: apache-2.0
-version: 1.0.1
+version: 1.0.2
 short_description: Powerful image editing - supports one or two input images.
 ---
 
-Pro Realism Edit Studio is a powerful image editor powered by [Qwen-Image-Edit-2511](https://huggingface.co/Qwen/Qwen-Image-Edit-2511) with [Phr00t's Rapid-AIO v23](https://huggingface.co/Phr00t/Qwen-Image-Edit-Rapid-AIO) accelerated transformer for 4-step inference. Upload one or two input images, write a prompt, get high-quality results. The enhancement stage uses Nomos-family tiled upscaling, Qwen-aware masked artifact repair, micro-detail sharpening, and final photographic grain.
+Pro Realism Edit Studio is a powerful image editor powered by [Qwen-Image-Edit-2511](https://huggingface.co/Qwen/Qwen-Image-Edit-2511) with [Phr00t's Rapid-AIO v23](https://huggingface.co/Phr00t/Qwen-Image-Edit-Rapid-AIO) accelerated transformer for 4-step inference. Upload one or two input images, write a prompt, get high-quality results. The enhancement stage uses Nomos-family tiled upscaling, Qwen-aware masked artifact repair, tiled face/hair detail regions, micro-detail sharpening, and final photographic grain.
 
 Video generation is disabled unless an owned Gradio video Space is configured with `VIDEO_SPACE_ID`.

app.py

@@ -9,7 +9,7 @@ Advanced image editing and enhancement studio powered by:
 - Qwen-aware masked cleanup and final photographic detail
 
 Author: Enhanced with Hugging Face CLI and image generation expertise
-Version: 1.0.1
+Version: 1.0.2
 """
 
 import gradio as gr
@@ -25,7 +25,7 @@ from pathlib import Path
 # Advanced imports
 from accelerate import init_empty_weights
 from collections import OrderedDict
-from PIL import Image, ImageEnhance, ImageFilter, ImageOps
+from PIL import Image, ImageChops, ImageEnhance, ImageFilter, ImageOps
 from diffusers.models import QwenImageTransformer2DModel as DiffusersQwenImageTransformer2DModel
 from diffusers.models.model_loading_utils import load_model_dict_into_meta
 from huggingface_hub import hf_hub_download, HfApi, login, whoami
@@ -42,7 +42,7 @@ from gradio_client import Client, handle_file
 
 # Base model configuration
 BASE_MODEL_ID = "Qwen/Qwen-Image-Edit-2511"
-APP_VERSION = "1.0.1"
+APP_VERSION = "1.0.2"
 PHR00T_REPO_ID = os.environ.get("PHR00T_REPO_ID", "Phr00t/Qwen-Image-Edit-Rapid-AIO").strip()
 RAPID_TRANSFORMER_FILENAME = os.environ.get(
     "RAPID_TRANSFORMER_FILENAME",
@@ -60,6 +60,9 @@ ENHANCE_MAX_INPUT_EDGE = int(os.environ.get("ENHANCE_MAX_INPUT_EDGE", "2048"))
 ENHANCE_QWEN_DOWNSCALE_TRIGGER_EDGE = int(os.environ.get("ENHANCE_QWEN_DOWNSCALE_TRIGGER_EDGE", "1536"))
 ENHANCE_QWEN_DOWNSCALE_FACTOR = float(os.environ.get("ENHANCE_QWEN_DOWNSCALE_FACTOR", "0.75"))
 ENHANCE_GRAIN_STRENGTH = float(os.environ.get("ENHANCE_GRAIN_STRENGTH", "0.010"))
+ENHANCE_DETAILER_ENABLED = os.environ.get("ENHANCE_DETAILER_ENABLED", "true").lower() == "true"
+ENHANCE_DETAILER_MAX_REGIONS = int(os.environ.get("ENHANCE_DETAILER_MAX_REGIONS", "8"))
+ENHANCE_DETAILER_MIN_REGION_AREA = float(os.environ.get("ENHANCE_DETAILER_MIN_REGION_AREA", "0.003"))
 
 # Advanced Detail Enhancement Configuration
 DETAIL_ENHANCEMENT_ENABLED = os.environ.get("DETAIL_ENHANCEMENT_ENABLED", "true").lower() == "true"
@@ -606,6 +609,123 @@ def qwen_defect_mask(image):
     mask_image = mask_image.filter(ImageFilter.MaxFilter(size=3))
     return mask_image.filter(ImageFilter.GaussianBlur(radius=1.1))
 
+def qwen_hair_mask(image):
+    base = image.convert("RGB")
+    rgb = np.asarray(base).astype(np.float32)
+    gray_image = base.convert("L")
+    gray = np.asarray(gray_image).astype(np.float32)
+    skin = np.asarray(qwen_skin_mask(base)).astype(np.float32) / 255.0
+    edges = np.asarray(gray_image.filter(ImageFilter.FIND_EDGES).filter(ImageFilter.GaussianBlur(radius=0.7))).astype(np.float32)
+    chroma = rgb.max(axis=2) - rgb.min(axis=2)
+
+    dark_strands = (gray < 122) & (edges > 8) & (skin < 0.45)
+    light_strands = (gray < 235) & (edges > 18) & (chroma > 8) & (skin < 0.28)
+    mask = (dark_strands | light_strands).astype(np.uint8) * 255
+
+    try:
+        import cv2
+        kernel = np.ones((3, 3), np.uint8)
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
+        mask = cv2.GaussianBlur(mask, (0, 0), 1.0)
+    except ImportError:
+        mask_image = Image.fromarray(mask, mode="L")
+        mask_image = mask_image.filter(ImageFilter.MaxFilter(size=3))
+        mask_image = mask_image.filter(ImageFilter.GaussianBlur(radius=1.0))
+        mask = np.asarray(mask_image)
+
+    return Image.fromarray(mask.astype(np.uint8), mode="L")
+
+def qwen_face_feature_mask(image):
+    base = image.convert("RGB")
+    skin = np.asarray(qwen_skin_mask(base)).astype(np.float32) / 255.0
+    gray_image = base.convert("L")
+    edges = np.asarray(gray_image.filter(ImageFilter.FIND_EDGES)).astype(np.float32)
+    features = ((skin > 0.08) & (edges > 10)).astype(np.uint8) * 255
+    defects = np.asarray(qwen_defect_mask(base)).astype(np.uint8)
+    mask = np.maximum(features, defects)
+    mask_image = Image.fromarray(mask, mode="L")
+    mask_image = mask_image.filter(ImageFilter.MaxFilter(size=5))
+    return mask_image.filter(ImageFilter.GaussianBlur(radius=1.6))
+
+def _mask_to_boxes(mask_image, max_regions=ENHANCE_DETAILER_MAX_REGIONS):
+    mask = np.asarray(mask_image.convert("L"))
+    binary = (mask > 24).astype(np.uint8)
+    min_area = max(32, int(binary.shape[0] * binary.shape[1] * ENHANCE_DETAILER_MIN_REGION_AREA))
+    boxes = []
+
+    try:
+        import cv2
+        count, labels, stats, _ = cv2.connectedComponentsWithStats(binary, connectivity=8)
+        for label in range(1, count):
+            x, y, width, height, area = stats[label]
+            if area >= min_area:
+                boxes.append((int(x), int(y), int(x + width), int(y + height), int(area)))
+    except ImportError:
+        bbox = mask_image.point(lambda value: 255 if value > 24 else 0).getbbox()
+        if bbox:
+            x0, y0, x1, y1 = bbox
+            boxes.append((x0, y0, x1, y1, (x1 - x0) * (y1 - y0)))
+
+    boxes.sort(key=lambda item: item[4], reverse=True)
+    return [box[:4] for box in boxes[:max_regions]]
+
+def _expand_box(box, image_size, pad_ratio=0.18, min_size=192):
+    x0, y0, x1, y1 = box
+    width = x1 - x0
+    height = y1 - y0
+    pad = int(max(width, height) * pad_ratio)
+    if width < min_size:
+        extra = (min_size - width) // 2
+        x0 -= extra
+        x1 += extra
+    if height < min_size:
+        extra = (min_size - height) // 2
+        y0 -= extra
+        y1 += extra
+    return (
+        max(0, x0 - pad),
+        max(0, y0 - pad),
+        min(image_size[0], x1 + pad),
+        min(image_size[1], y1 + pad),
+    )
+
+def _local_detail_crop(crop, mask_crop, strength=0.35, hair=False):
+    base = crop.convert("RGB")
+    mask = mask_crop.convert("L").filter(ImageFilter.GaussianBlur(radius=1.8))
+    strength = max(0.0, min(1.0, strength))
+
+    if hair:
+        detailed = base.filter(ImageFilter.UnsharpMask(radius=0.55, percent=int(130 + 120 * strength), threshold=2))
+        detailed = ImageEnhance.Contrast(detailed).enhance(1.0 + 0.08 * strength)
+        edge_mask = base.convert("L").filter(ImageFilter.FIND_EDGES).filter(ImageFilter.GaussianBlur(radius=0.7))
+        mask = ImageChops.multiply(mask, edge_mask.point(lambda value: min(255, int(value * 2.2))))
+    else:
+        repaired = masked_texture_repair(base, strength=0.35 + 0.30 * strength)
+        detailed = repaired.filter(ImageFilter.UnsharpMask(radius=0.75, percent=int(80 + 90 * strength), threshold=3))
+        detailed = ImageEnhance.Contrast(detailed).enhance(1.0 + 0.045 * strength)
+
+    mask = mask.point(lambda value: int(value * strength))
+    return Image.composite(detailed, base, mask)
+
+def qwen_tiled_detailer_pass(image, strength=0.35, include_hair=True):
+    if not ENHANCE_DETAILER_ENABLED or strength <= 0:
+        return image.convert("RGB")
+
+    result = image.convert("RGB")
+    region_specs = [(qwen_face_feature_mask(result), strength, False, 0.22)]
+    if include_hair:
+        region_specs.append((qwen_hair_mask(result), strength * 0.85, True, 0.12))
+
+    for mask, region_strength, hair, pad_ratio in region_specs:
+        for box in _mask_to_boxes(mask):
+            expanded = _expand_box(box, result.size, pad_ratio=pad_ratio, min_size=192)
+            crop = result.crop(expanded)
+            mask_crop = mask.crop(expanded)
+            detailed = _local_detail_crop(crop, mask_crop, strength=region_strength, hair=hair)
+            result.paste(detailed, expanded, mask_crop.filter(ImageFilter.GaussianBlur(radius=2.5)))
+
+    return result
+
 def masked_texture_repair(image, strength=0.55):
     base = image.convert("RGB")
     mask = qwen_defect_mask(base)
@@ -640,8 +760,8 @@ def apply_enhancement(image, enhance_mode, seed=0, progress=None):
     enhanced = image.convert("RGB")
     total_steps = {
         ENHANCE_MODE_UPSCALE: 2,
-        ENHANCE_MODE_CLEAN: 3,
-        ENHANCE_MODE_MAX_DETAIL: 5,
+        ENHANCE_MODE_CLEAN: 4,
+        ENHANCE_MODE_MAX_DETAIL: 7,
     }[mode]
     step = 0
 
@@ -657,6 +777,15 @@ def apply_enhancement(image, enhance_mode, seed=0, progress=None):
         enhanced = masked_texture_repair(enhanced, strength=0.55 if mode == ENHANCE_MODE_CLEAN else 0.68)
         enhanced = qwen_micro_detail(enhanced, amount=0.18)
 
+        if progress:
+            step += 1
+            progress(0.85 * step / total_steps, desc="Detailing face regions...")
+        enhanced = qwen_tiled_detailer_pass(
+            enhanced,
+            strength=0.32 if mode == ENHANCE_MODE_CLEAN else 0.48,
+            include_hair=(mode == ENHANCE_MODE_MAX_DETAIL),
+        )
+
     if mode == ENHANCE_MODE_MAX_DETAIL:
         if progress:
             step += 1
@@ -669,6 +798,10 @@ def apply_enhancement(image, enhance_mode, seed=0, progress=None):
     enhanced = tile_upscale(enhanced)
 
     if mode == ENHANCE_MODE_MAX_DETAIL:
+        if progress:
+            step += 1
+            progress(0.94, desc="Detailing final face and hair tiles...")
+        enhanced = qwen_tiled_detailer_pass(enhanced, strength=0.30, include_hair=True)
         if progress:
             step += 1
             progress(0.98, desc="Adding final photographic grain...")
@@ -855,7 +988,7 @@ with gr.Blocks(css=css) as demo:
         
         Pro Tips:
         - Use Clean for portraits with smudged or pitted skin
-        - Use Max Detail for texture, grain, and sharper final output
+        - Use Max Detail for hair, eyes, lashes, texture, grain, and sharper final output
         """)
         
         with gr.Row():
@@ -882,8 +1015,8 @@ with gr.Blocks(css=css) as demo:
                 Enhancement Options:
                 - Off: No post-processing
                 - Upscale: Qwen precondition + 4x Nomos tiled upscale
-                - Clean: Masked Qwen artifact repair + upscaling
-                - Max Detail: Masked repair + micro detail + upscaling + final grain
+                - Clean: Masked Qwen artifact repair + tiled face detail + upscaling
+                - Max Detail: Tiled face/hair detail + micro detail + upscaling + final grain
                 """, visible=False)
                 
                 run_button = gr.Button("Generate!", variant="primary")

requirements.txt

@@ -15,15 +15,12 @@ Kernels==0.11.0
 Peft
 Torchao==0.11.0
 
-# Image processing and upscaling
+# Image processing and upscaling
 spandrel
 spandrel_extra_arches
-Pillow
-Numpy
-
-# OpenCV for faster mask cleanup (optional)
-# Install with: pip install opencv-python
-# opencv-python>=4.5.0
+opencv-python-headless
+Pillow
+Numpy
 
 # SciPy for legacy image processing helpers (optional)
 # Install with: pip install scipy
@@ -41,6 +38,6 @@ Gradio_client
 # Performance monitoring (optional)
 # Install with: pip install psutil
 
-# Note: For optional CPU-side mask acceleration, run:
+# Note: For optional legacy helper coverage, run:
 # pip install -r requirements_enhanced.txt
-# pip install opencv-python scipy
+# pip install scipy

tests/test_enhance_stage.py

@@ -34,11 +34,22 @@ class EnhanceStageContractTest(unittest.TestCase):
         self.assertIn("spandrel", app)
         self.assertIn("tile_upscale", app)
 
-    def test_upscaler_dependencies_are_declared(self):
-        requirements = read_text("requirements.txt")
-
-        self.assertIn("spandrel", requirements)
-        self.assertIn("spandrel_extra_arches", requirements)
+    def test_upscaler_dependencies_are_declared(self):
+        requirements = read_text("requirements.txt")
+
+        self.assertIn("spandrel", requirements)
+        self.assertIn("spandrel_extra_arches", requirements)
+        self.assertIn("opencv-python-headless", requirements)
+
+    def test_qwen_detailer_is_part_of_clean_and_max_detail(self):
+        app = read_text("app.py")
+
+        self.assertIn("ENHANCE_DETAILER_ENABLED", app)
+        self.assertIn("qwen_tiled_detailer_pass", app)
+        self.assertIn("qwen_hair_mask", app)
+        self.assertIn("qwen_face_feature_mask", app)
+        self.assertIn("Detailing face regions", app)
+        self.assertIn("Detailing final face and hair tiles", app)
 
 
 if __name__ == "__main__":