Deploy to Hugging Face Space: product-image-update-port-6

.gitattributes

@@ -0,0 +1,72 @@
+# Standard LFS patterns
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+
+# Model-specific patterns
+models/**/*.bin filter=lfs diff=lfs merge=lfs -text
+models/**/*.safetensors filter=lfs diff=lfs merge=lfs -text
+models/**/*.onnx filter=lfs diff=lfs merge=lfs -text
+models/**/*.pt filter=lfs diff=lfs merge=lfs -text
+models/**/*.pth filter=lfs diff=lfs merge=lfs -text
+
+# Cache patterns
+.cache/**/*.bin filter=lfs diff=lfs merge=lfs -text
+.cache/**/*.safetensors filter=lfs diff=lfs merge=lfs -text
+.cache/**/*.json filter=lfs diff=lfs merge=lfs -text
+
+# Image patterns (for sample images)
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.bmp filter=lfs diff=lfs merge=lfs -text
+
+# Video patterns (if needed)
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.avi filter=lfs diff=lfs merge=lfs -text
+*.mov filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text
+
+# Text files (not LFS)
+*.txt -filter=lfs -diff=lfs -merge=lfs text
+*.md -filter=lfs -diff=lfs -merge=lfs text
+*.json -filter=lfs -diff=lfs -merge=lfs text
+*.py -filter=lfs -diff=lfs -merge=lfs text
+*.yml -filter=lfs -diff=lfs -merge=lfs text
+*.yaml -filter=lfs -diff=lfs -merge=lfs text
+requirements.txt -filter=lfs -diff=lfs -merge=lfs text
+README.md -filter=lfs -diff=lfs -merge=lfs text

Dockerfile

@@ -0,0 +1,116 @@
+version: '3.8'
+
+services:
+  product-image-update:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "7860:7860"
+    environment:
+      # Copy from .env file or set directly
+      - HF_TOKEN=${HF_TOKEN}
+      - CUDA_VISIBLE_DEVICES=${CUDA_VISIBLE_DEVICES:-0}
+      - PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
+      - TRANSFORMERS_CACHE=/app/.cache/huggingface
+      - HF_HOME=/app/.cache/huggingface
+      - GRADIO_SERVER_NAME=0.0.0.0
+      - GRADIO_SERVER_PORT=7860
+      - DEBUG=${DEBUG:-false}
+    volumes:
+      # Mount cache directories for faster restarts
+      - huggingface-cache:/app/.cache/huggingface
+      - torch-cache:/app/.cache/torch
+      - models-cache:/app/models
+      # Mount processed images directory
+      - ./processed_imgs:/app/processed_imgs
+      # For development - mount source code
+      - ./app.py:/app/app.py:ro
+      - ./utils.py:/app/utils.py:ro
+      - ./image-download:/app/image-download:ro
+      - ./remove-background:/app/remove-background:ro
+      - ./bounding-box:/app/bounding-box:ro
+      - ./cropping-padding:/app/cropping-padding:ro
+      - ./return-images:/app/return-images:ro
+    deploy:
+      resources:
+        limits:
+          memory: 16G
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    restart: unless-stopped
+    networks:
+      - app-network
+
+  # Optional: Nginx reverse proxy for production
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./ssl:/etc/nginx/ssl:ro
+    depends_on:
+      - product-image-update
+    networks:
+      - app-network
+    profiles:
+      - production
+
+  # Optional: Monitoring with Prometheus
+  prometheus:
+    image: prom/prometheus:latest
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus-data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+    networks:
+      - app-network
+    profiles:
+      - monitoring
+
+  # Optional: Grafana for visualization
+  grafana:
+    image: grafana/grafana:latest
+    ports:
+      - "3000:3000"
+    environment:
+      - GF_SECURITY_ADMIN_PASSWORD=admin
+    volumes:
+      - grafana-data:/var/lib/grafana
+    depends_on:
+      - prometheus
+    networks:
+      - app-network
+    profiles:
+      - monitoring
+
+volumes:
+  huggingface-cache:
+    driver: local
+  torch-cache:
+    driver: local
+  models-cache:
+    driver: local
+  prometheus-data:
+    driver: local
+  grafana-data:
+    driver: local
+
+networks:
+  app-network:
+    driver: bridge

src/processing/bounding_box/flow_diagram.mermaid

@@ -0,0 +1,98 @@
+flowchart TD
+    classDef blueBox fill:#0000ff33,stroke:#0000ff,color:#000
+    classDef greenBox fill:#00ff0033,stroke:#00ff00,color:#000
+    classDef violetBox fill:#ee82ee33,stroke:#ee82ee,color:#000
+    classDef orangeBox fill:#ffa50033,stroke:#ffa500,color:#000
+    classDef redBox fill:#ff000033,stroke:#ff0000,color:#000
+    classDef multiBox fill:lightyellow,stroke:#333,color:#000
+    classDef processNode fill:#dae8fc,stroke:#6c8ebf,color:#000
+    classDef dataNode fill:#d5e8d4,stroke:#82b366,color:#000
+
+    Input[/"Input Image"/] --> Step1
+    
+    subgraph Models["Detection Models"]
+        direction TB
+        RTDETR["RT-DETR Model
+🟦 Main Product Detection:
+person, coat, dress, jacket,
+shirt, skirt, pants, shorts
+
+🟧 Some Features:
+tie → collar"]:::multiBox
+        
+        RTDETR_A["RT-DETR Artifact Detection
+🟥 Artifacts:
+backpack, handbag → bag,
+bottle, cup → cup,
+book, cell phone, camera,
+umbrella"]:::redBox
+        
+        YOLO["YOLOv11 Model
+🟦 Main Products:
+jacket, coat, shirt, dress,
+vest, pants, jeans, shorts
+
+🟪 Shoes:
+footwear, shoes, boots,
+high heels, sandals
+
+🟧 Some Features:
+tie → collar"]:::multiBox
+        
+        HEAD["Head Detection Model
+🟩 Head:
+face, head"]:::greenBox
+    end
+    
+    Step1["Step 1: Define Largest Box
+Use RT-DETR to identify 
+the main product region"]:::processNode
+    RTDETR --> Step1
+    Step1 --> Step2
+    
+    Step2["Step 2: Multi-model Detection
+Run all models on 
+largest box region"]:::processNode
+    RTDETR --> Step2
+    RTDETR_A --> Step2
+    YOLO --> Step2
+    HEAD --> Step2
+    Step2 --> Step3
+    
+    Step3["Step 3: Color Assignment
+& Keyword Mapping"]:::processNode --> Categories
+    
+    subgraph Categories["Map objects to categories"]
+        direction TB
+        Product["🟦 BLUE: Product Type (0.4)
+jacket, shirt, vest,
+jeans, shorts, skirt, 
+overall, dress"]:::blueBox
+        
+        Head["🟩 GREEN: Head (0.5)
+head"]:::greenBox
+        
+        Shoes["🟪 VIOLET: Shoes (0.5)
+shoes"]:::violetBox
+        
+        Features["🟧 ORANGE: Features (0.4)
+neckline, collar, sleeve,
+closure, pocket"]:::orangeBox
+        
+        Artifacts["🟥 RED: Artifacts (0.7)
+bag, cup, hanger, book,
+phone, camera, umbrella"]:::redBox
+    end
+    
+    Categories --> Step4
+    
+    Step4["Step 4: Adjust Blue Box
+Refine product box based on 
+head and shoe positions"]:::processNode --> Step5
+    
+    Step5["Step 5: Draw Boxes
+Add colored bbox
+to image"]:::processNode --> Output
+    
+    Output["Processed Image
+With Boxes"]:::dataNode

src/processing/cropping_padding/flow_diagram.mermaid

@@ -0,0 +1,224 @@
+flowchart TD
+    classDef processNode fill:#dae8fc,stroke:#6c8ebf,color:#000
+    classDef imageNode fill:#d5e8d4,stroke:#82b366,color:#000
+    classDef decisionNode fill:#fff2cc,stroke:#d6b656,color:#000
+    classDef squareNode fill:#e3f2fd,stroke:#1976d2,color:#000
+    classDef landscapeNode fill:#e8f5e8,stroke:#388e3c,color:#000
+    classDef portraitNode fill:#fce4ec,stroke:#c2185b,color:#000
+    classDef transformNode fill:#f3e5f5,stroke:#7b1fa2,color:#000
+    classDef borderNode fill:#fff3e0,stroke:#f57c00,color:#000
+
+    Input[/"Input RGBA Image
+with transparent background"/]:::imageNode
+    Input --> InitialCrop
+    
+    InitialCrop["Initial Cropping
+• Use blue box coordinates from detection
+• Remove excess vertical space
+• Preserve product boundaries"]:::processNode
+    InitialCrop --> ShrinkBox
+    
+    ShrinkBox["Shrink Primary Box
+• Analyze alpha channel transparency
+• Remove white-only regions
+• Create tight bounding box"]:::processNode
+    ShrinkBox --> BorderDetect
+    
+    BorderDetect["Border Detection Analysis
+• Measure edge coverage ratios
+• Calculate feathering smoothness
+• Classify border types as straight lines"]:::processNode
+    BorderDetect --> OrientCheck
+    
+    OrientCheck{"Determine Image Orientation
+Width vs Height Analysis"}:::decisionNode
+    OrientCheck -->|"Width ≈ Height"| SquareFlow
+    OrientCheck -->|"Width > Height"| LandscapeFlow
+    OrientCheck -->|"Height > Width"| PortraitFlow
+    
+    subgraph SquareFlow["Square Image Transformation Pipeline □"]
+        SqInput["Square Input □
+Width ≈ Height"]:::squareNode
+        SqInput --> SqCheck{"Detect Special Cases"}:::decisionNode
+        
+        SqCheck -->|"Shoes Detected"| SqShoes["Shoes Transformation:
+□ → Pad bottom only
+□ → Ignore lower border flags
+□ → Result: Slightly taller square"]:::squareNode
+        
+        SqCheck -->|"Head + Borders"| SqHeadBorder["Head with Borders:
+□ → No padding changes
+□ → Preserve existing borders
+□ → Result: Original square maintained"]:::squareNode
+        
+        SqCheck -->|"Border Lines"| SqBorders["Border Lines Present:
+□ → No additional padding
+□ → Maintain current dimensions
+□ → Result: Original square preserved"]:::squareNode
+        
+        SqCheck -->|"Default Case"| SqDefault["Universal Padding:
+□ → UNIVERSAL_PAD_RATIO on all sides
+□ → Equal padding: top, bottom, left, right
+□ → Result: Larger square with even spacing"]:::squareNode
+        
+        SqShoes --> SqOutput["□ Final Square Output"]:::squareNode
+        SqHeadBorder --> SqOutput
+        SqBorders --> SqOutput
+        SqDefault --> SqOutput
+    end
+    
+    subgraph LandscapeFlow["Landscape Image Transformation Pipeline ▭"]
+        LsInput["Landscape Input ▭
+Width > Height"]:::landscapeNode
+        LsInput --> LsCheck{"Detect Special Cases"}:::decisionNode
+        
+        LsCheck -->|"Shoes Detected"| LsShoes["Shoes Transformation:
+▭ → Add bottom padding
+▭ → Crop to square format
+▭ → Result: Square with shoes at bottom"]:::transformNode
+        
+        LsCheck -->|"Head Detected"| LsHead["Head Transformation:
+▭ → Remove top padding
+▭ → Keep landscape shape square
+▭ → Result: Square with head positioned well"]:::transformNode
+        
+        LsCheck -->|"Border Lines"| LsBorders["Border Lines Transformation:
+▭ → Coverage-based cropping
+▭ → Analyze content distribution
+▭ → Result: Square from content analysis"]:::transformNode
+        
+        LsCheck -->|"Default Case"| LsDefault["Two-Step Transformation:
+▭ → Step 1: Pad height to approach square
+▭ → Step 2: Equalize to perfect square
+▭ → Result: Centered square with even padding"]:::transformNode
+        
+        LsShoes --> LsOutput["□ Final Square Output"]:::landscapeNode
+        LsHead --> LsOutput
+        LsBorders --> LsOutput
+        LsDefault --> LsOutput
+    end
+    
+    subgraph PortraitFlow["Portrait Image Transformation Pipeline ▯"]
+        PtInput["Portrait Input ▯
+Height > Width"]:::portraitNode
+        PtInput --> PtCheck{"Detect Special Cases"}:::decisionNode
+        
+        PtCheck -->|"Shoes Detected"| PtShoes["Shoes Transformation:
+▯ → Never pad top
+▯ → Always pad bottom
+▯ → Pad sides to square
+▯ → Result: Square with shoes at bottom"]:::transformNode
+        
+        PtCheck -->|"Head Detected"| PtHead["Head Transformation:
+▯ → Pad left and right only
+▯ → Maintain head position
+▯ → Result: Square with head positioned"]:::transformNode
+        
+        PtCheck -->|"L/R Borders"| PtLR["L/R Borders Transformation:
+▯ → Coverage-based cropping
+▯ → Remove excess based on content density
+▯ → Result: Square from intelligent cropping"]:::transformNode
+        
+        PtCheck -->|"U+L Borders"| PtUL["U+L Borders Transformation:
+▯ → Pad left and right only
+▯ → Maintain vertical borders
+▯ → Result: Square with preserved content"]:::transformNode
+        
+        PtCheck -->|"One Border"| PtOne["Single Border Transformation:
+▯ → Two-step padding process
+▯ → Step 1: Pad width toward square
+▯ → Result: Balanced square output"]:::transformNode
+        
+        PtCheck -->|"Default Case"| PtDefault["Default Transformation:
+▯ → Two-step padding process
+▯ → Step 1: Add horizontal padding
+▯ → Result: Centered square with side padding"]:::transformNode
+        
+        PtShoes --> PtOutput["□ Final Square Output"]:::portraitNode
+        PtHead --> PtOutput
+        PtLR --> PtOutput
+        PtUL --> PtOutput
+        PtOne --> PtOutput
+        PtDefault --> PtOutput
+    end
+    
+    SqOutput --> Centering
+    LsOutput --> Centering
+    PtOutput --> Centering
+    
+    Centering["Final Object Centering
+• Analyze alpha channel boundaries
+• Calculate product midpoint
+• Shift horizontally to center
+• Maintain padding relationships"]:::processNode
+    Centering --> FinalOutput
+    
+    FinalOutput[/"□ Final Processed Square Image
+Consistently sized and centered"/]:::imageNode
+    
+    subgraph BorderDetectionDetails["Border Detection Algorithm Details"]
+        BorderParams["Detection Parameters:
+COVERAGE_THRESHOLD = 0.25
+FEATHER_THRESHOLD_MIN = 0.3
+FEATHER_THRESHOLD_MAX = 0.7"]:::borderNode
+        
+        CoverageAnalysis["Coverage Analysis:
+• Left Border: Vertical edge pattern
+• Right Border: Opposite vertical edge
+• Upper Border: Top horizontal edge
+• Lower Border: Bottom horizontal edge"]:::borderNode
+        
+        FeatheringAnalysis["Feathering Analysis:
+• Hard Edges: Sharp transitions
+• Soft Edges: Gradual transitions
+• Feathering Ratio: Transition zone proportion"]:::borderNode
+        
+        Classification["Classification Criteria:
+Border = Straight Line when:
+• Coverage > COVERAGE_THRESHOLD
+• Feathering outside MIN-MAX range"]:::borderNode
+        
+        BorderParams --> CoverageAnalysis --> FeatheringAnalysis --> Classification
+    end
+    
+    BorderDetect -.-> BorderDetectionDetails
+    
+    subgraph TransformationExamples["Visual Transformation Examples"]
+        ExampleSquare["Square Examples:
+□ 1000×1000 → □ 1150×1150 (universal pad)
+□ 1000×1000 → □ 1000×1000 (preserved)"]:::squareNode
+        
+        ExampleLandscape["Landscape Examples:
+▭ 1200×800 → ▭ 1200×1200 (height pad) → □ 1200×1200
+▭ 1400×900 → Analysis → □ 1200×1200 (coverage crop)"]:::landscapeNode
+        
+        ExamplePortrait["Portrait Examples:
+▯ 800×1200 → ▯ 1200×1200 (width pad) → □ 1200×1200
+▯ 600×1000 → ▯ 1000×1000 (side pad) → □ 1000×1000"]:::portraitNode
+    end
+    
+    FinalOutput -.-> TransformationExamples
+    
+    subgraph PaddingStrategies["Padding Strategy Implementation"]
+        UniversalPadding["Universal Padding:
+UNIVERSAL_PAD_RATIO = 0.075
+Applied as 7.5% of image dimension
+1000px image = 75px padding per side"]:::borderNode
+        
+        TwoStepPadding["Two-Step Padding:
+Step 1: Pad longer dimension toward square
+Step 2: Equalize shorter dimension
+Step 3: Complete perfect square formation"]:::borderNode
+        
+        CoverageCropping["Coverage-Based Cropping:
+Step 1: Analyze content distribution
+Step 2: Remove excess based on density
+Step 3: Apply minimal padding
+Step 4: Achieve square format"]:::borderNode
+        
+        UniversalPadding --> TwoStepPadding --> CoverageCropping
+    end
+    
+    SquareFlow -.-> PaddingStrategies
+    LandscapeFlow -.-> PaddingStrategies
+    PortraitFlow -.-> PaddingStrategies

src/processing/remove_background/flow_diagram.mermaid

@@ -0,0 +1,349 @@
+flowchart TD
+    classDef processNode fill:#dae8fc,stroke:#6c8ebf,color:#000
+    classDef imageNode fill:#d5e8d4,stroke:#82b366,color:#000
+    classDef modelNode fill:#ffe6cc,stroke:#d79b00,color:#000
+    classDef paramNode fill:#fff2cc,stroke:#d6b656,color:#000
+    classDef analysisNode fill:#e1d5e7,stroke:#9673a6,color:#000
+    classDef scaleNode fill:#ffa50033,stroke:#ffa500,color:#000
+    classDef configNode fill:#f0f8ff,stroke:#4682b4,color:#000
+    classDef postProcessNode fill:#e1d5e7,stroke:#9673a6,color:#000
+    classDef componentNode fill:#ffb6c1,stroke:#c71585,color:#000
+
+    Input[/"Downloaded Image Content
+(_download_content)"/]:::imageNode --> Stage1
+    
+    Stage1["Stage 1: Preprocessing & Analysis
+• ImageOps.exif_transpose()
+• RGB conversion
+• Dynamic size configuration
+• Image analysis & enhancement"]:::processNode --> Stage2
+    
+    Stage2["Stage 2: Size-Grouped Model Application
+• Group by identical dimensions
+• Multi-scale tensor preparation
+• RMBG neural network inference
+• Scale-specific processing"]:::processNode --> Stage3
+    
+    Stage3["Stage 3: Advanced Post-Processing
+• guided_filter() edge preservation
+• Morphological operations pipeline
+• Bilateral filtering
+• Gaussian blur smoothing"]:::processNode --> Stage4
+    
+    Stage4["Stage 4: Component Analysis & Selection
+• Connected component detection
+• Left-side preference logic
+• Area-based optimization
+• Best component selection"]:::postProcessNode --> Stage5
+    
+    Stage5["Stage 5: Final Composition
+• final_pad_sq() processing
+• Content cleanup
+• Context update (pil_img)"]:::processNode --> Output
+    
+    Output[/"RGBA Image with Transparent Background"/]:::imageNode
+    
+    subgraph ImageAnalysis["Enhanced Image Analysis Pipeline"]
+        BlueDetect["detect_blue_background()
+HSV: [100,100,80] - [130,255,255]
+Threshold: >25% coverage"]:::analysisNode
+        
+        SkinDetect["detect_skin_tones()
+HSV ranges for diverse skin tones
+Threshold: >10% coverage"]:::analysisNode
+        
+        DenimDetect["detect_denim()
+HSV: [80,30,30] - [130,220,230]
+Additional range: [85,15,100] - [115,130,230]
+Threshold: >12% coverage"]:::analysisNode
+        
+        OutdoorDetect["detect_outdoor_scene()
+Green: [35,40,40] - [85,255,255]
+Sky: [90,40,150] - [130,120,255]
+Threshold: >15% coverage"]:::analysisNode
+        
+        DiffCheck["analyze_image_difficulty()
+contrast = std(histogram * pixel_values)
+edge_ratio = mean(canny_edges > 0)
+Difficult: contrast < 50 AND edge_ratio < 0.05"]:::analysisNode
+        
+        ApplyEnhancements["Context-Aware Enhancement:
+• Base: RBC_CONTRAST_FACTOR (1.25)
+• Outdoor: factor * 1.1
+• Person: factor * 0.75
+• Sharpness: RBC_SHARPNESS_FACTOR (1.15)
+• Edge enhancement for difficult images"]:::analysisNode
+        
+        BlueDetect --> SkinDetect --> DenimDetect --> OutdoorDetect --> DiffCheck --> ApplyEnhancements
+    end
+    
+    Stage1 -.-> ImageAnalysis
+    
+    subgraph DynamicSizing["Dynamic Size Configuration System v2"]
+        SizeDetection["determine_size_config()
+max_dim = max(width, height)
+SIZE_CONFIG_SCALE = [1024, 1536]
+• < 1024px → 'small' config
+• 1024-1536px → 'medium' config  
+• > 1536px → 'large' config"]:::scaleNode
+        
+        OptimalScale["calculate_optimal_scale()
+if max_original <= target_side: return 1.0
+else: return (target_side * 0.98) / max_original
+Prevents unnecessary upscaling"]:::scaleNode
+        
+        ConfigMapping["SIZE_CONFIGS Mapping:
+Small: final_side=1024, scales=[2.0,1.5,1.0,0.5]
+Medium: final_side=1536, scales=[1.25,1.0,0.75,0.5]
+Large: final_side=2048, scales=[1.0,0.75,0.5,0.25]"]:::scaleNode
+        
+        SizeDetection --> OptimalScale --> ConfigMapping
+    end
+    
+    Stage1 -.-> DynamicSizing
+    
+    subgraph SizeGroupedProcessing["Size-Grouped RMBG Processing v16_balanced"]
+        GroupBySize["Group Tensors by Size:
+• Create size_key: 'WxH' format
+• Group tensors with identical dimensions
+• Separate metas and indices by size
+• Prevent concatenation errors"]:::scaleNode
+        
+        PrepareScales["Scale Preparation per Size Group:
+For each scale in RBC_SCALES:
+• Resize enhanced image
+• Apply rmbg_trans normalization
+• Create tensor batch"]:::scaleNode
+        
+        ModelInference["Model Inference per Size Group:
+• Batch tensor to device (same sizes only)
+• RMBG model forward pass
+• Extract logits (handle list/tuple)
+• Apply sigmoid for probabilities"]:::modelNode
+        
+        CombineResults["Probability Combination:
+• Weight scale contributions
+• Merge probability maps
+• Apply THRESH (0.42)
+• Generate binary mask"]:::scaleNode
+        
+        GroupBySize --> PrepareScales --> ModelInference --> CombineResults
+        
+        subgraph ScaleOptimization["Scale-Specific Processing"]
+            SmallConfig["Small Images (< 1024px):
+final_side: 1024px
+scales: [2.0, 1.5, 1.0, 0.5]
+• 2.0x: Fine detail capture
+• 1.5x: Enhanced edges
+• 1.0x: Reference
+• 0.5x: Context"]:::scaleNode
+            
+            MediumConfig["Medium Images (1024-1536px):
+final_side: 1536px
+scales: [1.25, 1.0, 0.75, 0.5]
+• 1.25x: Slight enhancement
+• 1.0x: Native resolution
+• 0.75x: Noise reduction
+• 0.5x: Fast context"]:::scaleNode
+            
+            LargeConfig["Large Images (> 1536px):
+final_side: 2048px
+scales: [1.0, 0.75, 0.5, 0.25]
+• 1.0x: Full resolution
+• 0.75x: Balanced quality
+• 0.5x: Efficient processing
+• 0.25x: Overall structure"]:::scaleNode
+        end
+        
+        ModelInference -.-> ScaleOptimization
+    end
+    
+    Stage2 -.-> SizeGroupedProcessing
+    
+    subgraph MaskRefinement["Advanced Mask Refinement Pipeline"]
+        GuidedFilter["guided_filter()
+DO_GUIDED_FILTER = True
+radius: 4, eps: 0.01
+Edge-aware smoothing"]:::processNode
+        
+        MorphClose["cv2.morphologyEx(MORPH_CLOSE)
+MORPH_CLOSE_ITER = 1
+MORPH_KERNEL_SIZE = (3,3)
+Fill small mask holes"]:::processNode
+        
+        MorphOpen["cv2.morphologyEx(MORPH_OPEN)
+MORPH_OPEN_ITER = 1
+Remove isolated pixels"]:::processNode
+        
+        Erosion["cv2.erode()
+EROSION_ITER = 1
+Shrink mask boundaries"]:::processNode
+        
+        BilateralFilter["cv2.bilateralFilter()
+USE_BILATERAL = True
+Parameters: (9, 75, 75)
+Edge-preserving noise reduction"]:::processNode
+        
+        GaussianBlur["cv2.GaussianBlur()
+GAUSSIAN_KERNEL_SIZE = (7,7)
+Final edge smoothing"]:::processNode
+        
+        GuidedFilter --> MorphClose --> MorphOpen --> Erosion --> BilateralFilter --> GaussianBlur
+    end
+    
+    Stage3 -.-> MaskRefinement
+    
+    subgraph ComponentAnalysis["Component Analysis with Left-Side Selection"]
+        AlphaAnalysis["Alpha Channel Analysis:
+• Convert final_rgba alpha to numpy array
+• Apply scipy.label() for connected components
+• Count and identify separate regions"]:::componentNode
+        
+        BoundingBoxCalc["Bounding Box Calculation:
+• Use find_objects() to get region coordinates
+• Calculate sy, ey, sx, ex for each component
+• Crop sub-images for area analysis"]:::componentNode
+        
+        SpatialCategorization["Spatial Categorization:
+• Calculate center_x = (sx + ex) / 2.0
+• Left components: center_x < image_width / 2
+• Other components: center_x >= image_width / 2
+• Store area and sub_img for each"]:::componentNode
+        
+        SelectionLogic["Selection Logic:
+if left_components AND other_components:
+    best_crop = max(left_components, key=area)
+else:
+    all_components = left + other
+    best_crop = max(all_components, key=area)
+fallback: use original final_rgba"]:::componentNode
+        
+        DetailedLogging["Enhanced Logging:
+• num_components: total detected
+• split_component_boxes: coordinates & areas
+• passed_image_dimensions: final selection
+• time_seconds: processing duration"]:::componentNode
+        
+        AlphaAnalysis --> BoundingBoxCalc --> SpatialCategorization --> SelectionLogic --> DetailedLogging
+    end
+    
+    Stage4 -.-> ComponentAnalysis
+    
+    subgraph CalibrationV16["Calibration v16_balanced Parameters"]
+        ImageParams["Image Enhancement:
+• RBC_CONTRAST_FACTOR = 1.25
+• RBC_SHARPNESS_FACTOR = 1.15
+• PAD_COLOR = '#ffffff'"]:::paramNode
+        
+        ThresholdParams["Threshold Settings:
+• THRESH = 0.42 (primary)
+• RESCUE_THRESH = 0.20 (fallback)
+• Balanced precision/recall"]:::paramNode
+        
+        MorphParams["Morphological Settings:
+• MORPH_KERNEL_SIZE = (3,3)
+• MORPH_CLOSE_ITER = 1
+• MORPH_OPEN_ITER = 1
+• EROSION_ITER = 1"]:::paramNode
+        
+        FilterParams["Filter Configuration:
+• GAUSSIAN_KERNEL_SIZE = (7,7)
+• DO_GUIDED_FILTER = True
+• USE_BILATERAL = True
+• FILL_HOLES = False"]:::paramNode
+        
+        BatchParams["Batch Settings:
+• MAX_IMAGES_PER_BATCH = 4
+• CALIBRATION_VERSION = 'v16_balanced'
+• SIZE_CONFIG_SCALE = [1024, 1536]"]:::paramNode
+        
+        ImageParams --> ThresholdParams --> MorphParams --> FilterParams --> BatchParams
+    end
+    
+    SizeGroupedProcessing -.-> CalibrationV16
+    MaskRefinement -.-> CalibrationV16
+    ComponentAnalysis -.-> CalibrationV16
+    
+    subgraph ErrorHandling["Error Handling & Performance"]
+        SkipLogic["Skip Condition Handling:
+• Check skip_run flag
+• Check skip_processing flag
+• Validate _download_content existence"]:::processNode
+        
+        SizeGroupHandling["Size Group Error Handling:
+• Isolate errors per size group
+• Continue processing other size groups
+• Detailed size-specific error logging"]:::processNode
+        
+        MemoryMgmt["Memory Management:
+• Immediate _download_content cleanup
+• Tensor device management per size group
+• Component analysis memory optimization"]:::processNode
+        
+        PerformanceLog["Performance Logging:
+• Processing time tracking per stage
+• Success/error/skip counters per size group
+• Component analysis metrics
+• Size configuration logging"]:::processNode
+        
+        SkipLogic --> SizeGroupHandling --> MemoryMgmt --> PerformanceLog
+    end
+    
+    Stage1 -.-> ErrorHandling
+    Stage2 -.-> ErrorHandling
+    Stage4 -.-> ErrorHandling
+    Stage5 -.-> ErrorHandling
+    
+    subgraph BatchProcessing["Enhanced Batch Processing Flow"]
+        PreprocessBatch["preprocess_images_batch()
+• Load from _download_content
+• Size config determination using SIZE_CONFIG_SCALE
+• Image analysis & enhancement
+• Error isolation per context"]:::processNode
+        
+        ModelBatch["apply_model_batch() with Size Grouping
+• Group tensors by identical dimensions
+• Process each size group independently
+• Device placement & precision per group
+• Component analysis per image"]:::modelNode
+        
+        PostprocessBatch["Batch Post-processing:
+• Mask refinement per image
+• Component selection per image
+• Performance summary per size group
+• Context updates with selected components"]:::processNode
+        
+        PreprocessBatch --> ModelBatch --> PostprocessBatch
+    end
+    
+    Stage1 -.-> BatchProcessing
+    Stage2 -.-> BatchProcessing
+    Stage3 -.-> BatchProcessing
+    Stage4 -.-> BatchProcessing
+    
+    subgraph TensorSizeHandling["Tensor Size Compatibility Solution"]
+        SizeDetection2["Image Size Detection:
+• Extract width x height from enhanced image
+• Create size_key string (e.g., '1536x1536')
+• Group compatible images together"]:::configNode
+        
+        GroupingStrategy["Grouping Strategy:
+tensors_by_size = {}
+metas_by_size = {}
+idxs_by_size = {}
+• Separate data structures per size"]:::configNode
+        
+        ProcessingLoop["Processing Loop:
+for size_key, tensors in tensors_by_size.items():
+    batch = torch.cat(tensors)  # All same size!
+    # Process batch normally"]:::configNode
+        
+        ErrorPrevention["Error Prevention:
+• No more 'Sizes of tensors must match'
+• Each size group processes independently
+• Maintains batch efficiency within groups"]:::configNode
+        
+        SizeDetection2 --> GroupingStrategy --> ProcessingLoop --> ErrorPrevention
+    end
+    
+    Stage2 -.-> TensorSizeHandling

src/processing/return_images/flow_diagram.mermaid

@@ -0,0 +1,61 @@
+flowchart TD
+    classDef processNode fill:#dae8fc,stroke:#6c8ebf,color:#000
+    classDef dataNode fill:#d5e8d4,stroke:#82b366,color:#000
+    classDef colorNode fill:#ffe6cc,stroke:#d79b00,color:#000
+    classDef typeNode fill:#e1d5e7,stroke:#9673a6,color:#000
+    classDef outputNode fill:#f8cecc,stroke:#b85450,color:#000
+
+    Input[/"Processed Image"/]:::dataNode --> Step1
+    
+    Step1["Step 1: Color Extraction & Mapping
+Sample non-transparent pixels, 
+quantize colors, determine dominant color"]:::processNode --> Step2
+    
+    Step2["Step 2: Image Type Detection
+Analyze padding information 
+and detection keywords"]:::processNode --> Step3
+    
+    Step3["Step 3: WebP Conversion & Base64 Encoding
+Check for artifacts, convert format,
+encode for API response"]:::processNode --> Output
+    
+    Output[/"Final Response Data"/]:::dataNode
+    
+    subgraph ColorAnalysis["Color Classification Logic"]
+        RGBToHSL["RGB → HSL conversion"]:::processNode
+        
+        MonochromeCheck{"Is monochrome?
+(low saturation)"}:::colorNode
+        RGBToHSL --> MonochromeCheck
+        
+        MonochromeCheck -->|"Yes"| GreyscaleGrouping{"Lightness values"}:::colorNode
+        GreyscaleGrouping -->|"< 0.28"| Black["Black"]:::colorNode
+        GreyscaleGrouping -->|"0.28-0.88"| Grey["Grey"]:::colorNode
+        GreyscaleGrouping -->|"> 0.88"| White["White"]:::colorNode
+        
+        MonochromeCheck -->|"No"| BlueRangeCheck{"Is blue range?
+(160° ≤ H < 260°)"}:::colorNode
+        BlueRangeCheck -->|"Yes"| BlueShades{"Lightness values"}:::colorNode
+        BlueShades -->|"< 0.40"| DarkBlue["Dark Blue"]:::colorNode
+        BlueShades -->|"0.40-0.65"| Blue["Blue"]:::colorNode
+        BlueShades -->|"> 0.65"| LightBlue["Light Blue"]:::colorNode
+        
+        BlueRangeCheck -->|"No"| PrimaryColors{"Primary color groups
+based on hue angle"}:::colorNode
+        PrimaryColors -->|"0°-70°"| YellowGroup["Yellow Group"]:::colorNode
+        PrimaryColors -->|"70°-160°"| GreenGroup["Green Group"]:::colorNode
+        PrimaryColors -->|"260°-360°"| RedGroup["Red Group"]:::colorNode
+    end
+    
+    Step1 -.-> ColorAnalysis
+    
+    subgraph TypeAssignment["Image Type Assignment"]
+        PaddingCheck{"All sides padded?"}:::typeNode
+        PaddingCheck -->|"Yes"| PaddedProduct["padded_product"]:::typeNode
+        PaddingCheck -->|"No"| HeadShoesCheck{"Head or shoes
+detected?"}:::typeNode
+        HeadShoesCheck -->|"No"| DetailType["detail"]:::typeNode
+        HeadShoesCheck -->|"Yes"| DefaultType["none"]:::typeNode
+    end
+    
+    Step2 -.-> TypeAssignment