Update README.md

This commit is contained in:
Yiling-J authored and GitHub committed 2026-02-19 09:36:36 +08:00
1 parent 9c139d5bfb
commit bbd1fd320c
1 file changed
+26 -50
+26 -50
View File
@@ -1,63 +1,37 @@
<div align="center">
<img src="public/logo-large.webp" alt="Forgery Logo" width="200" height="200" />
<h1>Forgery</h1>
<p><strong>Build, remix, and re-style characters with AI — extract equipment from images, store them in a library, and apply equipment + pose/expression to generate fresh looks.</strong></p>
<p><strong>Build, remix, and re-style characters with AI</strong></p>
</div>
[![build-badge](https://img.shields.io/badge/build-wip-yellow)](https://github.com/yourname/forgery) [![license-mit](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
Forge characters, not chaos. Forgery helps you extract equipments (props, clothing, accessories) from character images, save them as reusable items, and then generate new character _looks_ by applying selected equipments + pose/expression controls using AI image generation.
Forge characters, not chaos. `forgery` helps you extract equipments (props, clothing, accessories) from character images, save them as reusable items in a DB, and then generate new character _looks_ by applying selected equipments + pose/expression controls using AI image generation.
---
## Why Forgery?
- **Modular Assets**: Turn screenshots, cosplay photos, or movie stills into modular assets.
- **Rapid Prototyping**: Quickly prototype many character looks by mixing and matching equipments.
- **Fine-Grained Control**: Add expression & pose control to generated looks for richer results.
- **Local-First & Private**: All data, including your image library and generated results, is stored locally on your machine.
- **Flexible AI Integration**: Seamlessly switch between Google Gemini and OpenAI models for different stages of the pipeline.
---
## Highlights
- 🔍 **Equipment extraction** — detect & crop equipment regions, normalize and store metadata.
- 🧩 **Equipment library** — structured DB with visual preview, masks, tags, anchors, and compatibility hints.
- 🖼️ **Apply equipments** — generate a new image of a character wearing selected equipments.
- 🎭 **Pose & expression controls** — specify expression and pose priors to steer generation.
- 🔌 **Model-agnostic** — plug in your favorite segmentation or image-generation models (OpenAI, Gemini supported out-of-the-box).
- ♻️ **Open-source** — clear data model & contribution guidelines.
---
## How It Works
1. **Extract**: Upload a character image. Forgery analyzes it to identify and extract equipment (outfits, weapons, accessories).
2. **Refine**: Review the extracted assets, refine their masks, and save them to your library.
3. **Create Character**: Upload a base portrait for your character.
4. **Fitting Room**: Combine your character with selected equipment, choose a pose, and set an expression.
5. **Generate**: Watch as Forgery generates a new Look for your character.
1. **Extractor**: Upload an image. Forgery analyzes it to identify and extract equipment (outfits, weapons, accessories).
2. **Create Character**: Upload a base portrait for your character.
3. **Fitting Room**: Combine your character with selected equipment, choose a pose, and set an expression.
4. **Generate**: Watch as Forgery generates a new Look for your character.
---
## Core Concepts
- **Equipment** — any wearable or attachable asset extracted from images (hat, glasses, sword, jacket). Stored with mask, anchor points, metadata.
- **Character** — a user-created profile representing a base person/portrait used as the generation canvas.
- **Look** — a generated image (or variant) that applies a set of equipments to a character, optionally altered by pose/expression.
- **Extraction** — computer vision process that detects equipment regions and outputs masks, crops, and suggested anchors.
- **Application/Generation** — image generation pipeline that composes character + selected equipments + conditioning (pose/expression) into a final render.
---
## Getting Started
### Requirements
- [Bun](https://bun.sh) (v1.0.0 or later)
- [Bun](https://bun.sh)
- **OR** [Docker](https://www.docker.com/)
- API Keys for OpenAI or Google Gemini (for AI generation)
- API Keys for OpenAI or Google Gemini
### Local Quickstart
@@ -93,7 +67,7 @@ docker run -d \
# server available at http://localhost:3000
```
---
## Configuration
@@ -102,9 +76,23 @@ Forgery requires API keys for AI generation services (Google Gemini and/or OpenA
1. Launch the application and go to the **Settings** page (accessed via the sidebar).
2. Enter your **Google API Key** and/or **OpenAI API Key**.
3. Configure your preferred models for text and image generation.
4. (Optional) Customize the "Extraction Flow" to choose specific models for different steps of the asset analysis and generation process.
---
## Model Recommendations
For optimal results in both equipment extraction and high-fidelity character generation, it is highly recommended to use the **Nana Banana Pro** model. This model provides superior precision for isolating modular assets and ensures the most consistent "looks" when remixing styles and accessories.
For the Refine step, the standard Nano Banana model is typically sufficient to handle iterative adjustments and polish without the need for the Pro-level tier.
## Data Backup
Your data is stored locally in data folder. To back up your library, character assets, and configuration, simply copy the data folder.
To restore, place the folder back in the root directory (or your Docker volume path) before starting the application.
## Architecture Overview
@@ -118,22 +106,10 @@ A modular pipeline built on a modern stack:
- Orchestrates AI models (OpenAI/Gemini) to analyze images and generate masks.
4. **Asset Store**
- Local file system (`data/files`) for storing optimized WebP images.
5. **Generation Service**
- Composes prompts and conditioning for image generation models.
6. **DB** (SQLite + Prisma)
5. **DB** (SQLite + Prisma)
- Stores metadata, relationships, settings, and generation history.
---
## Contributing
Love forks, fixes, and wild experiments.
- Run tests: `bun test`
- Lint code: `bun run lint`
- Create clear PRs with reproducible steps and small commits.
---
## License