da55b0889b
- Add Dockerfile, docker-compose.yml, .dockerignore for containerised deployment - Extract _resolve_character(), _ensure_character_fields(), _append_background() helpers to eliminate repeated inline character-field injection and background-tag patterns across all secondary-category generate routes - Add _IDENTITY_KEYS / _WARDROBE_KEYS constants - Fix build_extras_prompt() bug: detailer prompt (a list) was being appended as a single item instead of extended - Replace all per-route _finalize closures with _make_finalize() factory, reducing duplication across 10 generate routes - Add _prune_job_history() called each worker loop iteration to prevent unbounded memory growth - Remove 10 orphaned legacy finalize_generation HTTP routes and check_status route (superseded by job queue API since job-queue branch) - Remove one-time migration scripts (migrate_actions, migrate_detailers, migrate_lora_weight_range, migrate_wardrobe) - Update CLAUDE.md and README.md to document new helpers, queue architecture, and Docker deployment Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
103 lines
6.1 KiB
Markdown
103 lines
6.1 KiB
Markdown
# 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.
|
|
- **Styles Gallery**: Manage art style / artist LoRA presets with AI-assisted bulk creation from your styles LoRA folder.
|
|
- **Scenes Gallery**: Background and environment LoRA presets, previewable with any character.
|
|
- **Detailers Gallery**: Detail enhancement LoRA presets for fine-tuning face, hands, and other features.
|
|
- **Checkpoints Gallery**: Browse all your installed SDXL checkpoints (Illustrious & Noob families). Stores per-checkpoint generation settings (steps, CFG, sampler, VAE, base prompts) via JSON files in `data/checkpoints/`. Supports AI-assisted metadata generation from accompanying HTML files.
|
|
- **AI-Powered Creation**: Create and populate gallery entries using AI to generate profiles from descriptions or LoRA HTML files, or manually create blank templates.
|
|
- **Character-Integrated Previews**: Standalone items (Outfits/Actions/Styles/Scenes/Detailers/Checkpoints) can be previewed directly on a specific character's model.
|
|
- **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).
|
|
- **Quad LoRA Chaining**: Chains up to four distinct LoRAs (Character + Outfit + Action + Style/Detailer/Scene) sequentially in the generation workflow.
|
|
- **Per-Checkpoint Settings**: Steps, CFG, sampler name, VAE, and base prompts are applied automatically from each checkpoint's JSON profile.
|
|
- **Real-time Progress**: Live progress bars and queue status via WebSockets (with a reliable polling fallback).
|
|
- **Batch Processing**:
|
|
- **Fill Missing**: Generate covers for every item missing one with a single click, across all galleries.
|
|
- **Bulk Create from LoRAs/Checkpoints**: Auto-generate JSON metadata for entire directories using an LLM.
|
|
- **Advanced Generator**: A dedicated mix-and-match page combining any character, outfit, action, style, scene, and detailer in a single generation.
|
|
- **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
|
|
|
|
### Option A — Docker (recommended)
|
|
|
|
1. **Clone the repository.**
|
|
2. Edit `docker-compose.yml` if needed:
|
|
- Set `COMFYUI_URL` to your ComfyUI host/port.
|
|
- Adjust the `/Volumes/ImageModels` volume path to your model directory. If you're on Docker Desktop, add the path under **Settings → Resources → File Sharing** first.
|
|
3. **Start services:**
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
The app will be available at `http://localhost:5782`.
|
|
|
|
### Option B — Local (development)
|
|
|
|
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.
|
|
- `/data/styles`: Art style / artist LoRA JSON files.
|
|
- `/data/scenes`: Scene/background LoRA JSON files.
|
|
- `/data/detailers`: Detailer LoRA JSON files.
|
|
- `/data/checkpoints`: Per-checkpoint metadata JSON files (steps, CFG, sampler, VAE, base prompts).
|
|
- `/data/prompts`: LLM system prompts used by the AI-assisted bulk creation features.
|
|
- `/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`: Architectural patterns for extending the browser.
|