From 1982b4e9ebc985fb34c743fbde47473b381633de Mon Sep 17 00:00:00 2001 From: techjarves Date: Thu, 4 Jun 2026 10:49:14 +0530 Subject: [PATCH] docs: refactor README for better readability with condensed feature lists and updated directory structure. --- README.md | 177 +++++++++++------------------------------------------- 1 file changed, 35 insertions(+), 142 deletions(-) diff --git a/README.md b/README.md index da0128d..0807c68 100644 --- a/README.md +++ b/README.md @@ -1,188 +1,81 @@ -
- # 🖼️ Local AI Image Generator ### A fully self-contained, offline-first AI Art Studio for Windows -[![Platform: Windows](https://img.shields.io/badge/Platform-Windows-0078D6?logo=windows&logoColor=white&style=for-the-badge)](https://github.com) -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) -[![Build: v1.0.0](https://img.shields.io/badge/Release-v1.0.0-success?style=for-the-badge)](https://github.com) -[![Engine: stable--diffusion.cpp](https://img.shields.io/badge/Engine-stable--diffusion.cpp-orange?style=for-the-badge)](https://github.com/leejet/stable-diffusion.cpp) +
+ +[![Platform: Windows](https://img.shields.io/badge/Platform-Windows-0078D6?logo=windows&logoColor=white&style=flat-square)](https://github.com) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE) +[![Build: v1.0.0](https://img.shields.io/badge/Release-v1.0.0-success?style=flat-square)](https://github.com) +[![Engine: stable--diffusion.cpp](https://img.shields.io/badge/Engine-stable--diffusion.cpp-orange?style=flat-square)](https://github.com/leejet/stable-diffusion.cpp) --- -[🚀 Quick Start](#-quick-start) • [✨ Features](#-features) • [📸 Screenshots](#-screenshots) • [📂 Project Structure](#-project-structure) • [📦 Adding Models](#-adding-models-required) • [🛠️ Troubleshooting](#%EF%B8%8F-troubleshooting) +| **Generation Workspace** | **Model Library** | **Image Constraints** | +| :---: | :---: | :---: | +| | | | --- -Local AI Studio Dashboard -
## 📖 Overview - -**Local AI Image Generator** is a packaged, production-grade desktop environment designed to run Stable Diffusion models natively on Windows with maximum performance and zero installation complexity. - -Say goodbye to manual Python installations, corrupted PyTorch dependencies, global Node.js setups, or broken CUDA toolchains. This workspace automatically downloads, configures, and serves the entire local image generation stack inside a single directory. +**Local AI Image Generator** is a zero-configuration, portable desktop environment for running Stable Diffusion (Safetensors/GGUF/CKPT) offline on Windows. Double-clicking `start.bat` automatically handles dependency setup, GPU backend matching (CUDA/Vulkan), and launches a high-performance local web workspace. --- ## ⚡ Quick Start - -### 1. Launch -Double-click **`start.bat`** in the root directory. - -*On your first launch, the automated installer script will download a portable Node.js build, configure dependencies, detect your GPU, download pre-compiled backend binaries, and compile the user interface.* - -### 2. Put Weights in Place -Place any `.safetensors`, `.gguf`, or `.ckpt` model file into: -``` -app/models/ -``` -*(Or use the **Model Manager** tab in the browser dashboard to download one from our curated library).* - -### 3. Generate Offline -Open **`http://localhost:1420`** in your default web browser, select your model, write a prompt, and start creating! +1. **Launch:** Double-click **`start.bat`** (downloads portable Node.js and pre-compiled GPU backend binaries on first run). +2. **Add Models:** Drop `.safetensors`, `.gguf`, or `.ckpt` weights into `app/models/` (or download them via the **Model Manager** tab in the UI). +3. **Generate:** Open `http://localhost:1420` in your browser, select your model, and write a prompt. --- ## ✨ Features - - - - - - - - - - - - - - -
-

🔒 100% Offline & Private

-

All inference runs entirely on your local GPU/CPU. Your prompts, images, and data never leave your computer.

- 		-

🚀 Auto-Detected GPU Acceleration

-

Seamlessly detects and configures **CUDA** for Nvidia cards, or falls back to the high-performance **Vulkan** engine for AMD & Intel Arc GPUs.

-
-

📦 No Global Dependencies

-

Zero system footprint. Node.js is downloaded as a portable binary into a sandbox folder, leaving your environment paths untouched.

- 		-

🎛️ Dynamic Backend Controller

-

A native Node.js process manager hosts the React frontend, streams system telemetry, manages downloads, and handles inference server lifecycles.

-
-

📊 Real-time Hardware Telemetry

-

Monitor your PC's real-time CPU, RAM, GPU, and VRAM utilization directly inside the workspace UI.

- 		-

📁 Drag & Drop Model Importing

-

Upload local model files from other folders on your PC or download weights directly from Hugging Face via the built-in UI downloader.

-
+* **100% Offline & Private:** Inference runs completely locally on your hardware. +* **Auto-Detected GPU Acceleration:** Configures **CUDA** for Nvidia cards, and **Vulkan** for AMD or Intel Arc GPUs. +* **Zero System Footprint:** Node.js is sandboxed inside the folder. No global environment paths are altered. +* **Integrated Model Manager:** Paste a Hugging Face URL to download weights directly, or drag-and-drop local weight files to import them. +* **Real-time Telemetry:** Monitor RAM, VRAM, CPU, and GPU load directly in the UI. +* **Local Gallery:** Saves generated PNGs alongside prompt metadata JSONs to `app/outputs/`. --- -## 📸 Screenshots - -### Model Library Manager -Allows downloading recommended weights or importing custom files directly through the UI. -Model Library Screen - -### Inference & Hardware Constraints -Adjust parameters, resolution aspect-ratios, and hardware backend options in one place. -Image Constraints Settings - ---- - -## 🏗️ Project Structure - +## 📁 Repository Structure ``` local-ai-image-generator/ -├── start.bat # main double-click launcher +├── start.bat # Main double-click entrypoint ├── LICENSE # MIT Open Source license ├── .gitignore ├── README.md -│ ├── scripts/ -│ ├── setup.ps1 # dynamic 4-stage dependency manager -│ ├── reset.ps1 # repair utility (clears builds, keeps your models/images) -│ └── serve.cjs # static UI server & backend controller -│ +│ ├── setup.ps1 # Automated GPU-detect and environment installer +│ ├── reset.ps1 # Cleans runtime environments (keeps models & outputs) +│ └── serve.cjs # UI web server and backend lifecycle manager └── app/ - ├── frontend/ # React + Vite dashboard source code - ├── backend/ # pre-compiled stable-diffusion.cpp GPU binaries - │ ├── win/cuda/ # CUDA acceleration backend (sd-cuda.exe) - │ └── win/vulkan/ # Vulkan acceleration backend (sd-vulkan.exe) - ├── models/ # weight repository (.safetensors, .gguf, .ckpt) - ├── outputs/ # generated PNGs and JSON parameters metadata - ├── tools/node/ # portable Node.js sandbox - └── dist/ # built frontend assets (compiled on setup) + ├── frontend/ # UI source code (Vite + React) + ├── models/ # Place weights here (.safetensors, .gguf, .ckpt) + └── outputs/ # Saved images and parameters metadata ``` --- -## 📦 First-Run Setup Stages - -When launching for the first time, `scripts/setup.ps1` runs automatically in your console window through 4 stages: - -```mermaid -graph TD - A[Launch start.bat] --> B[Stage 1: Setup Portable Node.js] - B --> C[Stage 2: Scan GPU & Download CUDA / Vulkan Binary] - C --> D[Stage 3: Install Frontend NPM Dependencies] - D --> E[Stage 4: Compile React UI into dist/] - E --> F[Open Browser: localhost:1420] -``` - ---- - -## 📥 Adding Models (Required) - -> [!IMPORTANT] -> **This repository does not ship with pre-downloaded AI weights** due to their large file sizes (2 GB to 12 GB+). The `app/models/` folder will be empty on your first start. You must add at least one model before generating. - -You can import weights using **three simple options**: - -1. **Curated Library:** Navigate to the **Model Manager** tab in the dashboard and click **Download** next to any of our pre-configured models (e.g. *DreamShaper 8* for SD 1.5 speed, or *Juggernaut XL* for SDXL realism). -2. **Download URL:** Paste any direct download link to a GGUF/Safetensors weights file (e.g. from Civitai or Hugging Face) into the Model Manager URL box. -3. **Manual Import:** Move your existing `.safetensors`, `.gguf`, or `.ckpt` weights files directly into the `app/models/` directory. - ---- - ## 🖥️ GPU Compatibility Matrix -The application server configures itself to utilize the best performance pathways on your PC: - -| GPU Brand | Tech | Status | Setup Output | +| GPU Vendor | Tech | Status | Notes | | :--- | :--- | :--- | :--- | -| **Nvidia** | CUDA | ✅ Native Support | Maps `sd-cuda.exe` with Nvidia SDK 12 optimizations. | -| **AMD Radeon** | Vulkan | ✅ Native Support | Maps `sd-vulkan.exe` with Vulkan API acceleration. | -| **Intel Arc** | Vulkan | ✅ Native Support | Maps `sd-vulkan.exe` for GPU acceleration. | -| **None / Integrated** | CPU | ⚠️ Thread Fallback | Runs on logical threads (slow, for testing). | +| **Nvidia** | CUDA | ✅ Native | Maps `sd-cuda.exe` with Nvidia SDK 12 optimizations. | +| **AMD Radeon** | Vulkan | ✅ Native | Maps `sd-vulkan.exe` with Vulkan API acceleration. | +| **Intel Arc** | Vulkan | ✅ Native | Maps `sd-vulkan.exe` for Intel hardware. | +| **Integrated / None** | CPU | ⚠️ Fallback | Runs on logical CPU threads (slow). | --- ## 🛠️ Troubleshooting - -### 🔄 Resetting / Repairing -If you encounter corrupted downloads or want to rebuild your frontend assets, run: -```powershell -scripts/reset.ps1 -``` -*Note: This cleans the portable environment files and downloads fresh copies, but **safely preserves your downloaded models inside `app/models/` and images in `app/outputs/`**.* - -### 🔌 Port Conflict Warnings -The launcher utilizes two ports on local address `127.0.0.1`: -- **`1420`** (Frontend Dashboard Server) -- **`8080`** (Local Inference C++ API Server) - -Ensure no other applications or development services are binding to these ports before launching. +* **Reset Environment:** If a build fails or you want to clear dependencies, run `scripts/reset.ps1`. (This preserves your models and generated images). +* **Port Conflicts:** The application binds to ports `1420` (Frontend) and `8080` (Backend API). Ensure these are free. --- ## 📝 License - -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. - -It bundles [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) which is also licensed under the MIT License. Model weights are subject to their own respective licenses — please check model cards on Hugging Face or Civitai before commercial application. \ No newline at end of file +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file. Bundles [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) (MIT License). Model weights are subject to their respective creators' licenses. \ No newline at end of file