README.md

metadata

title: ColorCraft SDXL - Advanced LineArt Controls
emoji: 🎨
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.44.1
app_file: app.py
pinned: false
license: mit
hardware: t4-medium

🎨 ColorCraft SDXL - Advanced LineArt Controls

A professional multi-model line art generator powered by SDXL + ControlNet/T2I-Adapter for creating high-quality coloring book images.

🚀 Core Features

• Multi-Model Architecture: Support for both ControlNet and T2I-Adapter models
• 3 LineArt Models: Standard, Anime-specialized, and TencentARC research models
• Advanced Controls: Fine-tuned parameters for optimal coloring book output
• Storage Efficient: 20GB persistent storage with intelligent caching
• Real-time Monitoring: Live storage status and model loading feedback

🖌️ LineArt Models

Model	Type	Architecture	Specialization
Standard ControlNet	ControlNet	ShermanG/ControlNet-Standard-Lineart-for-SDXL	General purpose
Anime ControlNet	ControlNet	r3gm/controlnet-lineart-anime-sdxl-fp16	Anime-style images
TencentARC T2I-Adapter	T2I-Adapter	TencentARC/t2i-adapter-lineart-sdxl-1.0	Research-grade

🎯 Style Presets

• Ultra Clean: Pure B&W, minimal details, vector art style
• Clean: Clear outlines, simple design, minimal shading
• Detailed: Intricate outlines, fine details, precise lines
• Bold: Strong contrast, thick lines, dramatic effect
• Simple: Basic outlines, easy coloring, child-friendly

🔧 Advanced Controls

📊 Generation Parameters

• Inference Steps: 10-50 (default: 25)
• Guidance Scale: 3-15 (default: 9)
• ControlNet Strength: 0.5-2.0 (default: 1.4)
• Output Resolution: 512-1536px (default: 1024px)

🎨 Processing Options

• Depth Preprocessing: Optional structural guidance with MidasDetector/DPT
• Pure B&W Post-Processing: OpenCV enhancement for stark black/white output
• Negative Prompts: Toggle for quality improvement

📈 Monitoring Panels

• LineArt Preprocessor Output: See the detected line art
• Depth Preprocessor Output: View depth map when enabled
• Storage Status: Monitor cache usage and performance

🏗️ Technical Architecture

🤖 AI/ML Stack

• Base Model: stabilityai/stable-diffusion-xl-base-1.0
• VAE: madebyollin/sdxl-vae-fp16-fix (FP16 optimized)
• Depth Model: diffusers/controlnet-depth-sdxl-1.0
• Preprocessors: controlnet-aux (LineartDetector, MidasDetector)

⚡ Framework Stack

• ML Framework: PyTorch 2.0+
• Diffusion: Diffusers 0.26.3
• Transformers: 4.40.2
• UI: Gradio 4.0+
• Computer Vision: OpenCV 4.8+, Pillow 10.0+

🔄 Pipeline Flow

1. Input: User uploads image via Gradio
2. Model Selection: Choose ControlNet or T2I-Adapter architecture
3. Preprocessing: LineArt detection + optional depth processing
4. Generation: SDXL with LineArt guidance
5. Post-Processing: Optional OpenCV B&W enhancement
6. Output: Multi-panel results with monitoring

💾 Storage Management

• Persistent Cache: 20GB storage for model caching
• On-Demand Loading: Models loaded only when selected
• Intelligent Cleanup: Automatic cache management when space is low
• Multi-Model Caching: Each model cached independently

🔗 API Usage

import requests
import base64
from PIL import Image

def generate_lineart(image_path, model="standard", style="ultra_clean"):
    # Load and encode image
    with open(image_path, "rb") as f:
        image_data = base64.b64encode(f.read()).decode()
    
    # Call ColorCraft SDXL API
    response = requests.post(
        "https://YOUR_USERNAME-colorcraft-sdxl.hf.space/api/predict",
        json={
            "data": [
                f"data:image/jpeg;base64,{image_data}",
                "",  # custom_prompt
                style,  # style_preset
                25,  # num_steps
                9,   # guidance_scale
                1.4, # controlnet_scale
                True,  # use_negative_prompt
                1024,  # output_resolution
                False, # use_depth_preprocessor
                model, # lineart_model
                False  # apply_post_processing
            ]
        }
    )
    
    result = response.json()
    return result["data"]  # [main_image, lineart_preview, depth_preview, status]

# Usage
result = generate_lineart("input.jpg", model="anime", style="clean")

🎯 Use Cases

• Mobile Apps: Multi-model line art generation with quality options
• Art Education: Compare different model approaches for learning
• Research: Test ControlNet vs T2I-Adapter architectures
• Print Services: Generate coloring books with style consistency
• Creative Tools: Professional line art with real-time feedback

🚀 Deployment

Quick Deploy

1. Create HuggingFace Space (Gradio SDK)
2. Upload: app.py, requirements.txt, README.md
3. Set Hardware: T4-medium (16GB VRAM + 20GB storage)
4. Deploy: Available at https://USERNAME-SPACENAME.hf.space

Local Development

# Install dependencies
pip install -r requirements.txt

# Run locally (requires GPU for optimal performance)
python app.py

📊 Performance

• Startup Time: ~2-3 minutes (first load), ~30 seconds (cached)
• Generation Time: 15-30 seconds per image
• Memory Usage: ~12GB VRAM (T4-medium recommended)
• Storage: 20GB persistent recommended for all models

🔬 Model Comparison

Feature	Standard	Anime	TencentARC
Architecture	ControlNet	ControlNet	T2I-Adapter
Training Data	General	Anime-focused	Research dataset
Line Quality	Balanced	Clean/smooth	Technical precision
Best For	All images	Cartoon/anime	Complex scenes

---

Built with ❤️ for the ColorCraft ecosystem