cpu intensive without tweak best result

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+venv/
+.env
+outputs/*.svg
+models/*.onnx
+models/*.onnx_data
+*.log
+.DS_Store
+*.png
+*.webp
+*.jpg
+*.jpeg
+result_*.json
+outputs/

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# System deps for OpenCV headless
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY download_model.py .
+RUN python download_model.py
+
+COPY app/ app/
+
+RUN mkdir -p outputs
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -0,0 +1,40 @@
+---
+title: Color By Number Pro API
+emoji: 🎨
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+
+# Color-by-Number Pro API
+
+Advanced image processing backend for converting photos, illustrations, and anime into high-quality color-by-number templates.
+
+## Features
+- **SAM2 Segmentation**: Pixel-perfect region detection.
+- **Depth Estimation**: Automatic difficulty layers based on image depth.
+- **Adjacency Matrix**: Pre-calculated region neighbors for fast frontend logic.
+- **Pole of Inaccessibility**: Perfect number placement inside complex borders.
+- **SVG Output**: Clean, vectorized outputs with optional auto-coloring.
+
+## API Documentation
+Once running, visit the interactive docs at:
+`https://your-space-name.hf.space/docs`
+
+### Main Endpoints
+- `POST /api/process`: Primary endpoint for converting images.
+- `GET /health`: Check service status.
+
+## Deployment on Hugging Face
+1. Create a new **Space**.
+2. Select **Gradio** as the SDK (even though we use FastAPI).
+3. Upload all files.
+4. Set `GENERATION_API_KEY` in the Space settings if using AI prompt generation.
+
+## Local Development
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,14 @@
+import uvicorn
+from app.main import app
+from download_models import download_all
+import os
+
+if __name__ == "__main__":
+    # Ensure models are downloaded on first start
+    print("Pre-loading models...")
+    download_all(required_only=True)
+    
+    # Hugging Face usually provides a PORT env var
+    port = int(os.environ.get("PORT", 7860))
+    # Note: Hugging Face default port is 7860
+    uvicorn.run(app, host="0.0.0.0", port=port)

app/config.py

@@ -0,0 +1,126 @@
+"""Central configuration for all models and pipeline settings."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class Quality(str, Enum):
+    FAST = "fast"
+    BALANCED = "balanced"
+    HIGH = "high"
+    ULTRA = "ultra"
+
+
+class LineArtStyle(str, Enum):
+    INFORMATIVE = "informative"
+    ANYLINE = "anyline"
+    MANGA = "manga"
+    FUSED = "fused"          # Merge multiple models
+    AUTO = "auto"            # Pick based on content
+
+
+class ContentType(str, Enum):
+    PHOTO = "photo"
+    ILLUSTRATION = "illustration"
+    ANIME = "anime"
+    PORTRAIT = "portrait"
+    LANDSCAPE = "landscape"
+    AUTO = "auto"
+
+
+class Difficulty(str, Enum):
+    EASY = "easy"       # 6-8 colors, large regions
+    MEDIUM = "medium"   # 10-14 colors
+    HARD = "hard"       # 16-22 colors, small regions
+    EXPERT = "expert"   # 24-30 colors, tiny regions
+    AUTO = "auto"
+
+
+@dataclass
+class ModelPaths:
+    informative_drawings: str = "models/informative_drawings.onnx"
+    anyline: str = "models/anyline.onnx"
+    manga_line: str = "models/manga_line.onnx"
+    sam2_encoder: str = "models/sam2_encoder.onnx"
+    sam2_decoder: str = "models/sam2_decoder.onnx"
+    depth_anything: str = "models/depth_anything_v2.onnx"
+    real_esrgan: str = "models/real_esrgan_x4.onnx"
+    rmbg: str = "models/rmbg2.onnx"
+    face_parsing: str = "models/face_parsing.onnx"
+
+    def available(self, name: str) -> bool:
+        path = getattr(self, name, None)
+        return path is not None and Path(path).exists()
+
+
+@dataclass
+class PipelineConfig:
+    # Content
+    content_type: ContentType = ContentType.AUTO
+    difficulty: Difficulty = Difficulty.AUTO
+    quality: Quality = Quality.BALANCED
+
+    # Colors
+    k_colors: int | None = None   # None = auto
+    use_lab: bool = True
+    spatial_weight: float = 0.0
+
+    # Line art
+    line_style: LineArtStyle = LineArtStyle.FUSED
+    line_threshold: int = 128
+
+    # Regions
+    min_region_area: int = 200
+    use_sam: bool = True          # Use SAM2 for segmentation
+
+    # Enhancement
+    upscale_if_small: bool = True
+    remove_background: bool = False
+    detect_faces: bool = True
+
+    # Depth
+    use_depth: bool = True
+    depth_layers: int = 3         # Number of difficulty layers
+
+    # Closing
+    density: str = "auto"
+    close_kernel: int = 3
+    close_iterations: int = 2
+    bridge_gaps: bool = True
+
+    # System
+    max_dimension: int = 1024
+    save_debug: bool = False
+    debug_dir: str = "outputs/debug"
+
+    def apply_difficulty(self):
+        """Set parameters based on difficulty level."""
+        presets = {
+            Difficulty.EASY:   {"k": 8,  "min_area": 500, "spatial": 0.4},
+            Difficulty.MEDIUM: {"k": 14, "min_area": 300, "spatial": 0.2},
+            Difficulty.HARD:   {"k": 22, "min_area": 150, "spatial": 0.1},
+            Difficulty.EXPERT: {"k": 30, "min_area": 20,  "spatial": 0.05},
+        }
+        if self.difficulty in presets:
+            p = presets[self.difficulty]
+            if self.k_colors is None:
+                self.k_colors = p["k"]
+            self.min_region_area = p["min_area"]
+            self.spatial_weight = p["spatial"]
+
+    def apply_quality(self):
+        """Set processing params based on quality level."""
+        if self.quality == Quality.FAST:
+            self.use_sam = False
+            self.use_depth = False
+            self.bridge_gaps = False
+            self.line_style = LineArtStyle.INFORMATIVE
+            self.upscale_if_small = False
+        elif self.quality == Quality.ULTRA:
+            self.use_sam = True
+            self.use_depth = True
+            self.bridge_gaps = True
+            self.line_style = LineArtStyle.FUSED
+            self.density = "dense"
+            self.close_iterations = 2 

app/main.py

@@ -0,0 +1,201 @@
+"""
+FastAPI app with all model endpoints.
+"""
+
+import os
+import uuid
+import cv2
+import numpy as np
+from pathlib import Path
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
+from fastapi.responses import Response, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from app.config import PipelineConfig, ModelPaths, Quality, ContentType, Difficulty, LineArtStyle
+from app.pipeline import ColorByNumberPipeline
+
+
+pipeline: ColorByNumberPipeline | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global pipeline
+    paths = ModelPaths()
+
+    # Create directories if they don't exist
+    for d in ["outputs", "outputs/debug", "models"]:
+        Path(d).mkdir(exist_ok=True)
+
+    # Note: We don't crash if models are missing, the pipeline gracefully degrades
+    # but we print their status.
+    pipeline = ColorByNumberPipeline(
+        model_paths=paths,
+        generation_api_key=os.getenv("GENERATION_API_KEY", ""),
+        generation_provider=os.getenv("GENERATION_PROVIDER", "replicate"),
+    )
+
+    print("✓ Pro Pipeline loaded")
+    print(f"  Model Status: {pipeline.registry.status()}")
+    yield
+
+
+app = FastAPI(title="Color-by-Number Pro API", version="3.0.0", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Mount outputs for static access
+app.mount("/static", StaticFiles(directory="outputs"), name="static")
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "model_loaded": pipeline is not None}
+
+
+@app.get("/models/status")
+async def model_status():
+    if pipeline is None:
+        raise HTTPException(503, "Not initialized")
+    return pipeline.registry.status()
+
+
+@app.post("/generate")
+async def generate(
+    image: UploadFile = File(...),
+    difficulty: str = Form(default="auto"),
+    quality: str = Form(default="balanced"),
+    content_type: str = Form(default="auto"),
+    line_style: str = Form(default="auto"),
+    k_colors: int = Form(default=0, ge=0, le=30),
+    remove_background: bool = Form(default=False),
+    use_sam: bool = Form(default=True),
+    use_depth: bool = Form(default=True),
+    save_debug: bool = Form(default=False),
+    max_dimension: int = Form(default=1024, ge=256, le=2048),
+    response_format: str = Form(default="json"),
+):
+    if pipeline is None:
+        raise HTTPException(503, "Not initialized")
+
+    ct = image.content_type or ""
+    if not ct.startswith("image/"):
+        raise HTTPException(400, f"Expected image, got {ct}")
+
+    raw = await image.read()
+    arr = np.frombuffer(raw, dtype=np.uint8)
+    img = cv2.imdecode(arr, cv2.IMREAD_COLOR)
+    if img is None:
+        raise HTTPException(400, "Could not decode image")
+
+    job_id = uuid.uuid4().hex[:12]
+
+    config = PipelineConfig(
+        content_type=ContentType(content_type),
+        difficulty=Difficulty(difficulty),
+        quality=Quality(quality),
+        line_style=LineArtStyle(line_style),
+        k_colors=k_colors if k_colors > 0 else None,
+        remove_background=remove_background,
+        use_sam=use_sam,
+        use_depth=use_depth,
+        save_debug=save_debug,
+        debug_dir=f"outputs/debug/{job_id}",
+        max_dimension=max_dimension,
+    )
+
+    result = pipeline.process(
+        image=img,
+        config=config,
+        output_path=f"outputs/{job_id}.svg",
+    )
+
+    response = {
+        "job_id": job_id,
+        "svg_url": f"/static/{job_id}.svg",
+        "outline_url": f"/static/{job_id}_outline.svg",
+        "palette": result["palette"],
+        "num_regions": result["num_regions"],
+        "content_type": result["content_type"],
+        "models_used": result["models_used"],
+        "k_colors_used": result["k_colors_used"],
+        "density_used": result["density_used"],
+    }
+
+    if "suggested_order" in result:
+        response["suggested_order"] = result["suggested_order"]
+    if "difficulty_layers" in result:
+        response["difficulty_layers"] = result["difficulty_layers"]
+    if "regions" in result:
+        response["regions"] = result["regions"]
+    if save_debug:
+        response["debug_dir"] = f"/static/debug/{job_id}/"
+
+    if response_format == "svg":
+        return Response(content=result["svg_string"], media_type="image/svg+xml")
+    elif response_format == "outline":
+        return Response(content=result["svg_outline_string"], media_type="image/svg+xml")
+
+    response["svg_string"] = result["svg_string"]
+    return JSONResponse(response)
+
+
+@app.post("/generate-from-prompt")
+async def generate_from_prompt(
+    prompt: str = Form(..., description="What to generate"),
+    style: str = Form(default="coloring_book"),
+    difficulty: str = Form(default="medium"),
+    quality: str = Form(default="balanced"),
+    response_format: str = Form(default="json"),
+):
+    if pipeline is None:
+        raise HTTPException(503, "Not initialized")
+
+    if not pipeline.generator.available:
+        raise HTTPException(
+            501,
+            "Generation API not configured. Set GENERATION_API_KEY env var.",
+        )
+
+    job_id = uuid.uuid4().hex[:12]
+
+    config = PipelineConfig(
+        difficulty=Difficulty(difficulty),
+        quality=Quality(quality),
+        content_type=ContentType.ILLUSTRATION,
+    )
+
+    result = await pipeline.generate_from_prompt(
+        prompt=prompt,
+        style=style,
+        config=config,
+        output_path=f"outputs/{job_id}.svg",
+    )
+
+    if result is None:
+        raise HTTPException(500, "Image generation failed")
+
+    response = {
+        "job_id": job_id,
+        "prompt": prompt,
+        "style": style,
+        "svg_url": f"/static/{job_id}.svg",
+        "palette": result["palette"],
+        "num_regions": result["num_regions"],
+        "models_used": result["models_used"],
+    }
+
+    if response_format == "svg":
+        return Response(content=result["svg_string"], media_type="image/svg+xml")
+
+    response["svg_string"] = result["svg_string"]
+    return JSONResponse(response)

app/models/background.py

@@ -0,0 +1,54 @@
+"""
+RMBG-2.0 background removal.
+"""
+
+import cv2
+import numpy as np
+
+from app.models.registry import ModelRegistry
+
+
+class BackgroundRemover:
+    """RMBG-2.0 for subject isolation."""
+
+    def __init__(self, registry: ModelRegistry):
+        self.registry = registry
+
+    @property
+    def available(self) -> bool:
+        return self.registry.available("rmbg")
+
+    def remove(self, image: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        session = self.registry.get("rmbg")
+        if session is None:
+            mask = np.full(image.shape[:2], 255, dtype=np.uint8)
+            return image, mask
+
+        h, w = image.shape[:2]
+        input_info = session.get_inputs()[0]
+        if isinstance(input_info.shape[2], int):
+            th, tw = input_info.shape[2], input_info.shape[3]
+        else:
+            th, tw = 1024, 1024
+
+        rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        resized = cv2.resize(rgb, (tw, th))
+        blob = resized.astype(np.float32) / 255.0
+        mean = np.array([0.485, 0.456, 0.406])
+        std = np.array([0.229, 0.224, 0.225])
+        blob = (blob - mean) / std
+        blob = np.transpose(blob, (2, 0, 1))
+        blob = np.expand_dims(blob, axis=0).astype(np.float32)
+
+        output = session.run(None, {input_info.name: blob})[0]
+        alpha = np.squeeze(output)
+        alpha = np.clip(alpha, 0, 1)
+        alpha = cv2.resize(alpha, (w, h))
+        mask = (alpha > 0.5).astype(np.uint8) * 255
+        result = image.copy()
+        result[mask == 0] = [255, 255, 255]
+        return result, mask
+
+    def get_foreground_mask(self, image: np.ndarray) -> np.ndarray:
+        _, mask = self.remove(image)
+        return mask

app/models/depth_estimator.py

@@ -0,0 +1,87 @@
+"""
+Depth Anything V2 integration for automatic difficulty layering.
+"""
+
+import cv2
+import numpy as np
+import onnxruntime as ort
+
+from app.models.registry import ModelRegistry
+
+
+class DepthEstimator:
+    """Monocular depth estimation using Depth Anything V2."""
+
+    def __init__(self, registry: ModelRegistry):
+        self.registry = registry
+
+    @property
+    def available(self) -> bool:
+        return self.registry.available("depth_anything")
+
+    def estimate(self, image: np.ndarray) -> np.ndarray:
+        session = self.registry.get("depth_anything")
+        if session is None:
+            raise RuntimeError("Depth model not available")
+
+        h, w = image.shape[:2]
+        input_info = session.get_inputs()[0]
+        if isinstance(input_info.shape[2], int):
+            target_h, target_w = input_info.shape[2], input_info.shape[3]
+        else:
+            target_h, target_w = 518, 518
+
+        rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        resized = cv2.resize(rgb, (target_w, target_h))
+        blob = resized.astype(np.float32) / 255.0
+        mean = np.array([0.485, 0.456, 0.406])
+        std = np.array([0.229, 0.224, 0.225])
+        blob = (blob - mean) / std
+        blob = np.transpose(blob, (2, 0, 1))
+        blob = np.expand_dims(blob, axis=0).astype(np.float32)
+
+        depth = session.run(None, {input_info.name: blob})[0]
+        depth = np.squeeze(depth)
+        depth = (depth - depth.min()) / (depth.max() - depth.min() + 1e-8)
+        depth = cv2.resize(depth, (w, h))
+
+        return depth
+
+    def assign_difficulty_layers(
+        self,
+        depth_map: np.ndarray,
+        label_map: np.ndarray,
+        n_layers: int = 3,
+    ) -> dict[int, int]:
+        unique_labels = np.unique(label_map)
+        unique_labels = unique_labels[unique_labels >= 0]
+        region_depths = {}
+        for lbl in unique_labels:
+            mask = label_map == lbl
+            avg_depth = depth_map[mask].mean()
+            region_depths[int(lbl)] = avg_depth
+        depths = np.array(list(region_depths.values()))
+        if len(depths) == 0:
+            return {int(lbl): 0 for lbl in unique_labels}
+            
+        thresholds = np.quantile(depths, np.linspace(0, 1, n_layers + 1)[1:-1])
+        layer_assignments = {}
+        for lbl, depth in region_depths.items():
+            layer = int(np.searchsorted(thresholds, depth))
+            layer_assignments[lbl] = min(layer, n_layers - 1)
+        return layer_assignments
+
+    def create_ordering(
+        self,
+        depth_map: np.ndarray,
+        label_map: np.ndarray,
+    ) -> list[int]:
+        unique_labels = np.unique(label_map)
+        unique_labels = unique_labels[unique_labels >= 0]
+        depths = []
+        for lbl in unique_labels:
+            mask = label_map == lbl
+            avg_depth = depth_map[mask].mean()
+            depths.append((int(lbl), avg_depth))
+        depths.sort(key=lambda x: x[1])
+        return [lbl for lbl, _ in depths]

app/models/face_parser.py

@@ -0,0 +1,142 @@
+"""
+Face parsing for portrait-specific region handling.
+"""
+
+import cv2
+import numpy as np
+
+from app.models.registry import ModelRegistry
+
+
+FACE_REGION_GROUPS = {
+    "skin": [1, 14],
+    "left_eye": [4],
+    "right_eye": [5],
+    "left_eyebrow": [2],
+    "right_eyebrow": [3],
+    "nose": [10],
+    "upper_lip": [12],
+    "lower_lip": [13],
+    "mouth_interior": [11],
+    "hair": [17],
+    "left_ear": [7],
+    "right_ear": [8],
+    "glasses": [6],
+    "hat": [18],
+    "clothing": [16],
+    "accessories": [9, 15],
+}
+
+
+class FaceParser:
+    """BiSeNet face parsing for portrait-optimized coloring pages."""
+
+    def __init__(self, registry: ModelRegistry):
+        self.registry = registry
+
+    @property
+    def available(self) -> bool:
+        return self.registry.available("face_parsing")
+
+    def detect_faces(self, image: np.ndarray) -> list[tuple[int, int, int, int]]:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        cascade = cv2.CascadeClassifier(
+            cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
+        )
+        faces = cascade.detectMultiScale(gray, 1.1, 5, minSize=(80, 80))
+        return [tuple(f) for f in faces]
+
+    def parse(self, image: np.ndarray) -> np.ndarray | None:
+        session = self.registry.get("face_parsing")
+        if session is None:
+            return None
+
+        h, w = image.shape[:2]
+        input_info = session.get_inputs()[0]
+        if isinstance(input_info.shape[2], int):
+            th, tw = input_info.shape[2], input_info.shape[3]
+        else:
+            th, tw = 512, 512
+
+        rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        resized = cv2.resize(rgb, (tw, th))
+        blob = resized.astype(np.float32) / 255.0
+        mean = np.array([0.485, 0.456, 0.406])
+        std = np.array([0.229, 0.224, 0.225])
+        blob = (blob - mean) / std
+        blob = np.transpose(blob, (2, 0, 1))
+        blob = np.expand_dims(blob, axis=0).astype(np.float32)
+
+        output = session.run(None, {input_info.name: blob})[0]
+        parsed = np.squeeze(output)
+
+        if parsed.ndim == 3:
+            parsed = np.argmax(parsed, axis=0)
+
+        parsed = cv2.resize(
+            parsed.astype(np.float32), (w, h),
+            interpolation=cv2.INTER_NEAREST
+        ).astype(np.int32)
+
+        return parsed
+
+    def merge_with_label_map(
+        self,
+        face_parse: np.ndarray,
+        label_map: np.ndarray,
+        face_bbox: tuple[int, int, int, int] | None = None,
+    ) -> np.ndarray:
+        result = label_map.copy()
+        h, w = result.shape
+        max_existing = label_map.max() + 1
+
+        if face_bbox is not None:
+            x, y, fw, fh = face_bbox
+            expand = 0.3
+            x = max(0, int(x - fw * expand))
+            y = max(0, int(y - fh * expand))
+            fw = min(w - x, int(fw * (1 + 2 * expand)))
+            fh = min(h - y, int(fh * (1 + 2 * expand)))
+            face_region = np.zeros((h, w), dtype=bool)
+            face_region[y:y + fh, x:x + fw] = True
+        else:
+            face_region = face_parse > 0
+
+        grouped = np.full_like(face_parse, -1)
+        for group_idx, (group_name, raw_labels) in enumerate(
+            FACE_REGION_GROUPS.items()
+        ):
+            for raw_lbl in raw_labels:
+                grouped[face_parse == raw_lbl] = max_existing + group_idx
+
+        valid = face_region & (grouped >= 0)
+        result[valid] = grouped[valid]
+        return result
+
+    def is_portrait(self, image: np.ndarray) -> bool:
+        faces = self.detect_faces(image)
+        if not faces:
+            return False
+            
+        h, w = image.shape[:2]
+        img_area = h * w
+        
+        for x, y, fw, fh in faces:
+            face_area = fw * fh
+            # 1. Size check
+            if face_area / img_area < 0.05:
+                continue
+                
+            # 2. skin-tone check (Haar cascade fix for flowers)
+            face_crop = image[y:y+fh, x:x+fw]
+            if face_crop.size == 0: continue
+            
+            # Simple YCbCr skin detection
+            ycrcb = cv2.cvtColor(face_crop, cv2.COLOR_BGR2YCrCb)
+            mask = cv2.inRange(ycrcb, (0, 133, 77), (255, 173, 127))
+            skin_ratio = np.count_nonzero(mask) / mask.size
+            
+            if skin_ratio > 0.4: # Only if it's reasonably skin-colored
+                return True
+                
+        return False

app/models/generator.py

@@ -0,0 +1,169 @@
+"""
+AI template generation using Stable Diffusion / Flux API.
+"""
+
+import httpx
+import base64
+import asyncio
+from io import BytesIO
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+class TemplateGenerator:
+    """Generate coloring page templates from text prompts."""
+
+    def __init__(
+        self,
+        api_key: str = "",
+        provider: str = "replicate",
+        base_url: str = "",
+    ):
+        self.api_key = api_key
+        self.provider = provider
+        self.base_url = base_url or self._default_url()
+
+    def _default_url(self) -> str:
+        urls = {
+            "replicate": "https://api.replicate.com/v1/predictions",
+            "together": "https://api.together.xyz/v1/images/generations",
+            "stability": "https://api.stability.ai/v2beta/stable-image/generate/core",
+        }
+        return urls.get(self.provider, "")
+
+    @property
+    def available(self) -> bool:
+        return bool(self.api_key)
+
+    async def generate_from_prompt(
+        self,
+        prompt: str,
+        style: str = "coloring_book",
+        width: int = 1024,
+        height: int = 1024,
+    ) -> np.ndarray | None:
+        style_suffixes = {
+            "coloring_book": (
+                "clean line art, coloring book page, black outlines on white "
+                "background, no shading, no color fill, simple shapes, "
+                "clear boundaries between regions, vector art style"
+            ),
+            "realistic": (
+                "detailed illustration, clear edges, distinct color regions, "
+                "flat colors, no gradients, poster style"
+            ),
+            "cartoon": (
+                "cartoon style, bold black outlines, flat colors, "
+                "simple shapes, children's coloring book"
+            ),
+            "mandala": (
+                "mandala pattern, symmetrical, intricate line art, "
+                "black outlines on white, no fill colors"
+            ),
+            "pixel": (
+                "pixel art style, clear grid, distinct color blocks, "
+                "retro game aesthetic, flat colors"
+            ),
+        }
+
+        enhanced_prompt = f"{prompt}, {style_suffixes.get(style, style_suffixes['coloring_book'])}"
+
+        try:
+            if self.provider == "replicate":
+                return await self._generate_replicate(enhanced_prompt, width, height)
+            elif self.provider == "together":
+                return await self._generate_together(enhanced_prompt, width, height)
+            elif self.provider == "stability":
+                return await self._generate_stability(enhanced_prompt, width, height)
+        except Exception as e:
+            print(f"Generation failed: {e}")
+            return None
+
+    async def _generate_replicate(
+        self, prompt: str, width: int, height: int
+    ) -> np.ndarray | None:
+        async with httpx.AsyncClient(timeout=120) as client:
+            resp = await client.post(
+                self.base_url,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "version": "39ed52f2a78e934b3ba6e2a89f5b1c712de7dfea535525255b1aa35c5565e08b",
+                    "input": {
+                        "prompt": prompt,
+                        "width": width,
+                        "height": height,
+                        "num_inference_steps": 28,
+                        "guidance_scale": 7.5,
+                    },
+                },
+            )
+            prediction = resp.json()
+            poll_url = prediction.get("urls", {}).get("get", "")
+            for _ in range(60):
+                await asyncio.sleep(2)
+                status_resp = await client.get(
+                    poll_url,
+                    headers={"Authorization": f"Bearer {self.api_key}"},
+                )
+                status = status_resp.json()
+                if status["status"] == "succeeded":
+                    image_url = status["output"][0]
+                    img_resp = await client.get(image_url)
+                    return self._bytes_to_cv2(img_resp.content)
+                elif status["status"] == "failed":
+                    return None
+        return None
+
+    async def _generate_together(
+        self, prompt: str, width: int, height: int
+    ) -> np.ndarray | None:
+        async with httpx.AsyncClient(timeout=120) as client:
+            resp = await client.post(
+                self.base_url,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": "black-forest-labs/FLUX.1-schnell",
+                    "prompt": prompt,
+                    "width": width,
+                    "height": height,
+                    "n": 1,
+                    "response_format": "b64_json",
+                },
+            )
+            data = resp.json()
+            b64 = data["data"][0]["b64_json"]
+            img_bytes = base64.b64decode(b64)
+            return self._bytes_to_cv2(img_bytes)
+
+    async def _generate_stability(
+        self, prompt: str, width: int, height: int
+    ) -> np.ndarray | None:
+        async with httpx.AsyncClient(timeout=120) as client:
+            resp = await client.post(
+                self.base_url,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Accept": "image/png",
+                },
+                files={"none": ""},
+                data={
+                    "prompt": prompt,
+                    "output_format": "png",
+                    "aspect_ratio": f"{width}:{height}",
+                },
+            )
+            if resp.status_code == 200:
+                return self._bytes_to_cv2(resp.content)
+        return None
+
+    def _bytes_to_cv2(self, img_bytes: bytes) -> np.ndarray:
+        nparr = np.frombuffer(img_bytes, np.uint8)
+        return cv2.imdecode(nparr, cv2.IMREAD_COLOR)

app/models/line_art.py

@@ -0,0 +1,209 @@
+"""
+Multi-model line art extraction with intelligent fusion.
+"""
+
+import cv2
+import numpy as np
+import onnxruntime as ort
+
+from app.models.registry import ModelRegistry
+from app.config import LineArtStyle
+from app.processing.utils import (
+    multi_scale_close,
+    directional_close,
+    bridge_endpoints,
+    hysteresis_threshold,
+    declutter_lines,
+)
+
+
+class MultiLineArtExtractor:
+    """Extracts line art using one or more AI models."""
+
+    def __init__(self, registry: ModelRegistry):
+        self.registry = registry
+
+    def _run_model(
+        self,
+        session: ort.InferenceSession,
+        image_bgr: np.ndarray,
+        target_size: int = 512,
+    ) -> np.ndarray:
+        """Run a single ONNX line art model."""
+        original_h, original_w = image_bgr.shape[:2]
+
+        rgb = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2RGB)
+        resized = cv2.resize(rgb, (target_size, target_size))
+        blob = resized.astype(np.float32) / 255.0
+        blob = np.transpose(blob, (2, 0, 1))
+        blob = np.expand_dims(blob, axis=0)
+
+        input_name = session.get_inputs()[0].name
+        outputs = session.run(None, {input_name: blob})
+        raw = np.squeeze(outputs[0])
+        raw = np.clip(raw, 0.0, 1.0)
+
+        return cv2.resize(raw, (original_w, original_h))
+
+    def _preprocess(self, image: np.ndarray) -> np.ndarray:
+        """Bilateral filter + CLAHE for cleaner model input."""
+        filtered = cv2.bilateralFilter(image, d=9, sigmaColor=75, sigmaSpace=75)
+        lab = cv2.cvtColor(filtered, cv2.COLOR_BGR2LAB)
+        clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+        lab[:, :, 0] = clahe.apply(lab[:, :, 0])
+        return cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)
+
+    def extract(
+        self,
+        image: np.ndarray,
+        style: LineArtStyle = LineArtStyle.FUSED,
+        density: str = "normal",
+        bridge_gaps: bool = True,
+    ) -> np.ndarray:
+        """
+        Extract line art using specified style.
+        """
+        preprocessed = self._preprocess(image)
+        outputs: list[np.ndarray] = []
+
+        # ── Decide which models to run ──
+        if style == LineArtStyle.AUTO:
+            style = self._detect_best_style(image)
+
+        if style == LineArtStyle.FUSED:
+            models_to_run = ["informative_drawings", "anyline"]
+        elif style == LineArtStyle.MANGA:
+            models_to_run = ["manga_line"]
+        elif style == LineArtStyle.ANYLINE:
+            models_to_run = ["anyline"]
+        else:
+            models_to_run = ["informative_drawings"]
+
+        print(f"  [LineArt] Styles to run: {models_to_run}")
+
+        # ── Run each available model ──
+        for model_name in models_to_run:
+            session = self.registry.get(model_name)
+            if session is None:
+                continue
+
+            sizes = self._get_inference_sizes(model_name, density)
+            scale_outputs = []
+            for size in sizes:
+                out = self._run_model(session, preprocessed, target_size=size)
+                scale_outputs.append(out)
+
+            merged = scale_outputs[0]
+            for o in scale_outputs[1:]:
+                merged = np.maximum(merged, o)
+
+            outputs.append(merged)
+
+        # ── Fallback: Canny if no models available ──
+        if not outputs:
+            gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+            edges = cv2.Canny(gray, 50, 150)
+            outputs.append(edges.astype(np.float32) / 255.0)
+
+        # ── Fuse multiple model outputs ──
+        if len(outputs) == 1:
+            fused = outputs[0]
+        else:
+            print(f"  [LineArt] Fusing {len(outputs)} model outputs...")
+            fused = self._fuse_outputs(outputs)
+
+        # ── To uint8 ──
+        gray = (fused * 255).astype(np.uint8)
+
+        # ── Hysteresis threshold ──
+        thresholds = {
+            "sparse": (100, 200),
+            "normal": (90, 180),
+            "dense":  (80, 160),
+        }
+        lo, hi = thresholds.get(density, (90, 180))
+        binary = hysteresis_threshold(gray, low=lo, high=hi)
+        binary = cv2.bitwise_not(binary)  # lines = 0, bg = 255
+
+        # ── Aggressive closing pipeline ──
+        print("  [LineArt] Running closing pipeline...")
+        binary = self._close_pipeline(binary, density, bridge_gaps=bridge_gaps)
+
+        return binary
+
+    def _fuse_outputs(self, outputs: list[np.ndarray]) -> np.ndarray:
+        """Intelligent fusion of multiple model outputs."""
+        if len(outputs) == 2:
+            a, b = outputs[0], outputs[1]
+            agreement = np.minimum(a, b)
+            union = np.maximum(a, b)
+            fused = 0.7 * agreement + 0.3 * union
+            both_strong = (a > 0.3) & (b > 0.3)
+            fused[both_strong] = np.maximum(fused[both_strong], 0.8)
+            return np.clip(fused, 0.0, 1.0)
+        else:
+            stacked = np.stack(outputs)
+            avg = np.mean(stacked, axis=0)
+            agree_count = np.sum(stacked > 0.3, axis=0).astype(np.float32)
+            boost = agree_count / len(outputs)
+            fused = avg * (0.5 + 0.5 * boost)
+            return np.clip(fused, 0.0, 1.0)
+
+    def _close_pipeline(self, binary: np.ndarray, density: str, bridge_gaps: bool = True) -> np.ndarray:
+        """Full morphological closing pipeline."""
+        h, w = binary.shape
+        scale_factor = min(w, h) / 1024 # Normalize based on 1024px baseline
+        
+        configs = {
+            "sparse": {"kernels": [3], "dir_len": 5, "iters": 1, "bridge": 5},
+            "normal": {"kernels": [3, 5], "dir_len": 7, "iters": 1, "bridge": 10},
+            "dense":  {"kernels": [3, 5, 7], "dir_len": 9, "iters": 2, "bridge": 15},
+        }
+        cfg = configs.get(density, configs["normal"])
+        
+        # Scale bridge radius
+        bridge_dist = max(1, int(cfg["bridge"] * scale_factor))
+        if scale_factor < 0.5: # Small image
+            bridge_dist = min(bridge_dist, 8)
+
+        print("            - Multi-scale close...")
+        result = multi_scale_close(binary, cfg["kernels"], cfg["iters"])
+        print("            - Directional close...")
+        result = directional_close(result, cfg["dir_len"], cfg["iters"])
+
+        smooth = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+        result = cv2.morphologyEx(result, cv2.MORPH_CLOSE, smooth, iterations=1)
+
+        if bridge_gaps:
+            print(f"            - Bridging endpoints (radius {bridge_dist})...")
+            result = bridge_endpoints(result, search_radius=bridge_dist)
+
+        # ── Declutter: Merge close lines and thin out ──
+        print("            - Decluttering lines (merge & thin)...")
+        result = declutter_lines(result, merge_radius=2, thin_out=True)
+
+        return result
+
+    def _detect_best_style(self, image: np.ndarray) -> LineArtStyle:
+        """Auto-detect content type to pick the best model."""
+        hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+        saturation = hsv[:, :, 1].mean()
+        if saturation > 120:
+            if self.registry.available("manga_line"):
+                return LineArtStyle.MANGA
+        return LineArtStyle.FUSED
+
+    def _get_inference_sizes(self, model_name: str, density: str) -> list[int]:
+        """Get multi-scale inference sizes per model and density."""
+        base = {
+            "informative_drawings": 512,
+            "anyline": 768,
+            "manga_line": 512,
+        }.get(model_name, 512)
+
+        if density == "sparse":
+            return [base]
+        elif density == "dense":
+            return [max(256, base - 128), base, base + 256]
+        else:
+            return [base, base + 256]

app/models/registry.py

@@ -0,0 +1,79 @@
+"""
+Lazy-loading model registry.
+
+Models load on first use and stay in memory.
+Gracefully degrades when optional models are missing.
+"""
+
+import onnxruntime as ort
+from pathlib import Path
+from typing import Any
+
+from app.config import ModelPaths
+
+
+class ModelRegistry:
+    """Singleton that manages all ONNX model sessions."""
+
+    def __init__(self, paths: ModelPaths | None = None):
+        self.paths = paths or ModelPaths()
+        self._sessions: dict[str, ort.InferenceSession | None] = {}
+        self._availability: dict[str, bool] = {}
+
+        # Check what's available at startup
+        for attr in vars(self.paths):
+            if not attr.startswith("_"):
+                path = getattr(self.paths, attr)
+                self._availability[attr] = Path(path).exists()
+
+        # Safely detect providers
+        available = ort.get_available_providers()
+        print(f"  Available ONNX Providers: {available}")
+        
+        self._providers = []
+        if "CUDAExecutionProvider" in available:
+            self._providers.append("CUDAExecutionProvider")
+        if "CPUExecutionProvider" in available:
+            self._providers.append("CPUExecutionProvider")
+        
+        if not self._providers:
+            self._providers = ["CPUExecutionProvider"]
+
+    def available(self, name: str) -> bool:
+        return self._availability.get(name, False)
+
+    def get(self, name: str) -> ort.InferenceSession | None:
+        """Get or lazily load an ONNX session."""
+        if name in self._sessions:
+            return self._sessions[name]
+
+        if not self.available(name):
+            self._sessions[name] = None
+            return None
+
+        path = getattr(self.paths, name)
+        print(f"  [Registry] Loading {name}...")
+        print(f"             Path: {path}")
+
+        try:
+            # Add a timeout check or more logs if it hangs here
+            session = ort.InferenceSession(path, providers=self._providers)
+            print(f"  [Registry] ✓ {name} loaded successfully.")
+            self._sessions[name] = session
+            return session
+        except Exception as e:
+            print(f"  [Registry] ✗ Failed to load {name}: {e}")
+            self._sessions[name] = None
+            return None
+
+    def status(self) -> dict[str, str]:
+        """Return availability status of all models."""
+        result = {}
+        for name, avail in self._availability.items():
+            if name in self._sessions:
+                result[name] = "loaded" if self._sessions[name] else "failed"
+            elif avail:
+                result[name] = "available"
+            else:
+                result[name] = "missing"
+        return result

app/models/sam_segmenter.py

@@ -0,0 +1,319 @@
+"""
+SAM2 (Segment Anything Model 2) integration. Refined for SAM 2.1 ONNX.
+"""
+
+import cv2
+import numpy as np
+import onnxruntime as ort
+from scipy import ndimage
+
+from app.models.registry import ModelRegistry
+
+
+class SAMSegmenter:
+    """Segment Anything Model 2 for semantic region extraction."""
+
+    def __init__(self, registry: ModelRegistry):
+        self.registry = registry
+        self._encoder: ort.InferenceSession | None = None
+        self._decoder: ort.InferenceSession | None = None
+
+    @property
+    def available(self) -> bool:
+        return (
+            self.registry.available("sam2_encoder")
+            and self.registry.available("sam2_decoder")
+        )
+
+    def _load(self):
+        if self._encoder is None:
+            self._encoder = self.registry.get("sam2_encoder")
+            self._decoder = self.registry.get("sam2_decoder")
+
+    def _encode_image(self, image: np.ndarray) -> dict[str, np.ndarray]:
+        """Run SAM2 image encoder to get embeddings and high-res features."""
+        resized = cv2.resize(image, (1024, 1024))
+        rgb = cv2.cvtColor(resized, cv2.COLOR_BGR2RGB)
+
+        # Standard ImageNet normalization
+        mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+        std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+        blob = rgb.astype(np.float32) / 255.0
+        blob = (blob - mean) / std
+        blob = np.transpose(blob, (2, 0, 1))
+        blob = np.expand_dims(blob, axis=0)
+
+        input_name = self._encoder.get_inputs()[0].name
+        outputs = self._encoder.run(None, {input_name: blob})
+        
+        # In SAM 2.1 ONNX, we often have multiple outputs: 
+        # [image_embeddings, high_res_feat_1, high_res_feat_2]
+        out_names = [o.name for o in self._encoder.get_outputs()]
+        return dict(zip(out_names, outputs))
+
+    def _generate_grid_points(
+        self, h: int, w: int, n_points_per_side: int = 32
+    ) -> np.ndarray:
+        """Generate a grid of prompt points."""
+        xs = np.linspace(0, w, n_points_per_side + 2)[1:-1]
+        ys = np.linspace(0, h, n_points_per_side + 2)[1:-1]
+        xx, yy = np.meshgrid(xs, ys)
+        points = np.column_stack([xx.ravel(), yy.ravel()])
+        return points.astype(np.float32)
+
+    def _decode_mask(
+        self,
+        encoded_dict: dict[str, np.ndarray],
+        point: np.ndarray,
+        original_size: tuple[int, int],
+    ) -> np.ndarray | None:
+        """Run SAM2 decoder for a single point prompt."""
+        h, w = original_size
+        point_scaled = point.copy()
+        point_scaled[0] *= 1024 / w
+        point_scaled[1] *= 1024 / h
+
+        # Use explicit reshapes to ensure Rank 4/3 exactly as required by SAM 2.1 ONNX
+        point_coords = np.array([point_scaled], dtype=np.float32).reshape((1, 1, 1, 2))
+        point_labels = np.array([1], dtype=np.int64).reshape((1, 1, 1))
+
+        # Map encoder outputs to decoder inputs
+        decoder_inputs = {}
+        
+        # Detect decoder input names
+        input_names = [i.name for i in self._decoder.get_inputs()]
+        
+        # 1. Fill image features (embeddings and high-res if present)
+        for name in input_names:
+            if name in encoded_dict:
+                decoder_inputs[name] = encoded_dict[name]
+            elif "image_embedding" in name: # Fallback names
+                decoder_inputs[name] = encoded_dict.get("image_embeddings", list(encoded_dict.values())[0])
+            elif "point_coords" in name or "input_points" in name:
+                decoder_inputs[name] = point_coords
+            elif "point_labels" in name or "input_labels" in name:
+                decoder_inputs[name] = point_labels
+            elif "input_boxes" in name:
+                # Provide empty box [1, 1, 4] for SAM 2.1
+                decoder_inputs[name] = np.zeros((1, 1, 4), dtype=np.float32)
+            elif "mask_input" in name:
+                decoder_inputs[name] = np.zeros((1, 1, 212, 212), dtype=np.float32) # Standard mask size for some exports
+                # Some exports want 256, 256. We check shape if possible.
+                for inp in self._decoder.get_inputs():
+                    if inp.name == name:
+                        if isinstance(inp.shape[2], int):
+                            decoder_inputs[name] = np.zeros((1, 1, inp.shape[2], inp.shape[3]), dtype=np.float32)
+            elif "has_mask" in name:
+                decoder_inputs[name] = np.array([0], dtype=np.float32).reshape((1,))
+            elif "orig_im_size" in name:
+                # SAM 2.1 often expects float32 [H, W]
+                decoder_inputs[name] = np.array([h, w], dtype=np.float32)
+
+        try:
+            outputs = self._decoder.run(None, decoder_inputs)
+        except Exception as e:
+            print(f"  [SAM decoder] ✗ Decoder run failed: {e}")
+            return None
+            
+        masks = outputs[0]
+        scores = outputs[1]
+
+        # Robust score indexing
+        flat_scores = scores.flatten()
+        best_idx = int(np.argmax(flat_scores))
+        
+        if flat_scores[best_idx] < 0.2: # Support very weak features in expert mode
+            return None
+
+        # Robust mask extraction regardless of Rank 4/5 variations
+        # masks is usually [1, 3, H, W] or [1, 1, 3, H, W]
+        m = np.squeeze(masks)
+        if m.ndim == 3: # (C, H, W)
+            # If C is 1 but best_idx is 0, this is fine. 
+            # If C is 3, pick the best.
+            idx = min(best_idx, m.shape[0] - 1)
+            mask = m[idx]
+        elif m.ndim == 2: # (H, W)
+            mask = m
+        else:
+            # Fallback for complex shapes
+            masks_reshaped = masks.reshape(-1, masks.shape[-2], masks.shape[-1])
+            idx = min(best_idx, masks_reshaped.shape[0] - 1)
+            mask = masks_reshaped[idx]
+            
+        mask = (mask > 0.0).astype(np.uint8)
+        mask = cv2.resize(mask, (w, h), interpolation=cv2.INTER_NEAREST)
+        return mask
+
+    def segment(
+        self,
+        image: np.ndarray,
+        n_points: int = 24, # Reduced for speed
+        min_area_ratio: float = 0.001,
+        max_segments: int = 50,
+    ) -> np.ndarray:
+        self._load()
+        if self._encoder is None or self._decoder is None:
+            raise RuntimeError("SAM2 models not available")
+
+        h, w = image.shape[:2]
+        min_area = int(h * w * min_area_ratio)
+        encoded_dict = self._encode_image(image)
+        points = self._generate_grid_points(h, w, n_points)
+
+        all_masks: list[np.ndarray] = []
+        all_areas: list[int] = []
+
+        for point in points:
+            mask = self._decode_mask(encoded_dict, point, (h, w))
+            if mask is None:
+                continue
+            
+            area = np.count_nonzero(mask)
+            if area < min_area:
+                continue
+
+            # NMS for masks
+            is_duplicate = False
+            for existing in all_masks:
+                iou = self._compute_iou(mask, existing)
+                if iou > 0.7: # Slightly lower threshold for merge
+                    is_duplicate = True
+                    break
+            if not is_duplicate:
+                all_masks.append(mask)
+                all_areas.append(area)
+
+        if not all_masks:
+            return np.zeros((h, w), dtype=np.int32)
+
+        if len(all_masks) > max_segments:
+            indices = np.argsort(all_areas)[::-1][:max_segments]
+            all_masks = [all_masks[i] for i in indices]
+
+        # Painter's algorithm
+        sorted_pairs = sorted(
+            enumerate(all_masks),
+            key=lambda x: np.count_nonzero(x[1]),
+            reverse=True,
+        )
+
+        label_map = np.full((h, w), -1, dtype=np.int32)
+        for new_idx, (_, mask) in enumerate(sorted_pairs):
+            label_map[mask > 0] = new_idx
+
+        if np.any(label_map == -1):
+            label_map = self._fill_unlabeled(label_map)
+
+        return label_map
+
+    def _compute_iou(self, mask1: np.ndarray, mask2: np.ndarray) -> float:
+        intersection = np.count_nonzero(mask1 & mask2)
+        union = np.count_nonzero(mask1 | mask2)
+        return intersection / max(union, 1)
+
+    def _fill_unlabeled(self, label_map: np.ndarray) -> np.ndarray:
+        unlabeled = label_map == -1
+        labeled = label_map >= 0
+        if not np.any(unlabeled) or not np.any(labeled):
+            return label_map
+            
+        _, nearest_indices = ndimage.distance_transform_edt(
+            unlabeled, return_distances=True, return_indices=True
+        )
+        result = label_map.copy()
+        result[unlabeled] = label_map[
+            nearest_indices[0][unlabeled],
+            nearest_indices[1][unlabeled],
+        ]
+        return result
+
+
+class HybridSegmenter:
+    """Combines SAM2 (semantic) + K-Means (color) segmentation."""
+
+    def __init__(self, sam: SAMSegmenter):
+        self.sam = sam
+
+    def segment(
+        self,
+        image: np.ndarray,
+        k_colors: int = 12,
+        spatial_weight: float = 0.1,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        from app.processing.quantizer import quantize_colors
+        
+        h, w = image.shape[:2]
+        
+        # 1. Semantic segmentation - use more points for complex scenes
+        print(f"  [HybridSeg] Running SAM with 32x32 grid...")
+        sam_labels = self.sam.segment(image, n_points=32, max_segments=400)
+        
+        # 2. Color segmentation - use spatial weight to separate distant same-color regions
+        print(f"  [HybridSeg] Running K-Means (k={k_colors}, spatial={spatial_weight})...")
+        _, km_palette, km_labels = quantize_colors(image, k_colors=k_colors, spatial_weight=spatial_weight)
+        
+        # 3. Intersect (Hybrid)
+        n_km = km_labels.max() + 1
+        compound = sam_labels.astype(np.int64) * n_km + km_labels.astype(np.int64)
+        
+        unique_compounds, inverse = np.unique(compound, return_inverse=True)
+        hybrid_labels = inverse.reshape(h, w).astype(np.int32)
+        
+        n_regions = len(unique_compounds)
+        print(f"  [HybridSeg] Found {n_regions} initial regions.")
+        
+        palette = np.zeros((n_regions, 3), dtype=np.uint8)
+        # Calculate palette for new regions - use median for robustness to boundaries
+        for region_id in range(n_regions):
+            mask = hybrid_labels == region_id
+            if np.any(mask):
+                palette[region_id] = np.median(image[mask], axis=0).astype(np.uint8)
+        
+        # 4. Merge if excessively many regions
+        limit = max(k_colors * 12, 400) 
+        if n_regions > limit:
+            print(f"  [HybridSeg] Merging {n_regions} down to {limit}...")
+            hybrid_labels, palette = self._merge_similar(
+                hybrid_labels, palette, target_k=limit
+            )
+            
+        return hybrid_labels, palette
+
+    def _merge_similar(
+        self,
+        labels: np.ndarray,
+        palette: np.ndarray,
+        target_k: int,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        from sklearn.cluster import AgglomerativeClustering
+        
+        n_current = len(palette)
+        if n_current <= target_k:
+            return labels, palette
+            
+        clustering = AgglomerativeClustering(
+            n_clusters=target_k,
+            metric="euclidean",
+            linkage="ward",
+        )
+        color_labels = clustering.fit_predict(palette.astype(np.float32))
+        
+        new_labels = color_labels[labels]
+        new_palette = np.zeros((target_k, 3), dtype=np.uint8)
+        
+        for i in range(target_k):
+            old_indices = np.where(color_labels == i)[0]
+            if len(old_indices) == 0: continue
+            
+            # Weighted average by area
+            areas = np.array([np.count_nonzero(labels == idx) for idx in old_indices])
+            weights = areas / max(areas.sum(), 1)
+            new_palette[i] = np.average(
+                palette[old_indices].astype(np.float32),
+                weights=weights,
+                axis=0,
+            ).astype(np.uint8)
+            
+        return new_labels, new_palette

app/models/super_resolution.py

@@ -0,0 +1,68 @@
+"""
+Real-ESRGAN 4x super resolution.
+"""
+
+import cv2
+import numpy as np
+
+from app.models.registry import ModelRegistry
+
+
+class SuperResolution:
+    """Real-ESRGAN 4x upscaling."""
+
+    def __init__(self, registry: ModelRegistry):
+        self.registry = registry
+
+    @property
+    def available(self) -> bool:
+        return self.registry.available("real_esrgan")
+
+    def upscale(
+        self,
+        image: np.ndarray,
+        tile_size: int = 256,
+        overlap: int = 16,
+    ) -> np.ndarray:
+        session = self.registry.get("real_esrgan")
+        if session is None:
+            h, w = image.shape[:2]
+            return cv2.resize(image, (w * 4, h * 4), interpolation=cv2.INTER_CUBIC)
+
+        h, w = image.shape[:2]
+        scale = 4
+        out_h, out_w = h * scale, w * scale
+        output = np.zeros((out_h, out_w, 3), dtype=np.float32)
+        weight = np.zeros((out_h, out_w, 1), dtype=np.float32)
+        input_name = session.get_inputs()[0].name
+
+        for y in range(0, h, tile_size - overlap):
+            for x in range(0, w, tile_size - overlap):
+                y2 = min(y + tile_size, h)
+                x2 = min(x + tile_size, w)
+                tile = image[y:y2, x:x2]
+                th, tw = tile.shape[:2]
+                if th < tile_size or tw < tile_size:
+                    padded = np.zeros((tile_size, tile_size, 3), dtype=np.uint8)
+                    padded[:th, :tw] = tile
+                    tile = padded
+                blob = tile.astype(np.float32) / 255.0
+                blob = np.transpose(blob, (2, 0, 1))
+                blob = np.expand_dims(blob, axis=0)
+                sr_tile = session.run(None, {input_name: blob})[0]
+                sr_tile = np.squeeze(sr_tile)
+                sr_tile = np.transpose(sr_tile, (1, 2, 0))
+                sr_tile = np.clip(sr_tile, 0, 1)
+                oy, ox = y * scale, x * scale
+                oth, otw = th * scale, tw * scale
+                output[oy:oy + oth, ox:ox + otw] += sr_tile[:oth, :otw]
+                weight[oy:oy + oth, ox:ox + otw] += 1.0
+
+        weight = np.maximum(weight, 1.0)
+        output = output / weight
+        output = (output * 255).astype(np.uint8)
+        return output[:out_h, :out_w]
+
+    def should_upscale(self, image: np.ndarray, min_dim: int = 400) -> bool:
+        h, w = image.shape[:2]
+        return min(h, w) < min_dim

app/pipeline.py

@@ -0,0 +1,393 @@
+"""
+Master pipeline combining all models.
+"""
+
+import cv2
+import numpy as np
+from pathlib import Path
+
+from app.config import PipelineConfig, ModelPaths, ContentType, LineArtStyle, Quality
+from app.models.registry import ModelRegistry
+from app.models.line_art import MultiLineArtExtractor
+from app.models.sam_segmenter import SAMSegmenter, HybridSegmenter
+from app.models.depth_estimator import DepthEstimator
+from app.models.super_resolution import SuperResolution
+from app.models.background import BackgroundRemover
+from app.models.face_parser import FaceParser
+from app.models.generator import TemplateGenerator
+from app.processing.quantizer import (
+    quantize_colors,
+    merge_line_art_with_regions,
+    merge_small_regions_into_neighbors,
+    smooth_label_map,
+    estimate_k,
+)
+from app.processing.utils import get_adjacency_matrix, get_pole_of_inaccessibility
+from app.processing.vectorizer import generate_svg
+from app.processing.difficulty import compute_region_difficulty
+
+
+class ColorByNumberPipeline:
+    """Full multi-model pipeline."""
+
+    def __init__(
+        self,
+        model_paths: ModelPaths | None = None,
+        generation_api_key: str = "",
+        generation_provider: str = "replicate",
+    ):
+        self.paths = model_paths or ModelPaths()
+        self.registry = ModelRegistry(self.paths)
+
+        self.line_art = MultiLineArtExtractor(self.registry)
+        self.sam = SAMSegmenter(self.registry)
+        self.hybrid_seg = HybridSegmenter(self.sam)
+        self.depth = DepthEstimator(self.registry)
+        self.super_res = SuperResolution(self.registry)
+        self.bg_remover = BackgroundRemover(self.registry)
+        self.face_parser = FaceParser(self.registry)
+        self.generator = TemplateGenerator(
+            api_key=generation_api_key,
+            provider=generation_provider,
+        )
+
+    def _detect_content_type(self, image: np.ndarray) -> ContentType:
+        if self.face_parser.available and self.face_parser.is_portrait(image):
+            return ContentType.PORTRAIT
+
+        hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+        avg_sat = hsv[:, :, 1].mean()
+        sat_std = hsv[:, :, 1].std()
+
+        if avg_sat > 100 and sat_std < 50:
+            return ContentType.ANIME
+
+        h, w = image.shape[:2]
+        if w / h > 1.3:
+            blue_mask = (hsv[:, :, 0] > 90) & (hsv[:, :, 0] < 130)
+            green_mask = (hsv[:, :, 0] > 35) & (hsv[:, :, 0] < 85)
+            nature_ratio = (blue_mask.sum() + green_mask.sum()) / (h * w)
+            if nature_ratio > 0.3:
+                return ContentType.LANDSCAPE
+
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        unique_vals = len(np.unique(gray[::4, ::4]))
+        if unique_vals < 50:
+            return ContentType.ILLUSTRATION
+
+        return ContentType.PHOTO
+
+    def _estimate_density(self, image: np.ndarray) -> str:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        edges = cv2.Canny(gray, 50, 150)
+        ratio = np.count_nonzero(edges) / edges.size
+        if ratio < 0.03:
+            return "sparse"
+        elif ratio < 0.08:
+            return "normal"
+        return "dense"
+
+    def _save_debug(self, name: str, img: np.ndarray, debug_dir: str):
+        Path(debug_dir).mkdir(parents=True, exist_ok=True)
+        cv2.imwrite(str(Path(debug_dir) / f"{name}.png"), img)
+
+    def process(
+        self,
+        image: np.ndarray,
+        config: PipelineConfig | None = None,
+        output_path: str = "outputs/result.svg",
+    ) -> dict:
+        if config is None:
+            config = PipelineConfig()
+
+        config.apply_quality()
+        config.apply_difficulty()
+
+        if config.save_debug:
+            self._save_debug("00_original_input", image, config.debug_dir)
+
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+
+        if config.content_type == ContentType.AUTO:
+            config.content_type = self._detect_content_type(image)
+            if config.line_style == LineArtStyle.AUTO:
+                style_map = {
+                    ContentType.ANIME: LineArtStyle.MANGA,
+                    ContentType.ILLUSTRATION: LineArtStyle.INFORMATIVE,
+                    ContentType.PORTRAIT: LineArtStyle.FUSED,
+                    ContentType.LANDSCAPE: LineArtStyle.FUSED,
+                    ContentType.PHOTO: LineArtStyle.FUSED,
+                }
+                config.line_style = style_map.get(config.content_type, LineArtStyle.FUSED)
+
+        print(f"  [Pipeline] Detected content type: {config.content_type.value}")
+        if config.density == "auto":
+            config.density = self._estimate_density(image)
+        print(f"  [Pipeline] Estimated density: {config.density}")
+
+        if config.k_colors is None:
+            config.k_colors = estimate_k(image)
+        print(f"  [Pipeline] Target colors: {config.k_colors} (Spatial: {config.spatial_weight})")
+
+        if (
+            config.upscale_if_small
+            and self.super_res.available
+            and self.super_res.should_upscale(image)
+        ):
+            print("  [Pipeline] Upscaling small image...")
+            image = self.super_res.upscale(image)
+            if config.save_debug:
+                self._save_debug("01_upscaled", image, config.debug_dir)
+
+        h, w = image.shape[:2]
+        if max(h, w) > config.max_dimension:
+            print(f"  [Pipeline] Resizing to {config.max_dimension}px...")
+            scale = config.max_dimension / max(h, w)
+            image = cv2.resize(image, (int(w * scale), int(h * scale)), interpolation=cv2.INTER_AREA)
+
+        original_for_colors = image.copy()
+
+        fg_mask = None
+        if config.remove_background and self.bg_remover.available:
+            print("  [Pipeline] Removing background...")
+            image, fg_mask = self.bg_remover.remove(image)
+            if config.save_debug:
+                self._save_debug("02_bg_removed", image, config.debug_dir)
+
+        line_input = image.copy()
+        if config.density == "dense":
+            line_input = cv2.bilateralFilter(line_input, d=15, sigmaColor=100, sigmaSpace=100)
+
+        print("  [Pipeline] Extracting line art...")
+        line_art = self.line_art.extract(
+            line_input,
+            style=config.line_style,
+            density=config.density,
+            bridge_gaps=config.bridge_gaps,
+        )
+
+        if config.save_debug:
+            self._save_debug("03_line_art", line_art, config.debug_dir)
+
+        if config.use_sam and self.sam.available:
+            try:
+                print(f"  [Pipeline] Segmenting with SAM (Expert Detail)...")
+                label_map, palette = self.hybrid_seg.segment(
+                    original_for_colors, 
+                    k_colors=config.k_colors,
+                    spatial_weight=config.spatial_weight
+                )
+            except Exception as e:
+                import traceback
+                print(f"  [Pipeline] ✗ SAM failed dramatically:")
+                traceback.print_exc()
+                print(f"  [Pipeline] Falling back to K-Means quantization...")
+                _, palette, label_map = quantize_colors(
+                    original_for_colors, 
+                    k_colors=config.k_colors,
+                    spatial_weight=config.spatial_weight
+                )
+        else:
+            _, palette, label_map = quantize_colors(
+                original_for_colors, 
+                k_colors=config.k_colors,
+                spatial_weight=config.spatial_weight
+            )
+
+        if label_map is None:
+             _, palette, label_map = quantize_colors(
+                 original_for_colors, 
+                 k_colors=config.k_colors,
+                 spatial_weight=config.spatial_weight
+             )
+
+        if config.save_debug:
+            debug_q = palette[np.clip(label_map, 0, len(palette) - 1)]
+            self._save_debug("04_segmented", debug_q.reshape(image.shape), config.debug_dir)
+
+        if (
+            config.detect_faces
+            and config.content_type == ContentType.PORTRAIT
+            and self.face_parser.available
+        ):
+            print("  [Pipeline] Parsing facial features...")
+            face_map = self.face_parser.parse(original_for_colors)
+            if face_map is not None:
+                faces = self.face_parser.detect_faces(original_for_colors)
+                bbox = faces[0] if faces else None
+                label_map = self.face_parser.merge_with_label_map(face_map, label_map, face_bbox=bbox)
+                max_lbl = label_map.max() + 1
+                if max_lbl > len(palette):
+                    extra = np.zeros((max_lbl - len(palette), 3), dtype=np.uint8)
+                    for idx in range(len(palette), max_lbl):
+                        mask = label_map == idx
+                        if np.any(mask):
+                            extra[idx - len(palette)] = np.median(original_for_colors[mask], axis=0).astype(np.uint8)
+                    palette = np.vstack([palette, extra])
+                if config.save_debug:
+                    vis_labels = (label_map * 15 % 255).astype(np.uint8)
+                    self._save_debug("05_face_parsed", vis_labels, config.debug_dir)
+
+        print("  [Pipeline] Merging line art and regions...")
+        merged = merge_line_art_with_regions(label_map, line_art, -1)
+        
+        # Safety check: if line art wiped out >80% of regions, skip it
+        n_orig = len(np.unique(label_map))
+        n_merged = len(np.unique(merged[merged >= 0]))
+        if n_merged < n_orig * 0.2 and n_orig > 5:
+            print(f"  [Pipeline] ⚠ Line art merge lost too much detail ({n_merged}/{n_orig}). Skipping lines for better detail.")
+            merged = label_map.copy()
+
+        # Save merged final (after fallback)
+        if config.save_debug:
+            vis_merged = palette[np.clip(merged, 0, len(palette) - 1)]
+            vis_merged = vis_merged.reshape(image.shape)
+            vis_merged[merged == -1] = [255, 255, 255]
+            self._save_debug("06_merged_final", vis_merged, config.debug_dir)
+
+        # Adaptive min area for small images
+        effective_min_area = config.min_region_area
+        img_size = max(image.shape[:2])
+        if img_size < 512:
+            effective_min_area = min(effective_min_area, 50)
+            print(f"  [Pipeline] Small image detected, reducing min_area to {effective_min_area}")
+
+        print(f"  [Pipeline] Cleaning regions (min_area={effective_min_area})...")
+        cleaned = merge_small_regions_into_neighbors(merged, min_area=effective_min_area, palette=palette)
+
+        # ── FILL GAPS (New) ──
+        print("  [Pipeline] Smoothing map and filling internal gaps...")
+        cleaned = smooth_label_map(cleaned)
+
+        if fg_mask is not None:
+            # Re-apply background mask after smoothing if needed
+            cleaned[fg_mask == 0] = -1
+
+        if config.save_debug:
+            debug_c = palette[np.clip(cleaned, 0, len(palette) - 1)]
+            debug_c = debug_c.reshape(image.shape)
+            debug_c[cleaned == -1] = [255, 255, 255]
+            self._save_debug("07_cleaned_final", debug_c, config.debug_dir)
+
+        depth_map = None
+        difficulty_layers = None
+        coloring_order = None
+        region_info = None
+
+        if config.use_depth and self.depth.available:
+            print("  [Pipeline] Calculating depth and difficulty...")
+            try:
+                depth_map = self.depth.estimate(original_for_colors)
+                difficulty_layers = self.depth.assign_difficulty_layers(depth_map, cleaned, n_layers=config.depth_layers)
+                coloring_order = self.depth.create_ordering(depth_map, cleaned)
+                region_info = compute_region_difficulty(cleaned, palette, depth_map, config.depth_layers)
+                if config.save_debug:
+                    depth_vis = (depth_map * 255).astype(np.uint8)
+                    depth_vis = cv2.applyColorMap(depth_vis, cv2.COLORMAP_VIRIDIS)
+                    self._save_debug("06_depth", depth_vis, config.debug_dir)
+            except Exception as e:
+                print(f"Depth estimation failed: {e}")
+
+        # ── GENERATE SVGS ──
+        # 1. Colored SVG
+        svg_colored = generate_svg(
+            label_map=cleaned,
+            palette=palette,
+            output_path=output_path,
+            min_area=config.min_region_area // 2,
+            difficulty_layers=difficulty_layers,
+            fill_color=True,
+        )
+
+        # 2. Outline SVG
+        outline_path = output_path.replace(".svg", "_outline.svg")
+        svg_outline = generate_svg(
+            label_map=cleaned,
+            palette=palette,
+            output_path=outline_path,
+            min_area=config.min_region_area // 2,
+            difficulty_layers=difficulty_layers,
+            fill_color=False,
+        )
+
+        num_regions = svg_colored.count('class="fillable"')
+
+        # ── ADJACENCY (New) ──
+        print("  [Pipeline] Calculating region adjacency...")
+        adj_matrix = get_adjacency_matrix(cleaned)
+
+        result = {
+            "svg_string": svg_colored,
+            "svg_outline_string": svg_outline,
+            "svg_path": output_path,
+            "svg_outline_path": outline_path,
+            "palette": [
+                {
+                    "index": i + 1,
+                    "hex": f"#{int(c[2]):02X}{int(c[1]):02X}{int(c[0]):02X}",
+                }
+                for i, c in enumerate(palette)
+            ],
+            "num_regions": int(num_regions),
+            "adjacency_matrix": [[int(a), int(b)] for a, b in adj_matrix],
+            "k_colors_used": int(len(palette)),
+            "density_used": str(config.density),
+            "content_type": str(config.content_type.value),
+            "models_used": self._get_models_used(config),
+        }
+
+        if coloring_order:
+            result["suggested_order"] = [int(x) for x in coloring_order]
+        if difficulty_layers:
+            result["difficulty_layers"] = {int(k): int(v) for k, v in difficulty_layers.items()}
+        if region_info:
+            result["regions"] = [
+                {
+                    "label": int(r.label),
+                    "area": int(r.area),
+                    "color": str(r.color_hex),
+                    "difficulty_layer": int(r.difficulty_layer),
+                    "suggested_order": int(r.suggested_order),
+                    "centroid": [int(r.centroid[0]), int(r.centroid[1])],
+                    "seed_point": [int(r.seed_point[0]), int(r.seed_point[1])],
+                }
+                for r in region_info
+            ]
+
+        return result
+
+    def _get_models_used(self, config: PipelineConfig) -> list[str]:
+        used = []
+        if config.line_style in (LineArtStyle.FUSED, LineArtStyle.INFORMATIVE):
+            if self.registry.available("informative_drawings"):
+                used.append("informative-drawings")
+        if config.line_style in (LineArtStyle.FUSED, LineArtStyle.ANYLINE):
+            if self.registry.available("anyline"):
+                used.append("anyline")
+        if config.line_style == LineArtStyle.MANGA:
+            if self.registry.available("manga_line"):
+                used.append("manga-line")
+        if config.use_sam and self.sam.available:
+            used.append("sam2")
+        if config.use_depth and self.depth.available:
+            used.append("depth-anything-v2")
+        if config.content_type == ContentType.PORTRAIT and self.face_parser.available:
+            used.append("face-parser")
+        return used
+
+    async def generate_from_prompt(
+        self,
+        prompt: str,
+        style: str = "coloring_book",
+        config: PipelineConfig | None = None,
+        output_path: str = "outputs/generated.svg",
+    ) -> dict | None:
+        if not self.generator.available:
+            return None
+        image = await self.generator.generate_from_prompt(prompt, style)
+        if image is None:
+            return None
+        result = self.process(image, config, output_path)
+        result["source"] = "generated"
+        result["prompt"] = prompt
+        return result

app/processing/difficulty.py

@@ -0,0 +1,89 @@
+import numpy as np
+from dataclasses import dataclass
+from app.processing.utils import get_pole_of_inaccessibility
+
+
+@dataclass
+class RegionInfo:
+    label: int
+    area: int
+    avg_depth: float
+    color_hex: str
+    difficulty_layer: int
+    suggested_order: int
+    centroid: tuple[int, int]
+    seed_point: tuple[int, int]
+
+
+def compute_region_difficulty(
+    label_map: np.ndarray,
+    palette: np.ndarray,
+    depth_map: np.ndarray | None = None,
+    n_layers: int = 3,
+) -> list[RegionInfo]:
+    import cv2
+
+    unique_labels = np.unique(label_map)
+    unique_labels = unique_labels[unique_labels >= 0]
+
+    h, w = label_map.shape
+    total_pixels = h * w
+
+    regions = []
+    for lbl in unique_labels:
+        mask = (label_map == lbl).astype(np.uint8)
+        area = np.count_nonzero(mask)
+
+        if area < 10:
+            continue
+
+        moments = cv2.moments(mask)
+        if moments["m00"] > 0:
+            cx = int(moments["m10"] / moments["m00"])
+            cy = int(moments["m01"] / moments["m00"])
+        else:
+            cy_coords, cx_coords = np.where(mask > 0)
+            cy, cx = int(np.mean(cy_coords)), int(np.mean(cx_coords))
+
+        if depth_map is not None:
+            avg_depth = float(depth_map[mask > 0].mean())
+        else:
+            avg_depth = 0.5
+
+        size_score = 1.0 - min(area / (total_pixels * 0.1), 1.0)
+
+        contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        if contours:
+            perim = cv2.arcLength(contours[0], True)
+            circularity = (4 * np.pi * area) / max(perim * perim, 1)
+            complexity_score = 1.0 - min(circularity, 1.0)
+        else:
+            complexity_score = 0.5
+
+        difficulty = 0.4 * avg_depth + 0.3 * size_score + 0.3 * complexity_score
+        layer = int(difficulty * n_layers)
+        layer = min(layer, n_layers - 1)
+
+        color_idx = min(int(lbl), len(palette) - 1)
+        c = palette[color_idx]
+        hex_color = f"#{int(c[2]):02X}{int(c[1]):02X}{int(c[0]):02X}"
+
+        # Calculate seed_point (Pole of Inaccessibility)
+        seed_x, seed_y = get_pole_of_inaccessibility(mask)
+
+        regions.append(RegionInfo(
+            label=int(lbl),
+            area=area,
+            avg_depth=avg_depth,
+            color_hex=hex_color,
+            difficulty_layer=layer,
+            suggested_order=0,
+            centroid=(cx, cy),
+            seed_point=(seed_x, seed_y),
+        ))
+
+    regions.sort(key=lambda r: (r.difficulty_layer, -r.area))
+    for i, r in enumerate(regions):
+        r.suggested_order = i + 1
+
+    return regions

app/processing/quantizer.py

@@ -0,0 +1,189 @@
+"""
+Enhanced color quantization and region management.
+"""
+
+import cv2
+import numpy as np
+from sklearn.cluster import MiniBatchKMeans
+from collections import Counter
+
+
+def estimate_k(image: np.ndarray, min_k: int = 6, max_k: int = 24) -> int:
+    """Estimate optimal number of colors based on image complexity."""
+    small = cv2.resize(image, (128, 128))
+    hsv = cv2.cvtColor(small, cv2.COLOR_BGR2HSV)
+    hist = cv2.calcHist([hsv], [0, 1], None, [30, 30], [0, 180, 0, 256])
+    hist = hist.flatten()
+    hist = hist[hist > 0]
+    hist = hist / hist.sum()
+    entropy = -np.sum(hist * np.log2(hist))
+    k = int(np.interp(entropy, [2.0, 8.0], [min_k, max_k]))
+    return np.clip(k, min_k, max_k)
+
+
+def quantize_colors(
+    image: np.ndarray,
+    k_colors: int = 12,
+    sample_fraction: float = 0.25,
+    use_lab: bool = True,
+    spatial_weight: float = 0.0,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    h, w = image.shape[:2]
+    if use_lab:
+        working_img = cv2.cvtColor(image, cv2.COLOR_BGR2LAB).astype(np.float32)
+    else:
+        working_img = image.astype(np.float32)
+    pixels = working_img.reshape(-1, 3)
+    if spatial_weight > 0:
+        yy, xx = np.mgrid[0:h, 0:w]
+        coords = np.column_stack([
+            xx.ravel().astype(np.float32) / w * spatial_weight * 100,
+            yy.ravel().astype(np.float32) / h * spatial_weight * 100,
+        ])
+        features = np.hstack([pixels, coords])
+    else:
+        features = pixels
+    n_pixels = features.shape[0]
+    n_samples = max(int(n_pixels * sample_fraction), k_colors * 200)
+    rng = np.random.default_rng(42)
+    if n_samples < n_pixels:
+        indices = rng.choice(n_pixels, n_samples, replace=False)
+        sample = features[indices]
+    else:
+        sample = features
+    kmeans = MiniBatchKMeans(
+        n_clusters=k_colors,
+        random_state=42,
+        batch_size=2048,
+        n_init=5,
+        max_iter=300,
+    )
+    kmeans.fit(sample)
+    labels = kmeans.predict(features)
+    label_map = labels.reshape(h, w)
+    centers = kmeans.cluster_centers_[:, :3]
+    if use_lab:
+        centers_uint8 = np.clip(centers, 0, 255).astype(np.uint8)
+        centers_lab = centers_uint8.reshape(-1, 1, 3)
+        palette = cv2.cvtColor(centers_lab, cv2.COLOR_LAB2BGR).reshape(-1, 3)
+    else:
+        palette = np.clip(centers, 0, 255).astype(np.uint8)
+    quantized_img = palette[labels].reshape(h, w, 3)
+    return quantized_img, palette, label_map
+
+
+def merge_line_art_with_regions(
+    label_map: np.ndarray,
+    line_art_binary: np.ndarray,
+    line_color_index: int = -1,
+) -> np.ndarray:
+    """Subtract AI line art from color regions."""
+    line_mask = line_art_binary == 0
+    merged = label_map.copy()
+    merged[line_mask] = line_color_index
+    return merged
+
+
+def merge_small_regions_into_neighbors(
+    label_map: np.ndarray,
+    min_area: int = 200,
+    max_passes: int = 10,
+    boundary_index: int = -1,
+    palette: np.ndarray | None = None,
+) -> np.ndarray:
+    result = label_map.copy()
+    h, w = result.shape
+    
+    # Pre-calculate brightness if palette is provided
+    brightness_map = None
+    if palette is not None:
+        brightness_map = 0.299 * palette[:, 2] + 0.587 * palette[:, 1] + 0.114 * palette[:, 0]
+
+    for pass_num in range(5): # Reduced passes for speed
+        changed_count = 0
+        unique_labels = np.unique(result)
+        unique_labels = unique_labels[unique_labels != boundary_index]
+        
+        for lbl in unique_labels:
+            mask = (result == lbl).astype(np.uint8)
+            num_cc, cc_labels, stats, _ = cv2.connectedComponentsWithStats(
+                mask, connectivity=8
+            )
+            
+            # Special protection for dark regions (like eyes)
+            effective_min = min_area
+            if brightness_map is not None and lbl < len(brightness_map):
+                if brightness_map[lbl] < 60: # Very dark
+                    effective_min = max(20, min_area // 4)
+            
+            for cc_id in range(1, num_cc):
+                area = stats[cc_id, cv2.CC_STAT_AREA]
+                
+                # NARROWNESS CHECK: Clutter reduction (Optimized)
+                is_narrow = False
+                if area < 5: # Tiny is always "narrow" enough to merge
+                    is_narrow = True
+                elif area < effective_min * 2: # Only check narrowness for candidate regions
+                    x, y, bw, bh = stats[cc_id, cv2.CC_STAT_LEFT], stats[cc_id, cv2.CC_STAT_TOP], \
+                                stats[cc_id, cv2.CC_STAT_WIDTH], stats[cc_id, cv2.CC_STAT_HEIGHT]
+                    
+                    # Heuristic: If bounding box is very thin, or area is small compared to box
+                    if min(bw, bh) < 3: 
+                        is_narrow = True
+                    elif area / (bw * bh) < 0.2: # Very sparse/sliver-like
+                        # Only then do the expensive check
+                        cc_mask = (cc_labels == cc_id).astype(np.uint8)
+                        eroded = cv2.erode(cc_mask, np.ones((3, 3), np.uint8))
+                        if np.count_nonzero(eroded) / area < 0.1:
+                            is_narrow = True
+
+                if area >= effective_min and not is_narrow:
+                    continue
+                    
+                x, y, bw, bh = stats[cc_id, cv2.CC_STAT_LEFT], stats[cc_id, cv2.CC_STAT_TOP], \
+                              stats[cc_id, cv2.CC_STAT_WIDTH], stats[cc_id, cv2.CC_STAT_HEIGHT]
+                
+                y1, y2 = max(0, y - 2), min(h, y + bh + 2)
+                x1, x2 = max(0, x - 2), min(w, x + bw + 2)
+                
+                local_cc_labels = cc_labels[y1:y2, x1:x2]
+                local_result = result[y1:y2, x1:x2]
+                
+                cc_mask_local = (local_cc_labels == cc_id).astype(np.uint8)
+                dilated = cv2.dilate(cc_mask_local, np.ones((3, 3), np.uint8)) # smaller kernel
+                
+                neighbor_mask = (dilated > 0) & (local_cc_labels != cc_id)
+                neighbor_labels = local_result[neighbor_mask]
+                neighbor_labels = neighbor_labels[neighbor_labels != boundary_index]
+                neighbor_labels = neighbor_labels[neighbor_labels != lbl]
+                
+                if neighbor_labels.size == 0:
+                    continue
+                    
+                most_common = Counter(neighbor_labels).most_common(1)[0][0]
+                result[y1:y2, x1:x2][local_cc_labels == cc_id] = most_common
+                changed_count += 1
+                
+        if changed_count == 0:
+            break
+    return result
+def smooth_label_map(label_map: np.ndarray, boundary_index: int = -1) -> np.ndarray:
+    """Fill internal gaps (-1) using nearest neighbor approach."""
+    from scipy import ndimage
+    
+    unlabeled = label_map == boundary_index
+    labeled = label_map != boundary_index
+    
+    if not np.any(unlabeled) or not np.any(labeled):
+        return label_map
+        
+    _, nearest_indices = ndimage.distance_transform_edt(
+        unlabeled, return_distances=True, return_indices=True
+    )
+    
+    result = label_map.copy()
+    result[unlabeled] = label_map[
+        nearest_indices[0][unlabeled],
+        nearest_indices[1][unlabeled]
+    ]
+    return result

app/processing/utils.py

@@ -0,0 +1,377 @@
+"""
+Enhanced image processing utilities.
+
+Changes:
+ - Multi-pass directional closing (horizontal, vertical, diagonal)
+ - Endpoint-aware gap bridging
+ - Hysteresis thresholding for cleaner lines
+ - Adaptive kernel sizing based on image resolution
+ - Connected component noise removal
+"""
+
+import cv2
+import numpy as np
+
+
+def adaptive_kernel_size(image: np.ndarray, base: int = 3) -> int:
+    """
+    Scale kernel size based on image resolution.
+    Dense/large images need bigger kernels to close proportional gaps.
+    """
+    h, w = image.shape[:2]
+    scale = max(h, w) / 512.0
+    k = max(base, int(base * scale))
+    # Ensure odd
+    return k if k % 2 == 1 else k + 1
+
+
+def multi_scale_close(
+    binary_img: np.ndarray,
+    kernel_sizes: list[int] | None = None,
+    iterations_per_scale: int = 1,
+) -> np.ndarray:
+    """
+    Progressive morphological closing at multiple kernel sizes.
+
+    Small kernels fix tiny gaps without distorting shapes.
+    Larger kernels catch wider breaks that small ones miss.
+    Running them in sequence (small → large) gives best results.
+
+    Args:
+        binary_img:           Single-channel uint8 (0 or 255).
+        kernel_sizes:         List of odd kernel sizes, ascending.
+        iterations_per_scale: Closing iterations per kernel size.
+
+    Returns:
+        Closed binary image.
+    """
+    if kernel_sizes is None:
+        base = adaptive_kernel_size(binary_img, base=3)
+        kernel_sizes = [base, base + 2, base + 4]
+
+    result = binary_img.copy()
+    for ks in kernel_sizes:
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (ks, ks))
+        result = cv2.morphologyEx(
+            result, cv2.MORPH_CLOSE, kernel, iterations=iterations_per_scale
+        )
+    return result
+
+
+def directional_close(
+    binary_img: np.ndarray,
+    length: int = 7,
+    iterations: int = 1,
+) -> np.ndarray:
+    """
+    Close gaps in all four major orientations separately, then combine.
+
+    A horizontal gap won't be caught by a square kernel efficiently,
+    but a horizontal line kernel seals it perfectly. We run four
+    orientations and merge results.
+
+    Args:
+        binary_img: Single-channel uint8 (0 or 255).
+        length:     Length of the directional structuring element.
+        iterations: Closing iterations per direction.
+
+    Returns:
+        Binary image with directional gaps sealed.
+    """
+    length = max(3, length)
+    if length % 2 == 0:
+        length += 1
+
+    results = []
+
+    # Horizontal
+    k_h = cv2.getStructuringElement(cv2.MORPH_RECT, (length, 1))
+    results.append(
+        cv2.morphologyEx(binary_img, cv2.MORPH_CLOSE, k_h, iterations=iterations)
+    )
+
+    # Vertical
+    k_v = cv2.getStructuringElement(cv2.MORPH_RECT, (1, length))
+    results.append(
+        cv2.morphologyEx(binary_img, cv2.MORPH_CLOSE, k_v, iterations=iterations)
+    )
+
+    # Diagonal 45°
+    k_d1 = np.eye(length, dtype=np.uint8)
+    results.append(
+        cv2.morphologyEx(binary_img, cv2.MORPH_CLOSE, k_d1, iterations=iterations)
+    )
+
+    # Diagonal 135°
+    k_d2 = np.fliplr(np.eye(length, dtype=np.uint8))
+    results.append(
+        cv2.morphologyEx(binary_img, cv2.MORPH_CLOSE, k_d2, iterations=iterations)
+    )
+
+    # Merge: a pixel is closed if ANY direction closed it
+    # Lines are black (0), so we take the minimum — if any pass
+    # turned a gap pixel black, keep it black
+    merged = results[0]
+    for r in results[1:]:
+        merged = cv2.min(merged, r)
+
+    return merged
+
+
+def bridge_endpoints(
+    binary_img: np.ndarray, search_radius: int = 15
+) -> np.ndarray:
+    """
+    Find line endpoints and bridge them to nearby line pixels.
+    Optimized for performance by avoiding full skeletonization fallback.
+    """
+    # Work with inverted image (lines = white = 255)
+    inverted = cv2.bitwise_not(binary_img)
+    
+    # 1. Thinning / Skeletonization
+    if hasattr(cv2, 'ximgproc'):
+        skeleton = cv2.ximgproc.thinning(inverted)
+    else:
+        # Fast "thinned" version for endpoint detection
+        # Just use a simple morphological skeleton for 2 iterations
+        element = cv2.getStructuringElement(cv2.MORPH_CROSS, (3, 3))
+        skeleton = cv2.erode(inverted, element, iterations=1)
+        # Difference between original and eroded roughly highlights endpoints
+        skeleton = cv2.absdiff(inverted, cv2.dilate(skeleton, element))
+
+    # 2. Endpoint detection via neighbor count (3x3 window)
+    # A pixel is likely an endpoint if it has exactly 1 neighbor in 3x3
+    kernel = np.array([[1, 1, 1], [1, 10, 1], [1, 1, 1]], dtype=np.uint8)
+    neighbor_counts = cv2.filter2D(skeleton, -1, kernel)
+    
+    # Value 11 means: self (10) + 1 neighbor (1)
+    endpoints = (neighbor_counts == 11).astype(np.uint8) * 255
+    
+    ep_coords = np.column_stack(np.where(endpoints > 0))
+    result = binary_img.copy()
+
+    if len(ep_coords) < 2:
+        return result
+
+    # Limit endpoints to process if there are thousands
+    if len(ep_coords) > 1000:
+        indices = np.random.choice(len(ep_coords), 1000, replace=False)
+        ep_coords = ep_coords[indices]
+
+    # Pre-calculate search windows to be faster
+    h, w = inverted.shape
+    for y, x in ep_coords:
+        y1, y2 = max(0, y - search_radius), min(h, y + search_radius + 1)
+        x1, x2 = max(0, x - search_radius), min(w, x + search_radius + 1)
+
+        window = inverted[y1:y2, x1:x2]
+        
+        # Look for the nearest point that isn't the current pixel or immediate neighbor
+        # Use distance transform for faster "nearest point" lookup in window
+        local_y, local_x = y - y1, x - x1
+        
+        # Find points in window
+        pts = np.column_stack(np.where(window > 128))
+        if len(pts) < 2: continue # Only self found
+        
+        # Distances to (local_y, local_x)
+        dists_sq = (pts[:, 0] - local_y)**2 + (pts[:, 1] - local_x)**2
+        
+        # Filter out points too close (neighbors)
+        valid = dists_sq > 16 # sqrt(16) = 4 pixels away
+        if not np.any(valid): continue
+        
+        nearest_idx = np.argmin(dists_sq[valid])
+        target_y, target_x = pts[valid][nearest_idx]
+        
+        if dists_sq[valid][nearest_idx] <= search_radius**2:
+            cv2.line(result, (x, y), (target_x + x1, target_y + y1), 0, 1)
+
+    return result
+
+
+def hysteresis_threshold(
+    grayscale: np.ndarray, low: int = 80, high: int = 160
+) -> np.ndarray:
+    """
+    Dual-threshold binarization (like Canny's hysteresis).
+
+    Strong edges (above high) are always kept.
+    Weak edges (between low and high) are kept only if connected
+    to a strong edge. This preserves faint but important lines
+    while rejecting isolated noise.
+
+    Args:
+        grayscale: Single-channel uint8 image.
+        low:       Lower threshold.
+        high:      Upper threshold.
+
+    Returns:
+        Binary uint8 image.
+    """
+    strong = grayscale >= high
+    weak = (grayscale >= low) & (grayscale < high)
+
+    # Use connected components: weak pixels touching strong ones survive
+    result = np.zeros_like(grayscale)
+    result[strong] = 255
+
+    # Dilate strong regions and intersect with weak
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
+    for _ in range(5):  # Propagate connectivity
+        dilated = cv2.dilate(result, kernel)
+        connected_weak = (dilated > 0) & weak
+        result[connected_weak] = 255
+        if not np.any(connected_weak):
+            break
+
+    return result
+
+
+def binarize(grayscale: np.ndarray, threshold: int = 128) -> np.ndarray:
+    """Simple global threshold."""
+    _, binary = cv2.threshold(grayscale, threshold, 255, cv2.THRESH_BINARY)
+    return binary
+
+
+def adaptive_binarize(grayscale: np.ndarray, block_size: int = 21) -> np.ndarray:
+    """
+    Adaptive thresholding handles uneven lighting / AI output intensity.
+    Different parts of the image get different threshold values.
+    """
+    if block_size % 2 == 0:
+        block_size += 1
+    return cv2.adaptiveThreshold(
+        grayscale, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+        cv2.THRESH_BINARY, block_size, 5
+    )
+
+
+def remove_small_regions(
+    mask: np.ndarray, min_area: int = 100
+) -> np.ndarray:
+    """Remove noise blobs below min_area."""
+    contours, _ = cv2.findContours(
+        mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+    )
+    cleaned = mask.copy()
+    for cnt in contours:
+        if cv2.contourArea(cnt) < min_area:
+            cv2.drawContours(cleaned, [cnt], -1, 0, cv2.FILLED)
+    return cleaned
+
+
+def remove_small_components(
+    mask: np.ndarray, min_area: int = 100
+) -> np.ndarray:
+    """
+    Connected-component based cleanup. Faster and more accurate
+    than contour-based removal for dense images with many tiny blobs.
+    """
+    num_labels, labels, stats, _ = cv2.connectedComponentsWithStats(
+        mask, connectivity=8
+    )
+    cleaned = np.zeros_like(mask)
+    for label_id in range(1, num_labels):
+        area = stats[label_id, cv2.CC_STAT_AREA]
+        if area >= min_area:
+            cleaned[labels == label_id] = 255
+    return cleaned
+
+
+def skeletonize(binary_img: np.ndarray) -> np.ndarray:
+    """
+    Thins lines to 1-pixel width. Optimized for speed.
+    Expects: lines = 255, background = 0.
+    """
+    if hasattr(cv2, "ximgproc"):
+        return cv2.ximgproc.thinning(binary_img)
+    
+    # Fast iteration-limited morphological thinning
+    size = np.size(binary_img)
+    skel = np.zeros(binary_img.shape, np.uint8)
+    element = cv2.getStructuringElement(cv2.MORPH_CROSS, (3, 3))
+    
+    img = binary_img.copy()
+    # 32 iterations is typically enough for 1024px lines
+    for _ in range(32):
+        if cv2.countNonZero(img) == 0:
+            break
+        eroded = cv2.erode(img, element)
+        temp = cv2.dilate(eroded, element)
+        temp = cv2.subtract(img, temp)
+        skel = cv2.bitwise_or(skel, temp)
+        img = eroded.copy()
+ 
+    return skel
+
+
+def declutter_lines(
+    binary_img: np.ndarray, 
+    merge_radius: int = 1, # Default smaller
+    thin_out: bool = True
+) -> np.ndarray:
+    """
+    Merge lines that are very close and then thin them back down.
+    Expects: lines = 0, background = 255.
+    """
+    # 1. Work with inverted image (lines = 255)
+    inverted = cv2.bitwise_not(binary_img)
+    
+    # 2. Dilation to merge close boundaries
+    if merge_radius > 0:
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (merge_radius * 2 + 1, merge_radius * 2 + 1))
+        inverted = cv2.dilate(inverted, kernel, iterations=1)
+        
+    # 3. Skeletonize to restore thin lines
+    if thin_out:
+        inverted = skeletonize(inverted)
+        
+    # 4. Invert back
+    return cv2.bitwise_not(inverted)
+
+
+def get_pole_of_inaccessibility(mask: np.ndarray) -> tuple[int, int]:
+    """
+    Find the point farthest from any boundary in a binary mask.
+    Perfect for label placement to avoid touching borders.
+    """
+    dist = cv2.distanceTransform(mask, cv2.DIST_L2, 5)
+    _, max_val, _, max_loc = cv2.minMaxLoc(dist)
+    return max_loc # (x, y)
+
+
+def get_adjacency_matrix(label_map: np.ndarray) -> list[tuple[int, int]]:
+    """
+    Calculate which regions are neighbors.
+    Uses 4-way connectivity pixel check for efficiency.
+    Returns list of (label_a, label_b) pairs where label_a < label_b.
+    """
+    h, w = label_map.shape
+    adj = set()
+
+    # Horizontal adjacencies
+    # [0, 0, 1, 1] -> neighbors are (0, 1)
+    # Use array slicing to check left/right neighbors
+    left = label_map[:, :-1]
+    right = label_map[:, 1:]
+    mask = (left != right) & (left >= 0) & (right >= 0)
+    
+    # Extract pairs
+    pairs = np.column_stack((left[mask], right[mask]))
+    # Sort each pair to ensure (a, b) where a < b
+    pairs.sort(axis=1)
+    for p in np.unique(pairs, axis=0):
+        adj.add(tuple(p))
+
+    # Vertical adjacencies
+    top = label_map[:-1, :]
+    bottom = label_map[1:, :]
+    mask = (top != bottom) & (top >= 0) & (bottom >= 0)
+    
+    pairs = np.column_stack((top[mask], bottom[mask]))
+    pairs.sort(axis=1)
+    for p in np.unique(pairs, axis=0):
+        adj.add(tuple(p))
+
+    return sorted(list(adj))

app/processing/vectorizer.py

@@ -0,0 +1,194 @@
+"""
+Enhanced SVG vectorizer with difficulty layer support.
+"""
+
+import cv2
+import numpy as np
+import svgwrite
+from app.processing.utils import get_pole_of_inaccessibility
+
+
+def _contour_to_svg_path(contour: np.ndarray) -> str:
+    points = contour.squeeze()
+    if points.ndim == 1:
+        return ""
+    parts = [f"M {points[0][0]},{points[0][1]}"]
+    for pt in points[1:]:
+        parts.append(f"L {pt[0]},{pt[1]}")
+    parts.append("Z")
+    return " ".join(parts)
+
+
+def _bgr_to_hex(bgr: np.ndarray) -> str:
+    b, g, r = int(bgr[0]), int(bgr[1]), int(bgr[2])
+    return f"#{r:02X}{g:02X}{b:02X}"
+
+
+def generate_svg(
+    label_map: np.ndarray,
+    palette: np.ndarray,
+    output_path: str = "output.svg",
+    min_area: int = 100,
+    simplify_epsilon_ratio: float = 0.002,
+    stroke_width: float = 1.0,
+    font_size: int = 10,
+    boundary_index: int = -1,
+    difficulty_layers: dict[int, int] | None = None,
+    fill_color: bool = True,
+) -> str:
+    """Generate color-by-number SVG with optional color filling."""
+    try:
+        h, w = label_map.shape[:2]
+        n_colors = len(palette)
+        
+        # Ensure output_path is a string
+        output_path = str(output_path)
+        
+        # Debug info
+        unique_labels = np.unique(label_map)
+        print(f"  [Vectorizer] Unique labels in map: {len(unique_labels)}")
+        print(f"  [Vectorizer] Dimensions: {w}x{h}, Target: {output_path}")
+
+        dwg = svgwrite.Drawing(
+            output_path,
+            size=(f"{w}px", f"{h}px"),
+            profile='full',
+            debug=False
+        )
+        dwg.viewbox(0, 0, w, h)
+
+        # Background
+        dwg.add(dwg.rect(insert=(0, 0), size=(w, h), fill="white"))
+
+        # Create layer groups
+        groups = {}
+        if difficulty_layers:
+            layers = list(difficulty_layers.values())
+            n_layers = max(layers) + 1 if layers else 1
+            for i in range(n_layers):
+                name = ["easy", "medium", "hard", "expert"][min(i, 3)]
+                g = dwg.g(id=f"layer_{name}")
+                groups[i] = g
+        else:
+            groups[0] = dwg.g(id="regions")
+
+        labels_group = dwg.g(id="labels")
+        region_counter = 0
+        unique_labels = np.unique(label_map)
+        print(f"  [Vectorizer] Unique labels in map: {len(unique_labels)}")
+        # Filter out boundary, but if we have only 1 label, keep it so it's not a blank page
+        if len(unique_labels) > 2:
+            valid_labels = unique_labels[unique_labels != boundary_index]
+        else:
+            # If we only have 2 colors, keep both
+            valid_labels = unique_labels
+            
+        for color_idx in valid_labels:
+            if color_idx == boundary_index:
+                hex_color = "#FFFFFF" # Draw boundary as white
+            elif color_idx < 0 or color_idx >= n_colors:
+                continue
+            else:
+                hex_color = _bgr_to_hex(palette[color_idx])
+            mask = np.zeros((h, w), dtype=np.uint8)
+            mask[label_map == color_idx] = 255
+
+            contours, hierarchy = cv2.findContours(
+                mask, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_SIMPLE
+            )
+
+            if hierarchy is None:
+                continue
+
+            hierarchy = hierarchy[0]
+            difficulty = 0
+            if difficulty_layers and int(color_idx) in difficulty_layers:
+                difficulty = difficulty_layers[int(color_idx)]
+
+            target_group = groups.get(difficulty, list(groups.values())[0])
+
+            for i, (cnt, hier) in enumerate(zip(contours, hierarchy)):
+                # Only process external contours (those with no parent in CCOMP)
+                if hier[3] != -1:
+                    continue
+                    
+                area = cv2.contourArea(cnt)
+                if area < 2: # Keep almost everything
+                    continue
+
+                epsilon = simplify_epsilon_ratio * cv2.arcLength(cnt, True)
+                approx = cv2.approxPolyDP(cnt, epsilon, True)
+
+                if len(approx) >= 3:
+                    path_d = _contour_to_svg_path(approx)
+                    
+                    # Add holes
+                    child_idx = hier[2]
+                    while child_idx != -1:
+                        hole_cnt = contours[child_idx]
+                        hole_area = cv2.contourArea(hole_cnt)
+                        if hole_area > 5: # Small holes ok
+                            hole_eps = simplify_epsilon_ratio * cv2.arcLength(hole_cnt, True)
+                            hole_approx = cv2.approxPolyDP(hole_cnt, hole_eps, True)
+                            if len(hole_approx) >= 3:
+                                path_d += " " + _contour_to_svg_path(hole_approx)
+                        child_idx = hierarchy[child_idx][0]
+
+                    region_counter += 1
+                
+                    final_fill = hex_color if fill_color else "none"
+                    if color_idx == boundary_index and not fill_color:
+                        final_fill = "none" # or white
+                    
+                    path_elem = dwg.path(
+                        d=path_d,
+                        fill=final_fill,
+                        stroke="black",
+                        stroke_width=stroke_width,
+                        fill_rule="evenodd"
+                    )
+                    path_elem.attribs['id'] = f"region_{region_counter}"
+                    path_elem.attribs['data-color'] = hex_color
+                    path_elem.attribs['data-index'] = str(int(color_idx) + 1)
+                    path_elem.attribs['class'] = "fillable"
+                    target_group.add(path_elem)
+
+                    # Add number label (Perfect center placement)
+                    cx, cy = get_pole_of_inaccessibility(mask)
+                    bgr = palette[color_idx]
+                    brightness = 0.299*bgr[2] + 0.587*bgr[1] + 0.114*bgr[0]
+                    text_color = "white" if brightness < 128 else "#333333"
+
+                    labels_group.add(dwg.text(
+                        str(int(color_idx) + 1),
+                        insert=(cx, cy),
+                        font_size=font_size,
+                        fill=text_color,
+                        text_anchor="middle",
+                        dominant_baseline="central"
+                    ))
+
+        for g in groups.values():
+            dwg.add(g)
+        dwg.add(labels_group)
+        
+        print(f"  [Vectorizer] Total regions drawn: {region_counter}")
+
+        # Palette Legend at bottom
+        legend_y = h + 10
+        swatch_h = 30
+        for i in range(n_colors):
+            x = 10 + i * (swatch_h + 10)
+            swatch_fill = _bgr_to_hex(palette[i]) if fill_color else "none"
+            dwg.add(dwg.rect(insert=(x, legend_y), size=(swatch_h, swatch_h), 
+                             fill=swatch_fill, stroke="black", stroke_width=0.5))
+            dwg.add(dwg.text(str(i+1), insert=(x + swatch_h/2, legend_y + swatch_h + 12),
+                             font_size=10, text_anchor="middle", fill="black"))
+
+        dwg.save()
+        return dwg.tostring()
+    except Exception as e:
+        print(f"  [Vectorizer] Error generating SVG: {e}")
+        import traceback
+        traceback.print_exc()
+        return f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text x="10" y="50">Error: {e}</text></svg>'

download_model.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Download the informative-drawings line-art ONNX model from HuggingFace."""
+
+from huggingface_hub import hf_hub_download
+import shutil
+from pathlib import Path
+
+
+def download_model(dest_dir: str = "models") -> str:
+    dest = Path(dest_dir)
+    dest.mkdir(exist_ok=True)
+
+    output_path = dest / "model.onnx"
+    if output_path.exists():
+        print(f"Model already exists at {output_path}")
+        return str(output_path)
+
+    print("Downloading informative-drawings-line-art-onnx...")
+    downloaded = hf_hub_download(
+        repo_id="rocca/informative-drawings-line-art-onnx",
+        filename="model.onnx",
+    )
+    shutil.copy(downloaded, output_path)
+    print(f"Model saved to {output_path}")
+    return str(output_path)
+
+
+if __name__ == "__main__":
+    download_model()

download_models.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Download all ONNX models needed for the multi-model pipeline.
+Handles split ONNX models and uses verified repositories.
+"""
+
+import shutil
+from pathlib import Path
+from huggingface_hub import hf_hub_download
+
+
+MODELS = {
+    "informative-drawings": {
+        "repo": "rocca/informative-drawings-line-art-onnx",
+        "file": "model.onnx",
+        "local": "models/informative_drawings.onnx",
+        "size_mb": 22,
+        "required": True,
+    },
+    "sam2-encoder": {
+        "repo": "onnx-community/sam2.1-hiera-small-ONNX",
+        "file": "onnx/vision_encoder.onnx",
+        "local": "models/sam2_encoder.onnx",
+        "extra_files": ["onnx/vision_encoder.onnx_data"],
+        "size_mb": 130,
+        "required": True,
+    },
+    "sam2-decoder": {
+        "repo": "onnx-community/sam2.1-hiera-small-ONNX",
+        "file": "onnx/prompt_encoder_mask_decoder.onnx",
+        "local": "models/sam2_decoder.onnx",
+        "extra_files": ["onnx/prompt_encoder_mask_decoder.onnx_data"],
+        "size_mb": 16,
+        "required": True,
+    },
+    "depth-anything-v2": {
+        "repo": "onnx-community/depth-anything-v2-small",
+        "file": "onnx/model_fp16.onnx",
+        "local": "models/depth_anything_v2.onnx",
+        "size_mb": 49,
+        "required": True,
+    },
+    "real-esrgan": {
+        "repo": "AXERA-TECH/Real-ESRGAN",
+        "file": "realesrgan-x4.onnx",
+        "local": "models/real_esrgan_x4.onnx",
+        "size_mb": 64,
+        "required": False,
+    },
+    "rmbg": {
+        "repo": "briaai/RMBG-2.0",
+        "file": "onnx/model.onnx", # Verified common path for this repo
+        "local": "models/rmbg2.onnx",
+        "size_mb": 170,
+        "required": False,
+    },
+    "face-parsing": {
+        "repo": "bluefoxcreation/Face_parsing_onnx",
+        "file": "faceparser.onnx",
+        "local": "models/face_parsing.onnx",
+        "size_mb": 52,
+        "required": False,
+    },
+}
+
+
+def download_all(required_only: bool = False):
+    """Download models from HuggingFace Hub."""
+    Path("models").mkdir(exist_ok=True)
+
+    for name, info in MODELS.items():
+        local_path = Path(info["local"])
+
+        if local_path.exists():
+            # For split models, ensure extra files exist even if .onnx exists
+            if "extra_files" in info:
+                all_extras_exist = True
+                for extra in info["extra_files"]:
+                    if not (Path("models") / Path(extra).name).exists():
+                        all_extras_exist = False
+                        break
+                if all_extras_exist:
+                    print(f"  ✓ {name} already exists")
+                    continue
+            elif local_path.stat().st_size > 1024 * 1024:
+                print(f"  ✓ {name} already exists")
+                continue
+
+        if required_only and not info["required"]:
+            print(f"  ⊘ {name} skipped (optional)")
+            continue
+
+        print(f"  ↓ Downloading {name} from {info['repo']}...")
+        try:
+            downloaded = hf_hub_download(
+                repo_id=info["repo"],
+                filename=info["file"],
+            )
+            shutil.copy(downloaded, local_path)
+            print(f"  ✓ {name} saved to {local_path}")
+
+            if "extra_files" in info:
+                for extra in info["extra_files"]:
+                    extra_local = Path("models") / Path(extra).name
+                    print(f"    ↓ Downloading extra file {extra}...")
+                    downloaded_extra = hf_hub_download(repo_id=info["repo"], filename=extra)
+                    shutil.copy(downloaded_extra, extra_local)
+                    print(f"    ✓ Saved to {extra_local}")
+
+        except Exception as e:
+            if info["required"]:
+                print(f"  ✗ Failed to download REQUIRED model {name}: {e}")
+            else:
+                print(f"  ✗ {name} failed (optional): {e}")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--required-only",
+        action="store_true",
+        help="Only download required models",
+    )
+    args = parser.parse_args()
+    download_all(required_only=args.required_only)

inspect_sam.py

@@ -0,0 +1,9 @@
+# inspect_sam.py
+import onnxruntime as ort
+path = "models/sam2_decoder.onnx"
+session = ort.InferenceSession(path)
+print("SAM2 Decoder Inputs:")
+for i in session.get_inputs():
+    print(f"  Name: {i.name}")
+    print(f"    Shape: {i.shape}")
+    print(f"    Type: {i.type}")

outputs/colo.code-workspace

@@ -0,0 +1,8 @@
+{
+	"folders": [
+		{
+			"path": "../.."
+		}
+	],
+	"settings": {}
+}

packages.txt

@@ -0,0 +1,2 @@
+libgl1-mesa-glx
+libglib2.0-0

render_build.py

@@ -0,0 +1,18 @@
+import os
+import subprocess
+import sys
+
+def build():
+    # 1. Install requirements
+    print("Installing requirements...")
+    subprocess.check_call([sys.executable, "-m", "pip", "install", "-r", "requirements.txt"])
+    
+    # 2. Download required models
+    print("Downloading required models...")
+    from download_models import download_all
+    download_all(required_only=True)
+    
+    print("Build step complete!")
+
+if __name__ == "__main__":
+    build()

requirements.txt

@@ -0,0 +1,14 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+python-multipart==0.0.18
+onnxruntime==1.19.2
+opencv-python-headless==4.10.0.84
+numpy==1.26.4
+scikit-learn==1.5.2
+svgwrite==1.4.3
+Pillow==10.4.0
+huggingface-hub==0.27.1
+torch==2.4.1
+torchvision==0.19.1
+httpx==0.28.1
+scipy==1.14.1

test_model.py

@@ -0,0 +1,18 @@
+
+import onnxruntime as ort
+import sys
+from pathlib import Path
+
+path = "models/informative_drawings.onnx"
+if not Path(path).exists():
+    print(f"Error: {path} not found")
+    sys.exit(1)
+
+print(f"Testing {path}...")
+try:
+    session = ort.InferenceSession(path, providers=["CPUExecutionProvider"])
+    print("✓ Model loaded successfully")
+    print(f"Inputs: {[i.name for i in session.get_inputs()]}")
+    print(f"Outputs: {[o.name for o in session.get_outputs()]}")
+except Exception as e:
+    print(f"✗ Failed: {e}")