Processed Electric Sheep Dreams

A native desktop application for fast AI image generation with multiple SDNQ-quantized model options. Choose between speed-optimized (default), quality-optimized, or base models. Supports Text-to-Image, Image-to-Image transformation, and Inpainting with mask-based editing.

Architecture Overview

graph TD
    User[User Input] -->|Prompt & Settings| App[Desktop UI]
    App -->|Model Selection| Chooser{Model Chooser}
    
    Chooser -->|Default: Speed| Model1[Disty0/Z-Image-Turbo-SDNQ]
    Chooser -->|Quality| Model2[Abrahamm3r/Z-Image-SDNQ]
    Chooser -->|Base| Model3[Tongyi-MAI/Z-Image-Turbo]
    
    Model1 --> VN[VRAM Optimizer]
    Model2 --> VN
    Model3 --> VN
    
    VN -->|Load & Offload| Pipeline[Z-Image Pipeline]
    
    subgraph "Neural Engine"
        Pipeline -->|SDNQ Quant*| Transformer[Transformer Model]
        Pipeline -->|Smart Masking| Inpaint[Inpainting Logic]
    end
    
    Transformer -->|Latents| VAE[VAE Decoder]
    VAE -->|Raw Image| Post[Post-Processing]
    Post -->|Color Match/Edge Blend| Upscaler{Upscale?}
    
    Upscaler -->|Yes| SR[Swin2SR 2x]
    Upscaler -->|No| Output
    SR --> Output[Final Image + Metadata]
    
    Output --> Gallery[Gallery View]
    
    style Chooser fill:#ff6b6b
    style Model1 fill:#ffd93d
    style Model2 fill:#ff6b6b
    
    Note1[*SDNQ on quantized models]

With accurate text and subject rendering. Includes a MOAP (Mother of All (negative) Prompts) for better rendering.

---

⚡ Model Selection

NEW: Choose your preferred model in the Advanced Configuration section!

Note: Both Disty0 and Abrahamm3r models use SDNQ 4-bit quantization. Disty0 prioritizes faster generation, while Abrahamm3r prioritizes output quality.

How to Switch Models

1. Launch the application
2. Open Advanced Configuration (expand the section)
3. Select your preferred model from the Model dropdown
4. The selected model will load on startup

Tip: Changing the model requires restarting the application. The model selection persists during each session.

---

⌨️ Shortcuts

---

Screenshots

Main Interface

Prompt Entry with Advanced Configuration

Generated Result

---

Gallery

Sample images generated with Processed Electric Sheep Dreams:

Showcase with Prompts

---

Features

Generation Modes

• Text-to-Image: Generate images from text descriptions
• Image-to-Image: Transform existing images with text guidance
• Inpainting: Edit specific regions using masks (white = regenerate, black = preserve)

Inpainting Options

• Color Match: Transfers color/lighting statistics from source to generated regions
• Blend Edges: Feathers mask boundaries for seamless transitions
• Preserve Structure: Maintains edge contours from the source image
• Send to Remix: One-click workflow to instantly send a generated result to the input for iteration
• Gallery Strip: Persistent session history at the bottom of the viewport
• Open Output Folder: Quick access button 📂 to view your generated files

Note: Remix mode includes content filtering and cannot be used for NSFW image generation. Please use appropriate prompts when working with Remix mode.

Advanced Capabilities

• Model Selection: Choose between speed-optimized, quality-optimized, or base models
• LoRA Support: Drop .safetensors files into models/loras/ to dynamically load styles (Experimental)
• Smart Seed: Toggle between Random (-1) and Fixed seeds with a simple checkbox

Technical Features

• SDNQ 4-bit quantization on optimized models
• Automatic aspect ratio detection from source images
• Styles: Select from Cinematic, Anime, Cyberpunk, and more for instant aesthetic enhancements
• 2x AI Upscaling: Integrated Swin2SR for high-quality resolution boosting
• Invisible Watermarking: Embeds invisible SynthID-like signatures for authenticity (contains optional Device ID)
• Metadata Embedding: Full generation parameters (Prompt, Seed, Steps, Guidance) stored directly in PNG files
• TF32 Acceleration: Enabled on Ampere+ GPUs for faster inference

---

Requirements

• Python 3.10 or higher
• CUDA-compatible GPU with 8GB+ VRAM (recommended)
  • Quantized models can run on 6GB VRAM
• Windows, Linux, or macOS

---

Agentic & MCP Support

This project is MCP (Model Context Protocol) Compliant. You can run Run_MCP.bat or configure your agent (like Claude Desktop) to use mcp_server.py to:

• Generate images via text prompt
• Upscale images
• Check device status

Installation

1. Clone the repository:

git clone https://github.com/yourusername/processed-electric-sheep-dreams.git
cd processed-electric-sheep-dreams

2. Create and activate a virtual environment:

python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/macOS

3. Install dependencies:

pip install -r requirements.txt

4. Install PyTorch with CUDA support (if not already installed):

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

---

Quick Start (Windows)

For the easiest experience, just double-click Launch.bat. It will:

1. Check for Python installation
2. Create a virtual environment (first run only)
3. Install all dependencies (first run only)
4. Launch the application

Note: First launch takes several minutes to set up. Subsequent launches are fast.

---

Usage

Launch the application:

python app.py

Interface Overview

Generation Parameters

Inpainting Workflow

1. Switch to the REMIX tab
2. Upload a reference image
3. Upload a mask image (white areas will be regenerated)
4. Enter a prompt describing what to generate in masked areas
5. Adjust strength and enable desired post-processing options
6. Click “INITIATE RENDER”

---

Project Structure

processed-electric-sheep-dreams/
├── app.py           # GUI application (ttkbootstrap)
├── backend.py       # Image generation engine
├── mcp_server.py    # MCP server for agentic access
├── requirements.txt # Python dependencies
├── Launch.bat       # One-click launcher (Windows)
└── README.md        # This file

---

Model Information

This application supports multiple models with easy switching:

Speed-Optimized (Default) ⭐

Disty0/Z-Image-Turbo-SDNQ-uint4-svd-r32

• 4-bit SDNQ quantization optimized for maximum speed
• Fastest generation times
• ~3GB download, ~4GB VRAM
• Excellent quality with minimal compromise

Quality-Optimized

Abrahamm3r/Z-Image-SDNQ-uint4-svd-r32

• 4-bit SDNQ quantization optimized for maximum quality
• Superior output fidelity
• ~3GB download, ~4GB VRAM
• Created by @Abrahamm3r (Self/OP)

Base Model

Tongyi-MAI/Z-Image-Turbo

• Full precision model without quantization
• Original Z-Image architecture
• ~5GB download, ~6GB VRAM

Both Disty0 and Abrahamm3r models use SDNQ quantization, making them efficient on GPUs with limited VRAM. Models are automatically downloaded on first run.

Performance Notes

• First generation may be slower due to model initialization
• Generation speed depends on resolution and GPU capability
• Lower dimensions (1024x1024) generate faster than higher resolutions
• Speed vs Quality: Disty0 generates ~15-20% faster; Abrahamm3r produces slightly higher fidelity
• LoRA Note: Quantized models use int4 precision. Some standard fp16 LoRAs may not apply correctly or may degrade quality. This feature is experimental.

---

Troubleshooting

Common Issues

“Height must be divisible by 16”

• Adjust dimensions to multiples of 16 (e.g., 1024, 1280, 1536)

CUDA out of memory

• Use Disty0 or Abrahamm3r quantized models (lower VRAM)
• Reduce output resolution
• Close other GPU-intensive applications
• The application uses CPU offload to minimize VRAM requirements

Slow generation

• Ensure CUDA is properly installed
• Use Disty0 for fastest generation
• Lower the number of inference steps
• Reduce image resolution

---

License

This project is provided as-is for educational and personal use. The underlying models may have their own licensing terms.

---

Acknowledgments & Citations

Speed-Optimized Model (Default)

• Z-Image-Turbo-SDNQ-uint4-svd-r32 by @Disty0
  • 4-bit SDNQ quantization optimized for speed
  • Original SDNQ quantization implementation

Quality-Optimized Model

• Z-Image-SDNQ-uint4-svd-r32 by @Abrahamm3r
  • 4-bit SDNQ quantization optimized for quality
  • Superior output fidelity with efficient inference

Base Model

• Z-Image-Turbo by Tongyi-MAI
  • Original Z-Image architecture optimized for turbo generation

Infrastructure & Tools

• Diffusers by Hugging Face
  • Diffusion model pipeline framework
• SDNQ for quantization support
  • Structured Differentiable Neural Quantization
• Swin2SR for upscaling
  • AI-powered 2x super-resolution