ubuntu-post-install/paintplus/docs/QUICK_START.md

Quick Start Guide

How to Choose the Right AI Model

For Body Parts (Hands, Faces, Bodies)

Use Replicate with realistic-vision model:

AI_PROVIDER=replicate
REPLICATE_API_KEY=your-key-here
REPLICATE_MODEL=realistic-vision

Why: This model is specifically trained on human anatomy and handles difficult features like:

• ✅ Hands (even complex finger positions)
• ✅ Faces and expressions
• ✅ Skin textures
• ✅ Body proportions

Cost: ~$0.020/image

For Removing Objects

Use Replicate with lama model:

AI_PROVIDER=replicate
REPLICATE_MODEL=lama

Why: Designed specifically for inpainting and removal Cost: ~$0.002/image (cheapest!)

For General Edits (Landscapes, Objects, Creative)

Use Replicate with sdxl-inpaint model (default):

AI_PROVIDER=replicate
REPLICATE_MODEL=sdxl-inpaint

Cost: ~$0.025/image

---

Auto-Model Selection

The system automatically picks the best model based on your prompt:

Your Prompt	Auto-Selected Model	Why
"Fix the hand"	realistic-vision	Detects "hand" keyword
"Remove person"	lama	Detects "remove" keyword
"Change sky to sunset"	sdxl-inpaint	General purpose default

You don't need to manually specify models - the auto-selection is optimized for quality and cost!

---

Patch Library: Save and Reuse Parts

What is the Patch Library?

A library where you can save image patches (regions) and reuse them across different images.

Use Cases:

• Save a well-generated hand to reuse later
• Save a perfect face for multiple photos
• Build a collection of good body parts
• Save textures, objects, or backgrounds
• Reuse AI-generated elements that came out great

How to Save a Patch

Option 1: Save AI-Generated Result

After an AI edit completes:

POST /patches/
{
  "name": "Perfect Hand",
  "description": "Well-formed left hand, palm up",
  "source_type": "ai_generated",
  "source_edit_id": 123,
  "category": "hand",
  "tags": "left, palm, realistic"
}

This saves the AI-generated output (patch_out.png) to your library.

Option 2: Save Manual Selection

Select any region from your current image:

POST /patches/
{
  "name": "Good Face",
  "description": "Frontal face with good lighting",
  "source_type": "manual_selection",
  "source_project_id": 456,
  "bbox": {"x": 100, "y": 100, "width": 200, "height": 200},
  "category": "face",
  "tags": "front, smile, female"
}

This saves whatever is currently in that region of your image.

Option 3: Import from File

Upload an external image:

POST /patches/
FormData:
  name: "Downloaded Hand"
  source_type: "imported"
  file: [uploaded PNG file]
  category: "hand"

How to Apply a Saved Patch

POST /patches/apply
{
  "project_id": 789,
  "patch_id": 123,
  "bbox": {"x": 300, "y": 400, "width": 200, "height": 200},
  "feather_px": 10
}

This places the saved patch at the specified location in your image.

Browse Your Patch Library

# List all patches
GET /patches/

# Filter by category
GET /patches/?category=hand

# Filter by tags
GET /patches/?tags=realistic

# Get specific patch
GET /patches/123

# Get patch image
GET /patches/123/image

# Get patch thumbnail
GET /patches/123/image?thumbnail=true

Organize Your Patches

Categories:

• hand - Hand images
• face - Facial features
• body - Body parts
• object - Objects and items
• texture - Textures and patterns
• background - Backgrounds and scenery

Tags: Comma-separated keywords for searching

• "left, palm, realistic"
• "front, smile, female"
• "five fingers, open hand"

---

Complete Workflow Example

Scenario: Fix hands in a portrait photo

Step 1: Create project and upload image

POST /projects/ {"name": "Portrait Edit"}
POST /projects/1/upload [upload photo]

Step 2: Try to fix the hand with AI

POST /edits/projects/1/fix
{
  "prompt": "realistic human hand with five fingers, natural pose",
  "mode": "B",  # Use full image for context
  "selection_type": "rectangle",
  "bbox": {"x": 200, "y": 300, "width": 150, "height": 200},
  "feather_px": 10
}

The system auto-selects realistic-vision model because prompt mentions "hand".

Step 3: If result is good, save it for later

POST /patches/
{
  "name": "Good Left Hand",
  "source_type": "ai_generated",
  "source_edit_id": 1,
  "category": "hand",
  "tags": "left, natural, realistic, five fingers"
}

Step 4: Use saved hand on another photo

# On a different project
POST /patches/apply
{
  "project_id": 2,
  "patch_id": 1,
  "bbox": {"x": 150, "y": 250, "width": 150, "height": 200},
  "feather_px": 15
}

---

Cost Comparison

Example: Fixing 10 hands in different photos

Option A: Generate each hand with AI

• 10 edits × $0.020 = $0.20

Option B: Generate one good hand, save it, reuse it

• 1 AI generation: $0.020
• 9 patch applications: $0.00 (no AI cost)
• Total: $0.020 (90% savings!)

When to Use Saved Patches vs AI

Use Saved Patches When:

• You have a perfect result you want to reuse
• Same angle/lighting/style needed
• Want to maintain consistency across images
• Want to avoid AI generation costs

Use AI Generation When:

• Need unique/different result each time
• Different angle or perspective needed
• Want variation and creativity
• Patch doesn't fit the context

---

Pro Tips

Building a Good Patch Library

1. Save your best AI results - When AI generates something great, save it immediately
2. Organize with categories - Use consistent categories for easy finding
3. Tag descriptively - Include orientation (left/right), pose, lighting, etc.
4. Create variations - Save multiple versions of common needs (left hand, right hand, etc.)
5. Build gradually - Your library becomes more valuable over time

Maximizing Quality

1. For hands: Always use realistic-vision model or save good results
2. For faces: Use Mode B (full image context) for better matching
3. Use high feather values (15-20px) when applying saved patches
4. Test positioning before finalizing - patches work best when lighting/angle matches

Saving Money

1. Build a patch library of common needs
2. Use lama for removals instead of expensive models
3. Let auto-selection work - it picks the cheapest appropriate model
4. Reuse successful patches instead of regenerating

---

API Quick Reference

# List available patches
GET /patches/

# Get patch details
GET /patches/{id}

# Get patch image
GET /patches/{id}/image
GET /patches/{id}/image?thumbnail=true

# Create patch from AI edit
POST /patches/
{
  "name": "My Patch",
  "source_type": "ai_generated",
  "source_edit_id": 123,
  "category": "hand"
}

# Create patch from manual selection
POST /patches/
{
  "name": "My Patch",
  "source_type": "manual_selection",
  "source_project_id": 456,
  "bbox": {"x": 100, "y": 100, "width": 200, "height": 200}
}

# Apply saved patch
POST /patches/apply
{
  "project_id": 789,
  "patch_id": 123,
  "bbox": {"x": 300, "y": 400, "width": 200, "height": 200},
  "feather_px": 10
}

# Delete patch
DELETE /patches/{id}

# Update patch metadata
PUT /patches/{id}
{
  "name": "Updated Name",
  "tags": "new, tags",
  "category": "hand"
}

---

Summary

✅ For hands/faces/bodies: Use realistic-vision model ✅ For removal: Use lama model ✅ For general edits: Use sdxl-inpaint (default) ✅ Auto-selection works great - just write natural prompts ✅ Save good AI results to patch library for reuse ✅ Save manual selections from any image ✅ Reuse patches across images to save money and maintain consistency

You now have the best of both worlds:

• AI generation when you need something new
• Saved patches when you need consistency or want to save money