Upload 9 files

DEPLOYMENT.md

@@ -0,0 +1,250 @@
+# Deployment Guide - Hugging Face Spaces
+
+## Quick Deployment to Hugging Face
+
+### Step 1: Prepare Files
+
+Ensure you have these files:
+```
+your-repo/
+├── app.py                    # FastAPI application
+├── binary_segmentation.py    # Core segmentation module
+├── requirements.txt          # Python dependencies
+├── Dockerfile               # Docker configuration
+├── README.md                # This becomes your Space README
+├── static/
+│   └── index.html          # Web interface
+└── .model_cache/
+    └── u2netp.pth          # Model weights (IMPORTANT!)
+```
+
+### Step 2: Download U2NETP Weights
+
+**CRITICAL**: You must download the U2NETP model weights:
+
+1. Visit: https://github.com/xuebinqin/U-2-Net/tree/master/saved_models
+2. Download: `u2netp.pth` (4.7 MB)
+3. Place in: `.model_cache/u2netp.pth`
+
+**OR** use this direct link:
+```bash
+mkdir -p .model_cache
+wget https://github.com/xuebinqin/U-2-Net/raw/master/saved_models/u2netp/u2netp.pth -O .model_cache/u2netp.pth
+```
+
+### Step 3: Create Hugging Face Space
+
+1. Go to https://huggingface.co/new-space
+2. Fill in:
+   - **Space name**: `background-removal` (or your choice)
+   - **License**: Apache 2.0
+   - **SDK**: Docker
+   - **Hardware**: CPU Basic (free tier works!)
+   
+3. Click "Create Space"
+
+### Step 4: Upload Files
+
+#### Option A: Using Git (Recommended)
+
+```bash
+# Clone your new space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+
+# Copy all files
+cp /path/to/app.py .
+cp /path/to/binary_segmentation.py .
+cp /path/to/requirements.txt .
+cp /path/to/Dockerfile .
+cp /path/to/README_HF.md ./README.md
+cp -r /path/to/static .
+cp -r /path/to/.model_cache .
+
+# Commit and push
+git add .
+git commit -m "Initial commit"
+git push
+```
+
+#### Option B: Using Web Interface
+
+1. Click "Files" → "Add file"
+2. Upload each file individually
+3. **Important**: Upload `.model_cache/u2netp.pth` (it's large, ~4.7MB)
+
+### Step 5: Wait for Build
+
+- Space will build automatically (takes 3-5 minutes)
+- Watch the "Logs" tab for build progress
+- Once complete, your Space will be live!
+
+### Step 6: Test Your Space
+
+Visit your Space URL and try:
+1. Upload an image
+2. Click "Process Image"
+3. Download the result
+
+## Configuration Options
+
+### Use Different Models
+
+To enable BiRefNet or RMBG models, edit `requirements.txt`:
+
+```txt
+# Uncomment these lines:
+transformers>=4.30.0
+huggingface-hub>=0.16.0
+```
+
+**Note**: These models are larger and may require upgraded hardware (GPU).
+
+### Custom Port
+
+Default port is 7860 (Hugging Face standard). To change:
+
+In `Dockerfile`:
+```dockerfile
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+### Environment Variables
+
+Add secrets in Space Settings:
+```python
+import os
+API_KEY = os.environ.get("API_KEY", "default")
+```
+
+## Hardware Requirements
+
+### CPU Basic (Free)
+- ✅ U2NETP model
+- ✅ Small to medium images (<5MP)
+- ⏱️ ~2-5 seconds per image
+
+### CPU Upgrade
+- ✅ U2NETP model
+- ✅ Large images
+- ⏱️ ~1-3 seconds per image
+
+### GPU T4
+- ✅ All models (U2NETP, BiRefNet, RMBG)
+- ✅ Any image size
+- ⏱️ <1 second per image
+
+## Troubleshooting
+
+### Build Fails
+
+**Issue**: "No module named 'binary_segmentation'"
+- **Fix**: Ensure `binary_segmentation.py` is in root directory
+
+**Issue**: "Model weights not found"
+- **Fix**: Upload `u2netp.pth` to `.model_cache/u2netp.pth`
+
+**Issue**: "OpenCV error"
+- **Fix**: Check Dockerfile has `libgl1-mesa-glx` installed
+
+### Runtime Errors
+
+**Issue**: "Out of memory"
+- **Fix**: Upgrade to GPU hardware OR reduce image size
+
+**Issue**: "Slow processing"
+- **Fix**: Use CPU Upgrade or GPU hardware
+
+**Issue**: "Model not loading"
+- **Fix**: Check logs, ensure model file is in correct location
+
+### API Not Working
+
+**Issue**: 404 errors
+- **Fix**: Check that FastAPI routes are correct
+- **Fix**: Ensure `app:app` in CMD matches `app = FastAPI()` in code
+
+**Issue**: CORS errors
+- **Fix**: CORS is enabled by default; check browser console
+
+## File Structure Verification
+
+Before deploying, verify:
+
+```bash
+# Check all files exist
+ls -la
+
+# Should see:
+# app.py
+# binary_segmentation.py
+# requirements.txt
+# Dockerfile
+# README.md
+# static/index.html
+# .model_cache/u2netp.pth
+
+# Check model file size (should be ~4.7MB)
+ls -lh .model_cache/u2netp.pth
+```
+
+## Alternative: Deploy Without Docker
+
+If you prefer not to use Docker, create `.spacesdk` file:
+
+```
+sdk: gradio
+sdk_version: 4.0.0
+```
+
+Then modify to use Gradio instead of FastAPI. But Docker is recommended for FastAPI.
+
+## Post-Deployment
+
+### Monitor Usage
+- Check "Analytics" tab for usage stats
+- Monitor "Logs" for errors
+
+### Update Your Space
+```bash
+git pull
+# Make changes
+git add .
+git commit -m "Update"
+git push
+```
+
+### Share Your Space
+- Get shareable link from Space page
+- Embed in website using iframe
+- Use API endpoint in your apps
+
+## Example API Usage from External Apps
+
+Once deployed, use your Space API:
+
+```python
+import requests
+
+SPACE_URL = "https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME"
+
+with open('image.jpg', 'rb') as f:
+    response = requests.post(
+        f"{SPACE_URL}/segment",
+        files={'file': f},
+        data={'model': 'u2netp', 'threshold': 0.5}
+    )
+    
+with open('result.png', 'wb') as out:
+    out.write(response.content)
+```
+
+## Need Help?
+
+- Hugging Face Docs: https://huggingface.co/docs/hub/spaces
+- Community Forum: https://discuss.huggingface.co/
+- Discord: https://discord.gg/hugging-face
+
+---
+
+**Pro Tip**: Start with CPU Basic (free), test your Space, then upgrade to GPU if needed!

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application files
+COPY . .
+
+# Create necessary directories
+RUN mkdir -p .model_cache static
+
+# Expose port
+EXPOSE 7860
+
+# Run the application
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,12 +1,135 @@
----
-title: Inspectech Segmentation
-emoji: 🐨
-colorFrom: purple
-colorTo: gray
-sdk: gradio
-sdk_version: 6.5.1
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Binary Image Segmentation - FastAPI Service
+
+Professional background removal service with web interface and REST API, ready for Hugging Face Spaces deployment.
+
+## 🚀 Quick Start
+
+### Local Development
+
+```bash
+# 1. Install dependencies
+pip install -r requirements.txt
+
+# 2. Download U2NETP model weights
+mkdir -p .model_cache
+wget https://github.com/xuebinqin/U-2-Net/raw/master/saved_models/u2netp/u2netp.pth -O .model_cache/u2netp.pth
+
+# 3. Run the server
+uvicorn app:app --host 0.0.0.0 --port 7860
+
+# 4. Open browser
+# Visit: http://localhost:7860
+```
+
+### Test the API
+
+```bash
+python test_api.py
+```
+
+## 📁 Project Structure
+
+```
+.
+├── app.py                    # FastAPI application (main entry point)
+├── binary_segmentation.py    # Core segmentation module
+├── requirements.txt          # Python dependencies
+├── Dockerfile               # Docker configuration for deployment
+├── README_HF.md             # Hugging Face Space README
+├── DEPLOYMENT.md            # Detailed deployment guide
+├── client_examples.py       # API usage examples (Python, JS, curl)
+├── test_api.py             # Test script
+├── .gitignore              # Git ignore file
+└── static/
+    └── index.html          # Web interface
+```
+
+## 🎨 Features
+
+### Web Interface
+- Drag & drop image upload
+- 3 AI model options (U2NETP, BiRefNet, RMBG)
+- Adjustable threshold
+- Multiple output formats (transparent PNG, binary mask, or both)
+- Real-time preview
+- Download results
+
+### REST API
+- **POST /segment** - Segment image → transparent PNG
+- **POST /segment/mask** - Get binary mask only
+- **POST /segment/base64** - Get base64 encoded results
+- **POST /segment/batch** - Process multiple images
+- **GET /models** - List available models
+- **GET /health** - Health check
+
+### Supported Models
+
+| Model | Speed | Accuracy | Size | Best For |
+|-------|-------|----------|------|----------|
+| **U2NETP** | ⚡⚡⚡ | ⭐⭐ | 4.7 MB | Speed, simple objects |
+| **BiRefNet** | ⚡ | ⭐⭐⭐ | ~400 MB | Best quality |
+| **RMBG** | ⚡⚡ | ⭐⭐⭐ | ~200 MB | Balanced |
+
+## 🔧 API Usage Examples
+
+### Python
+
+```python
+import requests
+
+# Segment image
+with open('input.jpg', 'rb') as f:
+    response = requests.post(
+        'http://localhost:7860/segment',
+        files={'file': f},
+        data={'model': 'u2netp', 'threshold': 0.5}
+    )
+
+# Save result
+with open('output.png', 'wb') as out:
+    out.write(response.content)
+```
+
+### JavaScript
+
+```javascript
+async function removeBackground(file) {
+    const formData = new FormData();
+    formData.append('file', file);
+    formData.append('model', 'u2netp');
+    formData.append('threshold', '0.5');
+    
+    const response = await fetch('/segment', {
+        method: 'POST',
+        body: formData
+    });
+    
+    const blob = await response.blob();
+    return URL.createObjectURL(blob);
+}
+```
+
+### cURL
+
+```bash
+curl -X POST "http://localhost:7860/segment" \
+  -F "file=@input.jpg" \
+  -F "model=u2netp" \
+  -F "threshold=0.5" \
+  --output result.png
+```
+
+See `client_examples.py` for more!
+
+## 🌐 Deploy to Hugging Face Spaces
+
+See `DEPLOYMENT.md` for complete guide!
+
+## 📝 License
+
+Apache 2.0
+
+## 🙏 Credits
+
+- U2-Net, BiRefNet, RMBG models
+- FastAPI framework

app.py

@@ -0,0 +1,400 @@
+"""
+FastAPI Binary Segmentation Service
+Hugging Face Space compatible
+"""
+
+from fastapi import FastAPI, File, UploadFile, Form, HTTPException
+from fastapi.responses import Response, JSONResponse, FileResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+import cv2
+import numpy as np
+from PIL import Image
+import io
+import logging
+from typing import Literal, Optional
+import base64
+import os
+
+from binary_segmentation import BinarySegmenter
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="Binary Segmentation API",
+    description="Remove background from images using AI models",
+    version="1.0.0"
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Mount static files
+if os.path.exists("static"):
+    app.mount("/static", StaticFiles(directory="static"), name="static")
+
+# Global model instance (lazy loading)
+segmenter_cache = {}
+
+def get_segmenter(model_type: str = "u2netp") -> BinarySegmenter:
+    """Get or create segmenter instance"""
+    if model_type not in segmenter_cache:
+        logger.info(f"Loading {model_type} model...")
+        segmenter_cache[model_type] = BinarySegmenter(model_type=model_type)
+        logger.info(f"{model_type} model loaded successfully")
+    return segmenter_cache[model_type]
+
+
+@app.get("/")
+async def root():
+    """Serve the web interface"""
+    if os.path.exists("static/index.html"):
+        return FileResponse("static/index.html")
+    
+    # Fallback to API info
+    return {
+        "name": "Binary Segmentation API",
+        "version": "1.0.0",
+        "endpoints": {
+            "/segment": "POST - Segment image and return PNG with transparency",
+            "/segment/mask": "POST - Return binary mask only",
+            "/segment/base64": "POST - Return base64 encoded results",
+            "/health": "GET - Health check",
+            "/models": "GET - List available models"
+        }
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy",
+        "models_loaded": list(segmenter_cache.keys())
+    }
+
+
+@app.get("/models")
+async def list_models():
+    """List available segmentation models"""
+    return {
+        "models": [
+            {
+                "name": "u2netp",
+                "description": "Lightweight, fast model (1.1M params)",
+                "speed": "⚡⚡⚡",
+                "accuracy": "⭐⭐",
+                "size": "4.7 MB"
+            },
+            {
+                "name": "birefnet",
+                "description": "High accuracy model",
+                "speed": "⚡",
+                "accuracy": "⭐⭐⭐",
+                "size": "~400 MB",
+                "requires": "transformers package"
+            },
+            {
+                "name": "rmbg",
+                "description": "Balanced model",
+                "speed": "⚡⚡",
+                "accuracy": "⭐⭐⭐",
+                "size": "~200 MB",
+                "requires": "transformers package"
+            }
+        ],
+        "default": "u2netp"
+    }
+
+
+@app.post("/segment")
+async def segment_image(
+    file: UploadFile = File(..., description="Image file to segment"),
+    model: str = Form("u2netp", description="Model to use: u2netp, birefnet, or rmbg"),
+    threshold: float = Form(0.5, description="Segmentation threshold (0.0-1.0)", ge=0.0, le=1.0)
+):
+    """
+    Segment image and return PNG with transparent background.
+    
+    Returns: PNG image with transparency
+    """
+    try:
+        # Validate model
+        if model not in ["u2netp", "birefnet", "rmbg"]:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid model: {model}. Choose from: u2netp, birefnet, rmbg"
+            )
+        
+        # Read image
+        contents = await file.read()
+        nparr = np.frombuffer(contents, np.uint8)
+        image = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        
+        if image is None:
+            raise HTTPException(status_code=400, detail="Invalid image file")
+        
+        # Get segmenter
+        segmenter = get_segmenter(model)
+        
+        # Segment image
+        logger.info(f"Segmenting with model={model}, threshold={threshold}")
+        _, rgba = segmenter.segment(image, threshold=threshold, return_type="rgba")
+        
+        if rgba is None:
+            raise HTTPException(status_code=500, detail="Segmentation failed")
+        
+        # Convert to bytes
+        img_byte_arr = io.BytesIO()
+        rgba.save(img_byte_arr, format='PNG')
+        img_byte_arr.seek(0)
+        
+        logger.info("Segmentation successful")
+        return Response(
+            content=img_byte_arr.getvalue(),
+            media_type="image/png",
+            headers={
+                "Content-Disposition": f"attachment; filename=segmented_{file.filename}"
+            }
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in segmentation: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/segment/mask")
+async def segment_mask(
+    file: UploadFile = File(..., description="Image file to segment"),
+    model: str = Form("u2netp", description="Model to use"),
+    threshold: float = Form(0.5, description="Segmentation threshold (0.0-1.0)", ge=0.0, le=1.0)
+):
+    """
+    Segment image and return binary mask only.
+    
+    Returns: PNG image (binary mask - black and white)
+    """
+    try:
+        # Validate model
+        if model not in ["u2netp", "birefnet", "rmbg"]:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid model: {model}. Choose from: u2netp, birefnet, rmbg"
+            )
+        
+        # Read image
+        contents = await file.read()
+        nparr = np.frombuffer(contents, np.uint8)
+        image = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        
+        if image is None:
+            raise HTTPException(status_code=400, detail="Invalid image file")
+        
+        # Get segmenter
+        segmenter = get_segmenter(model)
+        
+        # Segment image
+        logger.info(f"Generating mask with model={model}, threshold={threshold}")
+        mask, _ = segmenter.segment(image, threshold=threshold, return_type="mask")
+        
+        if mask is None:
+            raise HTTPException(status_code=500, detail="Segmentation failed")
+        
+        # Convert to PNG
+        _, buffer = cv2.imencode('.png', mask)
+        
+        logger.info("Mask generation successful")
+        return Response(
+            content=buffer.tobytes(),
+            media_type="image/png",
+            headers={
+                "Content-Disposition": f"attachment; filename=mask_{file.filename}"
+            }
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in mask generation: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/segment/base64")
+async def segment_base64(
+    file: UploadFile = File(..., description="Image file to segment"),
+    model: str = Form("u2netp", description="Model to use"),
+    threshold: float = Form(0.5, description="Segmentation threshold (0.0-1.0)", ge=0.0, le=1.0),
+    return_type: str = Form("rgba", description="Return type: rgba, mask, or both")
+):
+    """
+    Segment image and return base64 encoded results.
+    
+    Returns: JSON with base64 encoded images
+    """
+    try:
+        # Validate inputs
+        if model not in ["u2netp", "birefnet", "rmbg"]:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid model: {model}. Choose from: u2netp, birefnet, rmbg"
+            )
+        
+        if return_type not in ["rgba", "mask", "both"]:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid return_type: {return_type}. Choose from: rgba, mask, both"
+            )
+        
+        # Read image
+        contents = await file.read()
+        nparr = np.frombuffer(contents, np.uint8)
+        image = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        
+        if image is None:
+            raise HTTPException(status_code=400, detail="Invalid image file")
+        
+        # Get segmenter
+        segmenter = get_segmenter(model)
+        
+        # Segment image
+        logger.info(f"Segmenting (base64) with model={model}, threshold={threshold}, return_type={return_type}")
+        mask, rgba = segmenter.segment(image, threshold=threshold, return_type=return_type)
+        
+        # Prepare response
+        response = {
+            "success": True,
+            "model": model,
+            "threshold": threshold
+        }
+        
+        # Encode mask if requested
+        if return_type in ["mask", "both"] and mask is not None:
+            _, buffer = cv2.imencode('.png', mask)
+            mask_base64 = base64.b64encode(buffer).decode('utf-8')
+            response["mask"] = f"data:image/png;base64,{mask_base64}"
+        
+        # Encode RGBA if requested
+        if return_type in ["rgba", "both"] and rgba is not None:
+            img_byte_arr = io.BytesIO()
+            rgba.save(img_byte_arr, format='PNG')
+            rgba_base64 = base64.b64encode(img_byte_arr.getvalue()).decode('utf-8')
+            response["rgba"] = f"data:image/png;base64,{rgba_base64}"
+        
+        logger.info("Base64 encoding successful")
+        return JSONResponse(content=response)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in base64 encoding: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/segment/batch")
+async def segment_batch(
+    files: list[UploadFile] = File(..., description="Multiple image files"),
+    model: str = Form("u2netp", description="Model to use"),
+    threshold: float = Form(0.5, description="Segmentation threshold (0.0-1.0)", ge=0.0, le=1.0)
+):
+    """
+    Segment multiple images and return base64 encoded results.
+    
+    Returns: JSON with array of base64 encoded images
+    """
+    try:
+        # Validate model
+        if model not in ["u2netp", "birefnet", "rmbg"]:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid model: {model}. Choose from: u2netp, birefnet, rmbg"
+            )
+        
+        # Limit batch size
+        if len(files) > 10:
+            raise HTTPException(
+                status_code=400,
+                detail="Maximum batch size is 10 images"
+            )
+        
+        # Get segmenter
+        segmenter = get_segmenter(model)
+        
+        results = []
+        
+        for idx, file in enumerate(files):
+            try:
+                # Read image
+                contents = await file.read()
+                nparr = np.frombuffer(contents, np.uint8)
+                image = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+                
+                if image is None:
+                    results.append({
+                        "filename": file.filename,
+                        "success": False,
+                        "error": "Invalid image file"
+                    })
+                    continue
+                
+                # Segment
+                logger.info(f"Processing batch image {idx+1}/{len(files)}: {file.filename}")
+                _, rgba = segmenter.segment(image, threshold=threshold, return_type="rgba")
+                
+                # Encode to base64
+                img_byte_arr = io.BytesIO()
+                rgba.save(img_byte_arr, format='PNG')
+                rgba_base64 = base64.b64encode(img_byte_arr.getvalue()).decode('utf-8')
+                
+                results.append({
+                    "filename": file.filename,
+                    "success": True,
+                    "rgba": f"data:image/png;base64,{rgba_base64}"
+                })
+                
+            except Exception as e:
+                logger.error(f"Error processing {file.filename}: {e}")
+                results.append({
+                    "filename": file.filename,
+                    "success": False,
+                    "error": str(e)
+                })
+        
+        logger.info(f"Batch processing complete: {len(results)} images")
+        return JSONResponse(content={
+            "total": len(files),
+            "results": results,
+            "model": model,
+            "threshold": threshold
+        })
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in batch processing: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+    import uvicorn
+    
+    # For local development
+    uvicorn.run(
+        "app:app",
+        host="0.0.0.0",
+        port=7860,
+        reload=True
+    )

binary_segmentation.py

@@ -0,0 +1,398 @@
+"""
+Binary Image Segmentation Tool
+A lightweight, professional implementation for foreground object segmentation.
+
+Supports multiple models:
+- U2NETP (fastest, 1.1M params)
+- BiRefNet (best accuracy, larger model)
+- RMBG (good balance)
+"""
+
+import os
+import logging
+from pathlib import Path
+from typing import Literal, Tuple, Optional
+import numpy as np
+import torch
+from PIL import Image
+from torchvision import transforms
+import cv2
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Device configuration
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+logger.info(f"Using device: {DEVICE}")
+
+
+class U2NETP(torch.nn.Module):
+    """U2-Net Portrait (U2NETP) - Lightweight segmentation model"""
+    
+    def __init__(self, in_ch=3, out_ch=1):
+        super(U2NETP, self).__init__()
+        
+        # Encoder
+        self.stage1 = self._make_stage(in_ch, 16, 64)
+        self.pool12 = torch.nn.MaxPool2d(2, stride=2, ceil_mode=True)
+        
+        self.stage2 = self._make_stage(64, 16, 64)
+        self.pool23 = torch.nn.MaxPool2d(2, stride=2, ceil_mode=True)
+        
+        self.stage3 = self._make_stage(64, 16, 64)
+        self.pool34 = torch.nn.MaxPool2d(2, stride=2, ceil_mode=True)
+        
+        self.stage4 = self._make_stage(64, 16, 64)
+        
+        # Bridge
+        self.stage5 = self._make_stage(64, 16, 64)
+        
+        # Decoder
+        self.stage4d = self._make_stage(128, 16, 64)
+        self.stage3d = self._make_stage(128, 16, 64)
+        self.stage2d = self._make_stage(128, 16, 64)
+        self.stage1d = self._make_stage(128, 16, 64)
+        
+        # Side outputs
+        self.side1 = torch.nn.Conv2d(64, out_ch, 3, padding=1)
+        self.side2 = torch.nn.Conv2d(64, out_ch, 3, padding=1)
+        self.side3 = torch.nn.Conv2d(64, out_ch, 3, padding=1)
+        self.side4 = torch.nn.Conv2d(64, out_ch, 3, padding=1)
+        self.side5 = torch.nn.Conv2d(64, out_ch, 3, padding=1)
+        
+        # Output fusion
+        self.outconv = torch.nn.Conv2d(5 * out_ch, out_ch, 1)
+    
+    def _make_stage(self, in_ch, mid_ch, out_ch):
+        return torch.nn.Sequential(
+            torch.nn.Conv2d(in_ch, mid_ch, 3, padding=1),
+            torch.nn.ReLU(inplace=True),
+            torch.nn.Conv2d(mid_ch, mid_ch, 3, padding=1),
+            torch.nn.ReLU(inplace=True),
+            torch.nn.Conv2d(mid_ch, out_ch, 3, padding=1),
+            torch.nn.ReLU(inplace=True)
+        )
+    
+    def forward(self, x):
+        hx = x
+        
+        # Encoder
+        hx1 = self.stage1(hx)
+        hx = self.pool12(hx1)
+        
+        hx2 = self.stage2(hx)
+        hx = self.pool23(hx2)
+        
+        hx3 = self.stage3(hx)
+        hx = self.pool34(hx3)
+        
+        hx4 = self.stage4(hx)
+        hx5 = self.stage5(hx4)
+        
+        # Decoder
+        hx4d = self.stage4d(torch.cat((hx5, hx4), 1))
+        hx4dup = torch.nn.functional.interpolate(hx4d, scale_factor=2, mode='bilinear', align_corners=True)
+        
+        hx3d = self.stage3d(torch.cat((hx4dup, hx3), 1))
+        hx3dup = torch.nn.functional.interpolate(hx3d, scale_factor=2, mode='bilinear', align_corners=True)
+        
+        hx2d = self.stage2d(torch.cat((hx3dup, hx2), 1))
+        hx2dup = torch.nn.functional.interpolate(hx2d, scale_factor=2, mode='bilinear', align_corners=True)
+        
+        hx1d = self.stage1d(torch.cat((hx2dup, hx1), 1))
+        
+        # Side outputs
+        d1 = self.side1(hx1d)
+        d2 = torch.nn.functional.interpolate(self.side2(hx2d), size=d1.shape[2:], mode='bilinear', align_corners=True)
+        d3 = torch.nn.functional.interpolate(self.side3(hx3d), size=d1.shape[2:], mode='bilinear', align_corners=True)
+        d4 = torch.nn.functional.interpolate(self.side4(hx4d), size=d1.shape[2:], mode='bilinear', align_corners=True)
+        d5 = torch.nn.functional.interpolate(self.side5(hx5), size=d1.shape[2:], mode='bilinear', align_corners=True)
+        
+        # Fusion
+        d0 = self.outconv(torch.cat((d1, d2, d3, d4, d5), 1))
+        
+        return torch.sigmoid(d0), torch.sigmoid(d1), torch.sigmoid(d2), torch.sigmoid(d3), torch.sigmoid(d4), torch.sigmoid(d5)
+
+
+class BinarySegmenter:
+    """
+    Professional binary segmentation tool with multiple model backends.
+    
+    Args:
+        model_type: Choice of segmentation model
+        cache_dir: Directory to cache downloaded models
+    """
+    
+    def __init__(
+        self,
+        model_type: Literal["u2netp", "birefnet", "rmbg"] = "u2netp",
+        cache_dir: str = "./.model_cache"
+    ):
+        self.model_type = model_type
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(exist_ok=True)
+        
+        self.model = None
+        self.transform = None
+        self._load_model()
+    
+    def _load_model(self):
+        """Load the specified segmentation model"""
+        logger.info(f"Loading {self.model_type} model...")
+        
+        if self.model_type == "u2netp":
+            self._load_u2netp()
+        elif self.model_type == "birefnet":
+            self._load_birefnet()
+        elif self.model_type == "rmbg":
+            self._load_rmbg()
+        else:
+            raise ValueError(f"Unknown model type: {self.model_type}")
+        
+        self.model.to(DEVICE)
+        self.model.eval()
+        logger.info(f"{self.model_type} loaded successfully")
+    
+    def _load_u2netp(self):
+        """Load U2NETP model (1.1M parameters, fastest)"""
+        self.model = U2NETP(3, 1)
+        
+        # Try to load pretrained weights
+        model_path = self.cache_dir / "u2netp.pth"
+        
+        if model_path.exists():
+            logger.info(f"Loading weights from {model_path}")
+            self.model.load_state_dict(
+                torch.load(model_path, map_location=DEVICE)
+            )
+        else:
+            logger.warning(f"No pretrained weights found at {model_path}")
+            logger.warning("Download from: https://github.com/xuebinqin/U-2-Net")
+        
+        # Standard ImageNet normalization
+        self.transform = transforms.Compose([
+            transforms.Resize((320, 320)),
+            transforms.ToTensor(),
+            transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])
+        ])
+    
+    def _load_birefnet(self):
+        """Load BiRefNet model (best accuracy, larger)"""
+        try:
+            from transformers import AutoModelForImageSegmentation
+            
+            self.model = AutoModelForImageSegmentation.from_pretrained(
+                'ZhengPeng7/BiRefNet',
+                trust_remote_code=True,
+                cache_dir=str(self.cache_dir)
+            )
+            
+            self.transform = transforms.Compose([
+                transforms.Resize((1024, 1024)),
+                transforms.ToTensor(),
+                transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])
+            ])
+        except ImportError:
+            raise ImportError("BiRefNet requires: pip install transformers")
+    
+    def _load_rmbg(self):
+        """Load RMBG model (good balance)"""
+        try:
+            from transformers import AutoModelForImageSegmentation
+            
+            self.model = AutoModelForImageSegmentation.from_pretrained(
+                'briaai/RMBG-1.4',
+                trust_remote_code=True,
+                cache_dir=str(self.cache_dir)
+            )
+            
+            self.transform = transforms.Compose([
+                transforms.Resize((1024, 1024)),
+                transforms.ToTensor(),
+                transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])
+            ])
+        except ImportError:
+            raise ImportError("RMBG requires: pip install transformers")
+    
+    def segment(
+        self,
+        image: np.ndarray,
+        threshold: float = 0.5,
+        return_type: Literal["mask", "rgba", "both"] = "mask"
+    ) -> Tuple[Optional[np.ndarray], Optional[Image.Image]]:
+        """
+        Segment foreground object from image.
+        
+        Args:
+            image: Input image as numpy array (H, W, 3) in RGB or BGR
+            threshold: Threshold for binary mask (0-1)
+            return_type: What to return - "mask", "rgba", or "both"
+        
+        Returns:
+            Tuple of (binary_mask, rgba_image) based on return_type
+        """
+        # Convert BGR to RGB if needed
+        if len(image.shape) == 3 and image.shape[2] == 3:
+            if image[0, 0, 0] != image[0, 0, 2]:  # Simple heuristic
+                image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+            else:
+                image_rgb = image
+        else:
+            raise ValueError("Input must be a color image (H, W, 3)")
+        
+        # Convert to PIL
+        image_pil = Image.fromarray(image_rgb)
+        original_size = image_pil.size
+        
+        # Transform
+        input_tensor = self.transform(image_pil).unsqueeze(0).to(DEVICE)
+        
+        # Inference
+        with torch.no_grad():
+            if self.model_type == "u2netp":
+                outputs = self.model(input_tensor)
+                pred = outputs[0]  # Main output
+            else:  # birefnet or rmbg
+                pred = self.model(input_tensor)[-1].sigmoid()
+        
+        # Post-process
+        pred = pred.squeeze().cpu().numpy()
+        
+        # Resize to original
+        pred_resized = cv2.resize(pred, original_size, interpolation=cv2.INTER_LINEAR)
+        
+        # Normalize to 0-255
+        pred_normalized = ((pred_resized - pred_resized.min()) / 
+                          (pred_resized.max() - pred_resized.min() + 1e-8) * 255)
+        
+        # Create binary mask
+        binary_mask = (pred_normalized > (threshold * 255)).astype(np.uint8) * 255
+        
+        # Optional: Morphological operations for cleaner mask
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+        binary_mask = cv2.morphologyEx(binary_mask, cv2.MORPH_CLOSE, kernel)
+        binary_mask = cv2.morphologyEx(binary_mask, cv2.MORPH_OPEN, kernel)
+        
+        # Create RGBA if needed
+        rgba_image = None
+        if return_type in ["rgba", "both"]:
+            # Create 4-channel image
+            rgba = np.dstack([image_rgb, binary_mask])
+            rgba_image = Image.fromarray(rgba, mode='RGBA')
+        
+        # Return based on type
+        if return_type == "mask":
+            return binary_mask, None
+        elif return_type == "rgba":
+            return None, rgba_image
+        else:  # both
+            return binary_mask, rgba_image
+    
+    def batch_segment(
+        self,
+        images: list[np.ndarray],
+        threshold: float = 0.5,
+        return_type: Literal["mask", "rgba", "both"] = "mask"
+    ) -> list:
+        """
+        Segment multiple images in batch.
+        
+        Args:
+            images: List of input images
+            threshold: Threshold for binary masks
+            return_type: What to return for each image
+        
+        Returns:
+            List of segmentation results
+        """
+        results = []
+        for i, img in enumerate(images):
+            logger.info(f"Processing image {i+1}/{len(images)}")
+            result = self.segment(img, threshold, return_type)
+            results.append(result)
+        return results
+
+
+def segment_image_file(
+    input_path: str,
+    output_path: str,
+    model_type: str = "u2netp",
+    threshold: float = 0.5,
+    save_rgba: bool = True
+):
+    """
+    Convenience function to segment an image file.
+    
+    Args:
+        input_path: Path to input image
+        output_path: Path to save output (mask or RGBA)
+        model_type: Model to use
+        threshold: Segmentation threshold
+        save_rgba: If True, save RGBA; if False, save binary mask
+    """
+    # Load image
+    image = cv2.imread(input_path)
+    if image is None:
+        raise FileNotFoundError(f"Could not load image: {input_path}")
+    
+    # Create segmenter
+    segmenter = BinarySegmenter(model_type=model_type)
+    
+    # Segment
+    return_type = "rgba" if save_rgba else "mask"
+    mask, rgba = segmenter.segment(image, threshold, return_type)
+    
+    # Save
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    if save_rgba and rgba is not None:
+        rgba.save(output_path)
+        logger.info(f"Saved RGBA to: {output_path}")
+    elif mask is not None:
+        cv2.imwrite(str(output_path), mask)
+        logger.info(f"Saved mask to: {output_path}")
+    
+    return str(output_path)
+
+
+# Example usage
+if __name__ == "__main__":
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Binary image segmentation")
+    parser.add_argument("input", help="Input image path")
+    parser.add_argument("output", help="Output path")
+    parser.add_argument(
+        "--model",
+        choices=["u2netp", "birefnet", "rmbg"],
+        default="u2netp",
+        help="Segmentation model"
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.5,
+        help="Segmentation threshold (0-1)"
+    )
+    parser.add_argument(
+        "--format",
+        choices=["mask", "rgba"],
+        default="rgba",
+        help="Output format"
+    )
+    
+    args = parser.parse_args()
+    
+    # Process
+    segment_image_file(
+        args.input,
+        args.output,
+        model_type=args.model,
+        threshold=args.threshold,
+        save_rgba=(args.format == "rgba")
+    )

client_examples.py

@@ -0,0 +1,396 @@
+"""
+API Client Examples for Binary Segmentation Service
+
+These examples show how to interact with the FastAPI service
+from Python, JavaScript, and curl.
+"""
+
+import requests
+import base64
+import json
+from pathlib import Path
+
+
+# =============================================================================
+# Python Client Examples
+# =============================================================================
+
+class SegmentationClient:
+    """Python client for segmentation API"""
+    
+    def __init__(self, base_url: str = "http://localhost:7860"):
+        self.base_url = base_url.rstrip('/')
+    
+    def segment_image(
+        self,
+        image_path: str,
+        output_path: str,
+        model: str = "u2netp",
+        threshold: float = 0.5
+    ):
+        """
+        Segment image and save as PNG with transparency
+        
+        Args:
+            image_path: Path to input image
+            output_path: Path to save output PNG
+            model: Model to use (u2netp, birefnet, rmbg)
+            threshold: Segmentation threshold (0.0-1.0)
+        """
+        with open(image_path, 'rb') as f:
+            files = {'file': f}
+            data = {
+                'model': model,
+                'threshold': threshold
+            }
+            
+            response = requests.post(
+                f"{self.base_url}/segment",
+                files=files,
+                data=data
+            )
+            
+            response.raise_for_status()
+            
+            with open(output_path, 'wb') as out:
+                out.write(response.content)
+            
+            print(f"✓ Saved to: {output_path}")
+    
+    def get_mask(
+        self,
+        image_path: str,
+        output_path: str,
+        model: str = "u2netp",
+        threshold: float = 0.5
+    ):
+        """Get binary mask only"""
+        with open(image_path, 'rb') as f:
+            files = {'file': f}
+            data = {
+                'model': model,
+                'threshold': threshold
+            }
+            
+            response = requests.post(
+                f"{self.base_url}/segment/mask",
+                files=files,
+                data=data
+            )
+            
+            response.raise_for_status()
+            
+            with open(output_path, 'wb') as out:
+                out.write(response.content)
+            
+            print(f"✓ Mask saved to: {output_path}")
+    
+    def segment_base64(
+        self,
+        image_path: str,
+        model: str = "u2netp",
+        threshold: float = 0.5,
+        return_type: str = "both"
+    ):
+        """
+        Get segmentation results as base64
+        
+        Returns:
+            dict with 'mask' and/or 'rgba' as base64 strings
+        """
+        with open(image_path, 'rb') as f:
+            files = {'file': f}
+            data = {
+                'model': model,
+                'threshold': threshold,
+                'return_type': return_type
+            }
+            
+            response = requests.post(
+                f"{self.base_url}/segment/base64",
+                files=files,
+                data=data
+            )
+            
+            response.raise_for_status()
+            return response.json()
+    
+    def batch_segment(
+        self,
+        image_paths: list[str],
+        model: str = "u2netp",
+        threshold: float = 0.5
+    ):
+        """
+        Segment multiple images
+        
+        Args:
+            image_paths: List of paths to images (max 10)
+            
+        Returns:
+            dict with results for each image
+        """
+        files = [
+            ('files', open(path, 'rb'))
+            for path in image_paths
+        ]
+        
+        data = {
+            'model': model,
+            'threshold': threshold
+        }
+        
+        try:
+            response = requests.post(
+                f"{self.base_url}/segment/batch",
+                files=files,
+                data=data
+            )
+            
+            response.raise_for_status()
+            return response.json()
+        finally:
+            # Close all file handles
+            for _, f in files:
+                f.close()
+    
+    def list_models(self):
+        """List available models"""
+        response = requests.get(f"{self.base_url}/models")
+        response.raise_for_status()
+        return response.json()
+    
+    def health_check(self):
+        """Check service health"""
+        response = requests.get(f"{self.base_url}/health")
+        response.raise_for_status()
+        return response.json()
+
+
+# =============================================================================
+# Usage Examples
+# =============================================================================
+
+def example_basic():
+    """Basic usage"""
+    client = SegmentationClient("http://localhost:7860")
+    
+    # Segment image
+    client.segment_image(
+        image_path="input.jpg",
+        output_path="output.png",
+        model="u2netp",
+        threshold=0.5
+    )
+
+
+def example_mask():
+    """Get binary mask"""
+    client = SegmentationClient("http://localhost:7860")
+    
+    client.get_mask(
+        image_path="input.jpg",
+        output_path="mask.png",
+        model="u2netp",
+        threshold=0.5
+    )
+
+
+def example_base64():
+    """Get base64 results"""
+    client = SegmentationClient("http://localhost:7860")
+    
+    result = client.segment_base64(
+        image_path="input.jpg",
+        return_type="both"
+    )
+    
+    # Save base64 images
+    if 'rgba' in result:
+        # Remove data URL prefix
+        rgba_data = result['rgba'].split(',')[1]
+        with open('output_rgba.png', 'wb') as f:
+            f.write(base64.b64decode(rgba_data))
+    
+    if 'mask' in result:
+        mask_data = result['mask'].split(',')[1]
+        with open('output_mask.png', 'wb') as f:
+            f.write(base64.b64decode(mask_data))
+
+
+def example_batch():
+    """Process multiple images"""
+    client = SegmentationClient("http://localhost:7860")
+    
+    results = client.batch_segment(
+        image_paths=["image1.jpg", "image2.jpg", "image3.jpg"],
+        model="u2netp",
+        threshold=0.5
+    )
+    
+    # Save results
+    for i, result in enumerate(results['results']):
+        if result['success']:
+            rgba_data = result['rgba'].split(',')[1]
+            with open(f'output_{i}.png', 'wb') as f:
+                f.write(base64.b64decode(rgba_data))
+
+
+def example_models():
+    """List available models"""
+    client = SegmentationClient("http://localhost:7860")
+    
+    models = client.list_models()
+    print(json.dumps(models, indent=2))
+
+
+# =============================================================================
+# JavaScript Examples (for frontend)
+# =============================================================================
+
+JAVASCRIPT_EXAMPLES = """
+// Example 1: Basic fetch
+async function segmentImage(file) {
+    const formData = new FormData();
+    formData.append('file', file);
+    formData.append('model', 'u2netp');
+    formData.append('threshold', '0.5');
+    
+    const response = await fetch('/segment', {
+        method: 'POST',
+        body: formData
+    });
+    
+    const blob = await response.blob();
+    return URL.createObjectURL(blob);
+}
+
+// Example 2: Get base64
+async function segmentBase64(file) {
+    const formData = new FormData();
+    formData.append('file', file);
+    formData.append('model', 'u2netp');
+    formData.append('threshold', '0.5');
+    formData.append('return_type', 'rgba');
+    
+    const response = await fetch('/segment/base64', {
+        method: 'POST',
+        body: formData
+    });
+    
+    const data = await response.json();
+    return data.rgba; // data:image/png;base64,...
+}
+
+// Example 3: Batch processing
+async function segmentBatch(files) {
+    const formData = new FormData();
+    
+    for (const file of files) {
+        formData.append('files', file);
+    }
+    formData.append('model', 'u2netp');
+    formData.append('threshold', '0.5');
+    
+    const response = await fetch('/segment/batch', {
+        method: 'POST',
+        body: formData
+    });
+    
+    return await response.json();
+}
+
+// Example 4: With progress
+async function segmentWithProgress(file, onProgress) {
+    const formData = new FormData();
+    formData.append('file', file);
+    formData.append('model', 'u2netp');
+    formData.append('threshold', '0.5');
+    
+    const xhr = new XMLHttpRequest();
+    
+    return new Promise((resolve, reject) => {
+        xhr.upload.addEventListener('progress', (e) => {
+            if (e.lengthComputable) {
+                onProgress(e.loaded / e.total);
+            }
+        });
+        
+        xhr.addEventListener('load', () => {
+            if (xhr.status === 200) {
+                const blob = xhr.response;
+                resolve(URL.createObjectURL(blob));
+            } else {
+                reject(new Error('Upload failed'));
+            }
+        });
+        
+        xhr.addEventListener('error', () => reject(new Error('Upload failed')));
+        
+        xhr.open('POST', '/segment');
+        xhr.responseType = 'blob';
+        xhr.send(formData);
+    });
+}
+"""
+
+
+# =============================================================================
+# cURL Examples
+# =============================================================================
+
+CURL_EXAMPLES = """
+# Example 1: Basic segmentation
+curl -X POST "http://localhost:7860/segment" \\
+  -F "file=@input.jpg" \\
+  -F "model=u2netp" \\
+  -F "threshold=0.5" \\
+  --output result.png
+
+# Example 2: Get mask
+curl -X POST "http://localhost:7860/segment/mask" \\
+  -F "file=@input.jpg" \\
+  -F "model=u2netp" \\
+  -F "threshold=0.5" \\
+  --output mask.png
+
+# Example 3: Get base64 JSON
+curl -X POST "http://localhost:7860/segment/base64" \\
+  -F "file=@input.jpg" \\
+  -F "model=u2netp" \\
+  -F "threshold=0.5" \\
+  -F "return_type=both"
+
+# Example 4: Batch processing
+curl -X POST "http://localhost:7860/segment/batch" \\
+  -F "files=@image1.jpg" \\
+  -F "files=@image2.jpg" \\
+  -F "files=@image3.jpg" \\
+  -F "model=u2netp" \\
+  -F "threshold=0.5"
+
+# Example 5: List models
+curl -X GET "http://localhost:7860/models"
+
+# Example 6: Health check
+curl -X GET "http://localhost:7860/health"
+"""
+
+
+if __name__ == "__main__":
+    print("API Client Examples")
+    print("=" * 50)
+    print("\nPython Examples:")
+    print("  example_basic()     - Basic segmentation")
+    print("  example_mask()      - Get binary mask")
+    print("  example_base64()    - Get base64 results")
+    print("  example_batch()     - Batch processing")
+    print("  example_models()    - List models")
+    print("\nUncomment the example you want to run!")
+    
+    # Uncomment to run:
+    # example_basic()
+    # example_mask()
+    # example_base64()
+    # example_batch()
+    # example_models()

index.html

@@ -0,0 +1,505 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Background Removal - AI Segmentation</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            min-height: 100vh;
+            padding: 20px;
+        }
+
+        .container {
+            max-width: 1200px;
+            margin: 0 auto;
+            background: white;
+            border-radius: 20px;
+            box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+            overflow: hidden;
+        }
+
+        header {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 30px;
+            text-align: center;
+        }
+
+        header h1 {
+            font-size: 2.5em;
+            margin-bottom: 10px;
+        }
+
+        header p {
+            font-size: 1.1em;
+            opacity: 0.9;
+        }
+
+        .content {
+            padding: 40px;
+        }
+
+        .upload-section {
+            text-align: center;
+            margin-bottom: 40px;
+        }
+
+        .upload-zone {
+            border: 3px dashed #667eea;
+            border-radius: 15px;
+            padding: 60px 40px;
+            background: #f8f9ff;
+            cursor: pointer;
+            transition: all 0.3s;
+            position: relative;
+        }
+
+        .upload-zone:hover {
+            border-color: #764ba2;
+            background: #f0f2ff;
+        }
+
+        .upload-zone.dragover {
+            border-color: #764ba2;
+            background: #e8ebff;
+            transform: scale(1.02);
+        }
+
+        .upload-icon {
+            font-size: 4em;
+            color: #667eea;
+            margin-bottom: 20px;
+        }
+
+        .upload-text {
+            font-size: 1.2em;
+            color: #333;
+            margin-bottom: 10px;
+        }
+
+        .upload-hint {
+            color: #666;
+            font-size: 0.9em;
+        }
+
+        input[type="file"] {
+            display: none;
+        }
+
+        .controls {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+            gap: 20px;
+            margin-bottom: 30px;
+        }
+
+        .control-group {
+            display: flex;
+            flex-direction: column;
+        }
+
+        .control-group label {
+            font-weight: 600;
+            margin-bottom: 8px;
+            color: #333;
+        }
+
+        select, input[type="range"] {
+            padding: 10px;
+            border: 2px solid #ddd;
+            border-radius: 8px;
+            font-size: 1em;
+            transition: border-color 0.3s;
+        }
+
+        select:focus, input[type="range"]:focus {
+            outline: none;
+            border-color: #667eea;
+        }
+
+        .threshold-value {
+            display: inline-block;
+            background: #667eea;
+            color: white;
+            padding: 4px 12px;
+            border-radius: 20px;
+            font-size: 0.9em;
+            margin-left: 10px;
+        }
+
+        .btn {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            border: none;
+            padding: 15px 40px;
+            font-size: 1.1em;
+            font-weight: 600;
+            border-radius: 10px;
+            cursor: pointer;
+            transition: all 0.3s;
+            box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
+        }
+
+        .btn:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 6px 20px rgba(102, 126, 234, 0.6);
+        }
+
+        .btn:active {
+            transform: translateY(0);
+        }
+
+        .btn:disabled {
+            opacity: 0.5;
+            cursor: not-allowed;
+        }
+
+        .results {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 30px;
+            margin-top: 40px;
+        }
+
+        .result-card {
+            background: #f8f9ff;
+            border-radius: 15px;
+            padding: 20px;
+            box-shadow: 0 4px 10px rgba(0,0,0,0.1);
+        }
+
+        .result-card h3 {
+            color: #333;
+            margin-bottom: 15px;
+            font-size: 1.2em;
+        }
+
+        .result-card img {
+            width: 100%;
+            border-radius: 10px;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+        }
+
+        .download-btn {
+            display: block;
+            width: 100%;
+            margin-top: 15px;
+            background: #10b981;
+            color: white;
+            padding: 10px;
+            text-align: center;
+            border-radius: 8px;
+            text-decoration: none;
+            font-weight: 600;
+            transition: background 0.3s;
+        }
+
+        .download-btn:hover {
+            background: #059669;
+        }
+
+        .loading {
+            text-align: center;
+            padding: 40px;
+            display: none;
+        }
+
+        .loading.active {
+            display: block;
+        }
+
+        .spinner {
+            border: 4px solid #f3f4f6;
+            border-top: 4px solid #667eea;
+            border-radius: 50%;
+            width: 50px;
+            height: 50px;
+            animation: spin 1s linear infinite;
+            margin: 0 auto 20px;
+        }
+
+        @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+        }
+
+        .error {
+            background: #fee;
+            color: #c33;
+            padding: 15px;
+            border-radius: 8px;
+            margin-top: 20px;
+            display: none;
+        }
+
+        .error.active {
+            display: block;
+        }
+
+        .model-info {
+            background: #e8f4f8;
+            padding: 15px;
+            border-radius: 8px;
+            margin-top: 10px;
+            font-size: 0.9em;
+            color: #555;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <header>
+            <h1>🎨 AI Background Removal</h1>
+            <p>Remove backgrounds from images using advanced AI models</p>
+        </header>
+
+        <div class="content">
+            <div class="upload-section">
+                <div class="upload-zone" id="uploadZone">
+                    <div class="upload-icon">📁</div>
+                    <div class="upload-text">Click to upload or drag & drop</div>
+                    <div class="upload-hint">Supports: JPG, PNG, WEBP (Max 10MB)</div>
+                    <input type="file" id="fileInput" accept="image/*">
+                </div>
+            </div>
+
+            <div class="controls">
+                <div class="control-group">
+                    <label for="modelSelect">AI Model</label>
+                    <select id="modelSelect">
+                        <option value="u2netp" selected>U2NETP (Fast & Lightweight)</option>
+                        <option value="birefnet">BiRefNet (Best Quality)</option>
+                        <option value="rmbg">RMBG (Balanced)</option>
+                    </select>
+                    <div class="model-info" id="modelInfo">
+                        ⚡⚡⚡ Speed | ⭐⭐ Quality | 4.7 MB
+                    </div>
+                </div>
+
+                <div class="control-group">
+                    <label for="thresholdRange">
+                        Threshold <span class="threshold-value" id="thresholdValue">0.5</span>
+                    </label>
+                    <input type="range" id="thresholdRange" min="0" max="1" step="0.1" value="0.5">
+                </div>
+
+                <div class="control-group">
+                    <label for="outputType">Output Type</label>
+                    <select id="outputType">
+                        <option value="rgba" selected>Transparent PNG</option>
+                        <option value="mask">Binary Mask</option>
+                        <option value="both">Both</option>
+                    </select>
+                </div>
+            </div>
+
+            <button class="btn" id="processBtn" disabled>Process Image</button>
+
+            <div class="loading" id="loading">
+                <div class="spinner"></div>
+                <p>Processing your image...</p>
+            </div>
+
+            <div class="error" id="error"></div>
+
+            <div class="results" id="results"></div>
+        </div>
+    </div>
+
+    <script>
+        const uploadZone = document.getElementById('uploadZone');
+        const fileInput = document.getElementById('fileInput');
+        const processBtn = document.getElementById('processBtn');
+        const loading = document.getElementById('loading');
+        const error = document.getElementById('error');
+        const results = document.getElementById('results');
+        const modelSelect = document.getElementById('modelSelect');
+        const modelInfo = document.getElementById('modelInfo');
+        const thresholdRange = document.getElementById('thresholdRange');
+        const thresholdValue = document.getElementById('thresholdValue');
+        const outputType = document.getElementById('outputType');
+
+        let selectedFile = null;
+
+        // Model information
+        const modelData = {
+            u2netp: { speed: '⚡⚡⚡', quality: '⭐⭐', size: '4.7 MB' },
+            birefnet: { speed: '⚡', quality: '⭐⭐⭐', size: '~400 MB' },
+            rmbg: { speed: '⚡⚡', quality: '⭐⭐⭐', size: '~200 MB' }
+        };
+
+        // Update model info
+        modelSelect.addEventListener('change', () => {
+            const model = modelData[modelSelect.value];
+            modelInfo.textContent = `${model.speed} Speed | ${model.quality} Quality | ${model.size}`;
+        });
+
+        // Update threshold value
+        thresholdRange.addEventListener('input', () => {
+            thresholdValue.textContent = thresholdRange.value;
+        });
+
+        // Upload zone click
+        uploadZone.addEventListener('click', () => {
+            fileInput.click();
+        });
+
+        // Drag and drop
+        uploadZone.addEventListener('dragover', (e) => {
+            e.preventDefault();
+            uploadZone.classList.add('dragover');
+        });
+
+        uploadZone.addEventListener('dragleave', () => {
+            uploadZone.classList.remove('dragover');
+        });
+
+        uploadZone.addEventListener('drop', (e) => {
+            e.preventDefault();
+            uploadZone.classList.remove('dragover');
+            
+            if (e.dataTransfer.files.length > 0) {
+                handleFile(e.dataTransfer.files[0]);
+            }
+        });
+
+        // File input change
+        fileInput.addEventListener('change', (e) => {
+            if (e.target.files.length > 0) {
+                handleFile(e.target.files[0]);
+            }
+        });
+
+        function handleFile(file) {
+            if (!file.type.startsWith('image/')) {
+                showError('Please select an image file');
+                return;
+            }
+
+            if (file.size > 10 * 1024 * 1024) {
+                showError('File size must be less than 10MB');
+                return;
+            }
+
+            selectedFile = file;
+            processBtn.disabled = false;
+            uploadZone.querySelector('.upload-text').textContent = `Selected: ${file.name}`;
+            uploadZone.querySelector('.upload-icon').textContent = '✅';
+            hideError();
+        }
+
+        // Process button
+        processBtn.addEventListener('click', async () => {
+            if (!selectedFile) return;
+
+            const formData = new FormData();
+            formData.append('file', selectedFile);
+            formData.append('model', modelSelect.value);
+            formData.append('threshold', thresholdRange.value);
+
+            processBtn.disabled = true;
+            loading.classList.add('active');
+            results.innerHTML = '';
+            hideError();
+
+            try {
+                let response;
+                
+                if (outputType.value === 'both') {
+                    // Use base64 endpoint for both outputs
+                    response = await fetch('/segment/base64', {
+                        method: 'POST',
+                        body: formData
+                    });
+
+                    const data = await response.json();
+
+                    if (!response.ok) {
+                        throw new Error(data.detail || 'Processing failed');
+                    }
+
+                    // Display results
+                    results.innerHTML = '';
+
+                    if (data.rgba) {
+                        results.innerHTML += `
+                            <div class="result-card">
+                                <h3>Transparent PNG</h3>
+                                <img src="${data.rgba}" alt="Transparent result">
+                                <a href="${data.rgba}" download="transparent.png" class="download-btn">
+                                    Download PNG
+                                </a>
+                            </div>
+                        `;
+                    }
+
+                    if (data.mask) {
+                        results.innerHTML += `
+                            <div class="result-card">
+                                <h3>Binary Mask</h3>
+                                <img src="${data.mask}" alt="Mask result">
+                                <a href="${data.mask}" download="mask.png" class="download-btn">
+                                    Download Mask
+                                </a>
+                            </div>
+                        `;
+                    }
+
+                } else {
+                    // Use appropriate endpoint
+                    const endpoint = outputType.value === 'mask' ? '/segment/mask' : '/segment';
+                    response = await fetch(endpoint, {
+                        method: 'POST',
+                        body: formData
+                    });
+
+                    if (!response.ok) {
+                        const errorData = await response.json();
+                        throw new Error(errorData.detail || 'Processing failed');
+                    }
+
+                    // Get blob
+                    const blob = await response.blob();
+                    const url = URL.createObjectURL(blob);
+
+                    // Display result
+                    const title = outputType.value === 'mask' ? 'Binary Mask' : 'Transparent PNG';
+                    results.innerHTML = `
+                        <div class="result-card">
+                            <h3>${title}</h3>
+                            <img src="${url}" alt="Result">
+                            <a href="${url}" download="result.png" class="download-btn">
+                                Download Image
+                            </a>
+                        </div>
+                    `;
+                }
+
+            } catch (err) {
+                showError(err.message);
+            } finally {
+                loading.classList.remove('active');
+                processBtn.disabled = false;
+            }
+        });
+
+        function showError(message) {
+            error.textContent = message;
+            error.classList.add('active');
+        }
+
+        function hideError() {
+            error.classList.remove('active');
+        }
+    </script>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,13 @@
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+python-multipart==0.0.6
+torch>=2.0.0
+torchvision>=0.15.0
+numpy>=1.24.0
+opencv-python-headless>=4.8.0
+Pillow>=10.0.0
+
+# Optional: For BiRefNet and RMBG models
+# Uncomment if you want to use these models
+# transformers>=4.30.0
+# huggingface-hub>=0.16.0

test_api.py

@@ -0,0 +1,225 @@
+"""
+Test script for Binary Segmentation API
+
+Run this to verify the API is working correctly.
+"""
+
+import requests
+import sys
+import time
+from pathlib import Path
+
+
+def test_api(base_url: str = "http://localhost:7860"):
+    """Run basic API tests"""
+    
+    print("=" * 60)
+    print("Binary Segmentation API - Test Suite")
+    print("=" * 60)
+    print(f"\nTesting API at: {base_url}\n")
+    
+    # Test 1: Health Check
+    print("Test 1: Health Check")
+    try:
+        response = requests.get(f"{base_url}/health", timeout=5)
+        if response.status_code == 200:
+            print("✓ Health check passed")
+            print(f"  Response: {response.json()}")
+        else:
+            print(f"✗ Health check failed: {response.status_code}")
+            return False
+    except Exception as e:
+        print(f"✗ Health check failed: {e}")
+        print("\n  Make sure the API is running:")
+        print("  python app.py")
+        print("  or")
+        print("  uvicorn app:app --host 0.0.0.0 --port 7860")
+        return False
+    
+    print()
+    
+    # Test 2: List Models
+    print("Test 2: List Models")
+    try:
+        response = requests.get(f"{base_url}/models", timeout=5)
+        if response.status_code == 200:
+            print("✓ Models endpoint working")
+            data = response.json()
+            print(f"  Available models: {len(data.get('models', []))}")
+            for model in data.get('models', []):
+                print(f"    - {model['name']}: {model['description']}")
+        else:
+            print(f"✗ Models endpoint failed: {response.status_code}")
+    except Exception as e:
+        print(f"✗ Models endpoint failed: {e}")
+    
+    print()
+    
+    # Test 3: Create test image
+    print("Test 3: Create Test Image")
+    try:
+        import numpy as np
+        from PIL import Image
+        
+        # Create a simple test image (100x100 red square on white background)
+        img = np.ones((200, 200, 3), dtype=np.uint8) * 255
+        img[50:150, 50:150] = [255, 0, 0]  # Red square
+        
+        test_img = Image.fromarray(img)
+        test_path = Path("test_image.jpg")
+        test_img.save(test_path)
+        
+        print(f"✓ Test image created: {test_path}")
+    except Exception as e:
+        print(f"✗ Failed to create test image: {e}")
+        return False
+    
+    print()
+    
+    # Test 4: Segmentation (if test image exists)
+    if test_path.exists():
+        print("Test 4: Image Segmentation")
+        try:
+            with open(test_path, 'rb') as f:
+                files = {'file': f}
+                data = {
+                    'model': 'u2netp',
+                    'threshold': '0.5'
+                }
+                
+                start_time = time.time()
+                response = requests.post(
+                    f"{base_url}/segment",
+                    files=files,
+                    data=data,
+                    timeout=30
+                )
+                elapsed = time.time() - start_time
+                
+                if response.status_code == 200:
+                    output_path = Path("test_output.png")
+                    with open(output_path, 'wb') as out:
+                        out.write(response.content)
+                    
+                    print(f"✓ Segmentation successful ({elapsed:.2f}s)")
+                    print(f"  Output saved to: {output_path}")
+                    print(f"  Output size: {len(response.content)} bytes")
+                else:
+                    print(f"✗ Segmentation failed: {response.status_code}")
+                    print(f"  Response: {response.text}")
+        except Exception as e:
+            print(f"✗ Segmentation failed: {e}")
+    
+    print()
+    
+    # Test 5: Mask endpoint
+    if test_path.exists():
+        print("Test 5: Binary Mask")
+        try:
+            with open(test_path, 'rb') as f:
+                files = {'file': f}
+                data = {
+                    'model': 'u2netp',
+                    'threshold': '0.5'
+                }
+                
+                response = requests.post(
+                    f"{base_url}/segment/mask",
+                    files=files,
+                    data=data,
+                    timeout=30
+                )
+                
+                if response.status_code == 200:
+                    mask_path = Path("test_mask.png")
+                    with open(mask_path, 'wb') as out:
+                        out.write(response.content)
+                    
+                    print(f"✓ Mask generation successful")
+                    print(f"  Mask saved to: {mask_path}")
+                else:
+                    print(f"✗ Mask generation failed: {response.status_code}")
+        except Exception as e:
+            print(f"✗ Mask generation failed: {e}")
+    
+    print()
+    
+    # Test 6: Base64 endpoint
+    if test_path.exists():
+        print("Test 6: Base64 Output")
+        try:
+            with open(test_path, 'rb') as f:
+                files = {'file': f}
+                data = {
+                    'model': 'u2netp',
+                    'threshold': '0.5',
+                    'return_type': 'both'
+                }
+                
+                response = requests.post(
+                    f"{base_url}/segment/base64",
+                    files=files,
+                    data=data,
+                    timeout=30
+                )
+                
+                if response.status_code == 200:
+                    result = response.json()
+                    print(f"✓ Base64 output successful")
+                    print(f"  Has RGBA: {'rgba' in result}")
+                    print(f"  Has Mask: {'mask' in result}")
+                else:
+                    print(f"✗ Base64 output failed: {response.status_code}")
+        except Exception as e:
+            print(f"✗ Base64 output failed: {e}")
+    
+    print()
+    
+    # Cleanup
+    print("Cleanup:")
+    try:
+        if test_path.exists():
+            test_path.unlink()
+            print(f"  Removed: {test_path}")
+        
+        output_path = Path("test_output.png")
+        if output_path.exists():
+            output_path.unlink()
+            print(f"  Removed: {output_path}")
+        
+        mask_path = Path("test_mask.png")
+        if mask_path.exists():
+            mask_path.unlink()
+            print(f"  Removed: {mask_path}")
+    except Exception as e:
+        print(f"  Warning: Cleanup failed: {e}")
+    
+    print()
+    print("=" * 60)
+    print("Test Suite Complete!")
+    print("=" * 60)
+    
+    return True
+
+
+if __name__ == "__main__":
+    # Get base URL from command line or use default
+    base_url = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:7860"
+    
+    success = test_api(base_url)
+    
+    if success:
+        print("\n✓ All critical tests passed!")
+        print("\nNext steps:")
+        print("1. Open http://localhost:7860 in your browser")
+        print("2. Upload an image and test the web interface")
+        print("3. Deploy to Hugging Face Spaces (see DEPLOYMENT.md)")
+        sys.exit(0)
+    else:
+        print("\n✗ Some tests failed!")
+        print("\nTroubleshooting:")
+        print("1. Make sure the server is running:")
+        print("   uvicorn app:app --host 0.0.0.0 --port 7860")
+        print("2. Check that u2netp.pth is in .model_cache/")
+        print("3. Check logs for errors")
+        sys.exit(1)