# 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.
- **Actions Gallery**: A library of reusable poses and actions (e.g., "Belly Dancing", "Sword Fighting") that can be previewed on any character model.
- **AI-Powered Creation**: Create new characters, outfits, and actions using AI to generate profiles from descriptions, or manually create blank templates.
- **character-Integrated Previews**: Standalone items (Outfits/Actions) can be previewed directly on a specific character's model with automatic style injection (e.g., background color matching).
- **Granular Prompt Control**: Every field in your JSON models (Identity, Wardrobe, Styles, Action details) has a checkbox. You decide exactly what is sent to the AI.
- **ComfyUI Integration**:
    - **SDXL Optimized**: Designed for high-quality SDXL/Illustrious workflows.
    - **Localized ADetailer**: Automated Face and Hand detailing with focused prompts (e.g., only eye color and expression are sent to the face detailer).
    - **Triple LoRA Chaining**: Chains up to three distinct LoRAs (Character + Outfit + Action) sequentially in the generation workflow.
    - **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.
- **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](https://github.com/ltdrdata/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:
   ```python
   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.
   ```bash
   chmod +x launch.sh
   ./launch.sh
   ```

## Usage

### Creating Content
- **AI Generation**: Toggle "Use AI to generate profile from description" on, then describe your character, outfit, or action. 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" buttons if you've added new JSON files or manually edited them.
- **Save Defaults**: On any detail page, select your favorite prompt combination and click "Save as Default Selection" to remember it for future 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 item's official gallery cover.
- **Clean Start**: If you want to wipe the database and all generated images to start fresh:
  ```bash
  ./launch.sh --clean
  ```

## File Structure

- `/data/characters`: Character JSON files.
- `/data/clothing`: Outfit preset JSON files.
- `/data/actions`: Action/Pose preset JSON files.
- `/static/uploads`: Generated images (organized by subfolders).
- `app.py`: Flask backend and prompt-building logic.
- `comfy_workflow.json`: The API-format workflow used for generations.
- `models.py`: SQLAlchemy database models.
- `DEVELOPMENT_GUIDE.md`: Architectual patterns for extending the browser.