README.md

metadata

title: sd-image-gen-toolkit
app_file: src/sdgen/main.py
sdk: gradio
sdk_version: 6.0.2

Stable Diffusion Image Generation Toolkit

Live Demo

---

Overview

A modular, lightweight image generation toolkit built on Hugging Face Diffusers, designed for CPU-friendly deployment, clean architecture, and practical usability.

It supports Text → Image, Image → Image, and Upscaling, with a preset system, optional LoRA adapters, and a local metadata history for reproducibility.

---

Features

Text → Image

• Stable Diffusion 1.5 and Turbo
• Configurable prompt parameters:
  • prompt / negative prompt
  • steps
  • guidance (CFG)
  • resolution
  • seed (optional)
• JSON metadata output
• Style presets for quick experimentation

Image → Image

• Modify existing images via the SD Img2Img pipeline
• Denoising strength control
• Full parameter configuration
• Shared preset system
• History saved for reproducibility

Upscaling (Real-ESRGAN NCNN)

• 2× and 4× upscaling
• NCNN backend (no GPU required)
• Minimal dependencies
• Fast on CPU environments (HF Spaces)

LoRA Adapter Support

• Runtime loading of .safetensors adapters
• Up to two adapters with independent weights
• Alpha range -2 → +2 per adapter
• Automatic discovery under:

src/assets/loras/

• LoRA UI is disabled for Turbo, since Turbo does not benefit from LoRA injection

Metadata History

Every generation stores:

• model id
• prompt + negative prompt
• steps, cfg, resolution
• seed
• LoRA names + weights
• timestamp

All generated data is stored in a tree structure under:

src/assets/history/

---

Architecture

src/
└── sdgen/
├── sd/                     # Stable Diffusion runtime
│   ├── pipeline.py         # model loading, device config
│   ├── generator.py        # text-to-image inference
│   ├── img2img.py          # image-to-image inference
│   ├── lora_loader.py      # LoRA discovery & injection
│   └── models.py           # typed config & metadata objects
│
├── ui/                     # Gradio UI components
│   ├── layout.py           # composition root for UI
│   └── tabs/               # modular tabs
│       ├── txt2img_tab.py
│       ├── img2img_tab.py
│       ├── upscaler_tab.py
│       ├── presets_tab.py
│       └── history_tab.py
│
├── presets/                # curated basic presets
│   └── styles.py           # preset registry
│
├── upscaler/               # Real-ESRGAN NCNN backend
│   ├── upscaler.py         # interface + metadata
│   └── realesrgan.py       # NCNN wrapper
│
├── utils/                  # shared utilities
│   ├── history.py          # atomic storage format
│   ├── common.py           # PIL helpers
│   └── logger.py           # structured logging
│
└── config/                 # static configuration
├── paths.py            # resolved directories
└── settings.py         # environment settings

---

Presets (Included)

The project includes four style presets, each defining:

• prompt
• negative prompt

These presets are neutral and work with both SD1.5 and Turbo:

Name	Style
Realistic Photo	35mm, photorealistic
Anime	clean anime illustration
Cinematic / Moody	cinematic lighting/grain
Oil Painting	classical oil painting

Presets do not include LoRA parameters.
Users may manually combine presets with LoRA adapters.

---

Installation

Clone

git clone https://github.com/sanskarmodi8/stable-diffusion-image-generator
cd stable-diffusion-image-generator

Environment

python -m venv .venv
source .venv/bin/activate

Install Dependencies (CPU)

pip install -r requirements.txt
pip install -e .

GPU (optional)

pip install torch torchvision torchaudio \
  --index-url https://download.pytorch.org/whl/cu121

---

Run

python src/sdgen/main.py

Open in browser:

http://127.0.0.1:7860

---

Adding LoRA Models

Place .safetensors files here:

src/assets/loras/

They will be automatically detected and displayed in the UI (SD1.5 only).

This repository does not include LoRA files.

---

Third-Party LoRA Models

The app supports optional LoRA adapters. LoRA weights are not included and are the property of their respective authors.

If you choose to download LoRA files automatically (see lora_urls.py), they are fetched directly from their original sources (Civitai).

This project does not redistribute LoRA weights. Refer to each model’s license on Civitai.

---

Development

The repo uses pre-commit hooks for consistency:

pre-commit install

Tools:

• ruff
• black
• isort

Check formatting:

ruff check .
black .

---

License

This project is licensed under the MIT License. See the LICENSE file.

---

Author

Sanskar Modi