diff --git a/README.md b/README.md index e960c50..65e1b53 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,81 @@ -
- Forgery Logo -

Forgery

-

Your personal AI studio for equipment extraction and character look generation.

-
+# 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. + +[![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 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)