character-browser/README.md

Character Browser & Generator

A local web-based GUI for managing character profiles (JSON) and generating consistent images using ComfyUI.

Features

• Character Gallery: Automatically scans your characters/ folder and builds a searchable, sortable database.
• Outfit Gallery: Manage reusable outfit presets that can be applied to any character.
• AI-Powered Creation: Create new characters and outfits using AI to generate profiles from descriptions, or manually create blank templates.
• Granular Prompt Control: Every field in your character JSON (Identity, Wardrobe, Styles) has a checkbox. You decide exactly what is sent to the AI.
• ComfyUI Integration:
  • SDXL Optimized: Designed for high-quality SDXL workflows.
  • Localized ADetailer: Automated Face and Hand detailing with focused prompts (e.g., only eye color and expression are sent to the face detailer).
  • LoRA Support: Automatically detects and applies LoRAs specified in your character sheets.
  • Real-time Progress: Live progress bars and queue status via WebSockets (with a reliable polling fallback).
• Batch Processing:
  • Fill Missing: Generate covers for every character missing one with a single click.
  • Refresh All: Unassign all current covers and generate a fresh set for the whole collection.
• Advanced Generator: A dedicated page to mix-and-match characters with different checkpoints (Illustrious/Noob support) and custom prompt additions.
• Smart URLs: Sanitized, human-readable URLs (slugs) that handle special characters and slashes gracefully.

Prerequisites

1. Python 3.10+
2. ComfyUI running locally (default: http://127.0.0.1:8188).
3. ComfyUI Custom Nodes:
   • ComfyUI-Impact-Pack (Required for FaceDetailer).
4. Models:
   • Ensure your Checkpoints are in the folders defined in app.py.
   • Face detection model: bbox/face_yolov9c.pt (or update comfy_workflow.json).
   • Hand detection model: bbox/hand_yolov8s.pt.

Setup & Installation

1. Clone the repository to your local machine.
2. Configure Paths: Open app.py and update the following variables to match your system:

   app.config['COMFYUI_URL'] = 'http://127.0.0.1:8188'
   app.config['ILLUSTRIOUS_MODELS_DIR'] = '/path/to/your/Illustrious/models'
   app.config['NOOB_MODELS_DIR'] = '/path/to/your/Noob/models'
   

3. Launch: Simply run the launch script. It will handle the virtual environment and dependencies automatically.

   chmod +x launch.sh
   ./launch.sh
   

Usage

Creating Characters & Outfits

• AI Generation: Toggle "Use AI to generate profile from description" on, then describe your character or outfit. The AI will generate a complete profile with appropriate tags.
• Manual Creation: Toggle AI generation off to create a blank template you can edit yourself.
• Auto-naming: Leave the filename field empty to auto-generate one from the name. If a file already exists, a number will be appended automatically.

Gallery Management

• Rescan: Use the "Rescan Character Files" button if you've added new JSON files or manually edited them.
• Save Defaults: On a character page, select your favorite prompt combination and click "Save as Default Selection" to remember it for future quick generations.

Generation

• Preview: Generates an image and shows it to you without replacing your current cover.
• Replace: Generates an image and sets it as the character's official gallery cover.
• Clean Start: If you want to wipe the database and all generated images to start fresh:

  ./launch.sh --clean
  

JSON Structure

Character Profile

{
  "character_id": "example_character",
  "character_name": "Example Character",
  "identity": {
    "base_specs": "1girl, slender build, fair skin",
    "hair": "long blue hair",
    "eyes": "blue eyes",
    "hands": "",
    "arms": "",
    "torso": "",
    "pelvis": "",
    "legs": "",
    "feet": "",
    "extra": ""
  },
  "defaults": {
    "expression": "smile",
    "pose": "standing",
    "scene": "simple background"
  },
  "wardrobe": {
    "default": {
      "full_body": "",
      "headwear": "",
      "top": "white blouse",
      "bottom": "blue skirt",
      "legwear": "black thighhighs",
      "footwear": "black shoes",
      "hands": "",
      "accessories": "ribbon"
    }
  },
  "styles": {
    "aesthetic": "anime style",
    "primary_color": "blue",
    "secondary_color": "white",
    "tertiary_color": ""
  },
  "lora": {
    "lora_name": "",
    "lora_weight": 1.0,
    "lora_triggers": ""
  },
  "tags": ["tag1", "tag2"]
}

Outfit Profile

{
  "outfit_id": "school_uniform_01",
  "outfit_name": "School Uniform",
  "wardrobe": {
    "full_body": "",
    "headwear": "",
    "top": "white blouse, sailor collar",
    "bottom": "pleated skirt",
    "legwear": "knee socks",
    "footwear": "loafers",
    "hands": "",
    "accessories": "ribbon tie"
  },
  "lora": {
    "lora_name": "",
    "lora_weight": 0.8,
    "lora_triggers": ""
  },
  "tags": ["school uniform", "uniform"]
}

File Structure

• /data/characters: Your character JSON files.
• /data/clothing: Outfit preset JSON files.
• /static/uploads: Generated images (organized by character subfolders).
• /templates: HTML UI using Bootstrap 5.
• app.py: Flask backend and prompt-building logic.
• comfy_workflow.json: The API-format workflow used for generations.
• models.py: SQLite database schema.