Docs: Revamp README with improved structure and correct tech stack
- Replaced generic intro with "Why Forgery?", "Highlights", and "Core Concepts" sections derived from marketing copy. - Corrected tech stack information (Bun, Hono, React, SQLite) to match the codebase. - Replaced incorrect `curl` demos with a UI-focused "How It Works" workflow. - Updated installation instructions to use `bun` commands. - Added "Architecture Overview" to explain the modular pipeline.
This commit is contained in:
google-labs-jules[bot] committed
1 parent
db256185f5
commit
017b4587f6
1 file changed
+87
-54
@@ -1,75 +1,81 @@
|
||||
<div align="center">
|
||||
<img src="public/logo-large.webp" alt="Forgery Logo" width="200" height="200" />
|
||||
<h1>Forgery</h1>
|
||||
<p><strong>Your personal AI studio for equipment extraction and character look generation.</strong></p>
|
||||
</div>
|
||||
# Forgery
|
||||
|
||||
> 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.
|
||||
|
||||
[](https://github.com/yourname/forgery) [](./LICENSE)
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## About
|
||||
## Why Forgery?
|
||||
|
||||
Forgery is a local-first application designed to help you build a digital wardrobe and generate stunning new looks for your characters. It specializes in two key workflows: **extracting equipment from existing images** and **fitting that equipment onto your characters**.
|
||||
* **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.
|
||||
|
||||
Unlike traditional character generators, Forgery focuses on consistency and customization. You start by uploading a base image for your character, then use the powerful "Fitting Room" to generate new variations (Looks) by mixing and matching extracted equipment, poses, and expressions.
|
||||
---
|
||||
|
||||
## Features
|
||||
## Highlights
|
||||
|
||||
- **Equipment Extraction**: Analyze images to identify and extract equipment (outfits, weapons, accessories) into your library.
|
||||
- **Look Generation**: Generate new images of your character wearing selected equipment.
|
||||
- **Character Management**: Organize your characters and their base reference images.
|
||||
- **Fitting Room**: The core studio interface for combining characters, equipment, poses, and expressions into new Looks.
|
||||
- **Pose & Expression Control**: Fine-tune your generation with a library of poses and facial expressions.
|
||||
- **Local & 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 extraction and generation pipeline.
|
||||
* 🔍 **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.
|
||||
|
||||
## Prerequisites
|
||||
---
|
||||
|
||||
- [Bun](https://bun.sh) (v1.0.0 or later)
|
||||
- **OR** [Docker](https://www.docker.com/)
|
||||
## 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.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
### 1. Clone the Repository
|
||||
### Requirements
|
||||
|
||||
* [Bun](https://bun.sh) (v1.0.0 or later)
|
||||
* **OR** [Docker](https://www.docker.com/)
|
||||
* API Keys for OpenAI or Google Gemini (for AI generation)
|
||||
|
||||
### Local Quickstart
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/forgery.git
|
||||
git clone https://github.com/yourname/forgery.git
|
||||
cd forgery
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
### 3. Initialize the Database
|
||||
|
||||
Forgery uses a local SQLite database. Run the following command to set up the schema:
|
||||
|
||||
```bash
|
||||
bun run prisma migrate dev
|
||||
```
|
||||
|
||||
### 4. Run the Application
|
||||
|
||||
Start the development server:
|
||||
|
||||
```bash
|
||||
bun run prisma migrate dev # Initialize local SQLite DB
|
||||
bun run dev
|
||||
# server available at http://localhost:3000
|
||||
```
|
||||
|
||||
Open your browser and navigate to `http://localhost:3000`.
|
||||
|
||||
## Running with Docker
|
||||
|
||||
You can also run Forgery using Docker Compose.
|
||||
### Docker Quickstart
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
# server available at http://localhost:3000
|
||||
```
|
||||
|
||||
The application will be available at `http://localhost:3000`.
|
||||
Data (database and generated files) will be persisted in the `./data` directory on your host machine.
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -80,10 +86,37 @@ Forgery requires API keys for AI generation services (Google Gemini and/or OpenA
|
||||
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.
|
||||
|
||||
## Tech Stack
|
||||
---
|
||||
|
||||
- **Runtime**: [Bun](https://bun.sh)
|
||||
- **Backend Framework**: [Hono](https://hono.dev)
|
||||
- **Frontend Library**: [React](https://react.dev)
|
||||
- **Styling**: [Tailwind CSS](https://tailwindcss.com) + [Shadcn UI](https://ui.shadcn.com)
|
||||
- **Database**: SQLite with [Prisma](https://www.prisma.io)
|
||||
## Architecture Overview
|
||||
|
||||
A modular pipeline built on a modern stack:
|
||||
|
||||
1. **Frontend** (React + Shadcn UI + Tailwind)
|
||||
* Upload UI, equipment library browser, look composer (Fitting Room).
|
||||
2. **API Server** (Hono on Bun)
|
||||
* REST API for extraction, equipment CRUD, character CRUD, generation.
|
||||
3. **Extraction Service**
|
||||
* 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)
|
||||
* 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
|
||||
|
||||
[MIT](./LICENSE)
|
||||
Reference in new issue
Block a user