---
license: mit
---
# Pixel

A PyTorch-based Generative Adversarial Network (GAN) for training and generating CryptoPunk-style pixel art images.

## Table of Contents

- [Overview](#overview)
- [Project Structure](#project-structure)
- [Architecture](#architecture)
- [Workflow](#workflow)
- [Installation](#installation)
- [User Guide](#user-guide)
- [Configuration](#configuration)
- [Examples](#examples)

---

## Overview

This project implements a Deep Convolutional GAN (DCGAN) to generate pixel art images. It includes:

- **Training Pipeline**: Train a GAN model on your custom image dataset
- **Image Generation**: Generate new images using trained models
- **Interactive GUI**: Tkinter-based interface for real-time generation
- **GGUF Support**: Convert and use GGUF quantized models

---

## Project Structure

```
ai-picture-model-trainer/
│
├── trainer.py                  # GAN training script
├── generator.py                # Image generation (GUI + CLI)
│
├── data/                       # Training data
│   ├── attributes.csv          # Dataset metadata
│   └── images/                 # Training images (punk000.png, punk001.png, ...)
│
├── models/                     # Trained model storage
│   └── generator_model.safetensors
│
├── generated/                  # Generated image outputs
│   ├── output.png              # Grid visualizations
│   └── individual/             # Individual generated images
│
├── gen_images/                 # Training progress images
│   ├── epoch_0.png
│   ├── epoch_1.png
│   └── ...
│
└── gguf/                       # GGUF format support
    └── generator.py            # GGUF model converter/generator
```

### Directory Purpose

| Directory | Purpose |
|-----------|---------|
| `data/` | Input training images and metadata |
| `models/` | Saved trained models (.safetensors format) |
| `generated/` | Output from generator.py |
| `gen_images/` | Training progress visualizations |
| `gguf/` | GGUF quantized model support |

---

## Architecture

### GAN Components

```
┌─────────────────────────────────────────────────────────────┐
│                      GAN Architecture                        │
└─────────────────────────────────────────────────────────────┘

┌──────────────────┐                    ┌──────────────────┐
│   Generator      │                    │  Discriminator   │
│                  │                    │                  │
│  Input: Noise    │                    │  Input: Images   │
│  (100-dim)       │                    │  (24x24x4)       │
│                  │                    │                  │
│  ┌────────────┐  │                    │  ┌────────────┐  │
│  │   FC       │  │                    │  │   Conv2D   │  │
│  │  (9,216)   │  │                    │  │  64 filters│  │
│  └────────────┘  │                    │  └────────────┘  │
│        ↓         │                    │        ↓         │
│  ┌────────────┐  │                    │  ┌────────────┐  │
│  │ Reshape    │  │    ┌──────────┐    │  │   Conv2D   │  │
│  │ (256,6,6)  │  │───→│  Real or │←───│  │ 128 filters│  │
│  └────────────┘  │    │   Fake?  │    │  └────────────┘  │
│        ↓         │    └──────────┘    │        ↓         │
│  ┌────────────┐  │                    │  ┌────────────┐  │
│  │ ConvTrans  │  │                    │  │   Conv2D   │  │
│  │ 128 filters│  │                    │  │ 256 filters│  │
│  └────────────┘  │                    │  └────────────┘  │
│        ↓         │                    │        ↓         │
│  ┌────────────┐  │                    │  ┌────────────┐  │
│  │ ConvTrans  │  │                    │  │  GlobalAvg │  │
│  │  64 filters│  │                    │  │    Pool    │  │
│  └────────────┘  │                    │  └────────────┘  │
│        ↓         │                    │        ↓         │
│  ┌────────────┐  │                    │  ┌────────────┐  │
│  │ ConvTrans  │  │                    │  │  FC + Sig  │  │
│  │  4 channels│  │                    │  │  (0-1)     │  │
│  └────────────┘  │                    │  └────────────┘  │
│                  │                    │                  │
│  Output: Image   │                    │  Output: Score   │
│  (24x24x4 RGBA)  │                    │  (Real/Fake)     │
└──────────────────┘                    └──────────────────┘
```

### Model Details

**Generator**:
- Input: 100-dimensional latent vector (random noise)
- Architecture: FC → BatchNorm → 3x ConvTranspose2D with BatchNorm
- Output: 24x24x4 RGBA image (values in [-1, 1])
- Activation: LeakyReLU + Tanh (output)

**Discriminator**:
- Input: 24x24x4 RGBA image
- Architecture: 3x Conv2D with Dropout → GlobalAvgPool → FC
- Output: Probability score [0, 1] (real vs. fake)
- Activation: LeakyReLU + Sigmoid (output)

---

## Workflow

### Training Workflow

```
┌─────────────┐
│  Start      │
└──────┬──────┘
       │
       ▼
┌──────────────────────┐
│  Load Dataset        │
│  (data/images/)      │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│  Initialize Models   │
│  - Generator         │
│  - Discriminator     │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│  Training Loop       │◄─────────┐
│  (N epochs)          │          │
└──────┬───────────────┘          │
       │                          │
       ▼                          │
┌──────────────────────┐          │
│  For each batch:     │          │
│  1. Train Discrim.   │          │
│  2. Train Generator  │          │
└──────┬───────────────┘          │
       │                          │
       ▼                          │
┌──────────────────────┐          │
│  Save Progress       │          │
│  (gen_images/)       │──────────┘
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│  Save Final Model    │
│  (models/*.safetensors)
└──────┬───────────────┘
       │
       ▼
┌──────────────┐
│  Complete    │
└──────────────┘
```

### Generation Workflow

```
┌─────────────────────┐
│  Mode Selection     │
└──────┬──────────────┘
       │
       ├─────────────────────────┐
       │                         │
       ▼                         ▼
┌──────────────┐       ┌──────────────────┐
│  GUI Mode    │       │   CLI Mode       │
└──────┬───────┘       └──────┬───────────┘
       │                      │
       ▼                      ▼
┌──────────────┐       ┌──────────────────┐
│ Load Model   │       │ Load Model       │
│ (safetensors)│       │ Parse Args       │
└──────┬───────┘       └──────┬───────────┘
       │                      │
       ▼                      ▼
┌──────────────┐       ┌──────────────────┐
│ Tkinter GUI  │       │ Generate N Images│
│ - Button 1x1 │       │ - Custom grid    │
│ - Button 3x3 │       │ - Custom seed    │
│ - Button 5x5 │       │ - Save options   │
└──────┬───────┘       └──────┬───────────┘
       │                      │
       ▼                      ▼
┌──────────────┐       ┌──────────────────┐
│ On Click:    │       │ Save Grid        │
│ Generate     │       │ Save Individual  │
│ Display      │       │ (optional)       │
└──────┬───────┘       └──────────────────┘
       │
       ▼
┌──────────────┐
│ Interactive  │
│ Generation   │
└──────────────┘
```

---

## Installation

### Prerequisites

- Python 3.8+
- CUDA-compatible GPU (optional, for faster training)

### Setup

1. **Clone/Download the repository**

2. **Install dependencies**:

```bash
pip install torch torchvision
pip install numpy pandas matplotlib pillow
pip install safetensors
```

3. **Prepare your dataset**:

Place your training images in `data/images/` with filenames like `punk000.png`, `punk001.png`, etc.

Create `data/attributes.csv`:
```csv
id
0
1
2
...
```

---

## User Guide

### 1. Training a Model

Train the GAN on your dataset:

```bash
python trainer.py \
    --data_path ./data/attributes.csv \
    --images_path ./data/images/ \
    --model_output_path ./models/ \
    --images_output_path ./gen_images/ \
    --epochs 50 \
    --batch_size 16
```

**Training Parameters**:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `--data_path` | `./data/attributes.csv` | Path to dataset metadata |
| `--images_path` | `./data/images/` | Directory containing training images |
| `--model_output_path` | `./models/` | Where to save trained model |
| `--images_output_path` | `./gen_images/` | Save progress images during training |
| `--epochs` | `50` | Number of training epochs |
| `--batch_size` | `16` | Training batch size |
| `--codings_size` | `100` | Latent vector dimension |
| `--image_size` | `24` | Output image size (24x24) |
| `--image_channels` | `4` | Image channels (4=RGBA, 3=RGB) |

**Training Output**:
- Progress displayed: `Epoch X/Y - Gen Loss: X.XXXX, Disc Loss: X.XXXX`
- Progress images saved to `gen_images/epoch_N.png`
- Final model saved to `models/generator_model.safetensors`

---

### 2. Generating Images

#### Option A: Interactive GUI Mode (Default)

Launch the Tkinter GUI for real-time generation:

```bash
python generator.py
```

or explicitly:

```bash
python generator.py --gui
```

**GUI Controls**:
- **Generate 1 cryptopunk**: Single image
- **Generate 3x3 cryptopunks**: 3x3 grid (9 images)
- **Generate 5x5 cryptopunks**: 5x5 grid (25 images)
- **Terminate**: Close the application

---

#### Option B: Command-Line Interface (CLI)

Batch generate images from terminal:

**Basic generation** (16 images):
```bash
python generator.py --num_images 16 --output_path ./generated/output.png
```

**Custom grid** (8x8 = 64 images):
```bash
python generator.py --grid_size 8 --output_path ./generated/grid_8x8.png
```

**Reproducible generation** (with seed):
```bash
python generator.py --grid_size 4 --seed 42 --output_path ./generated/seed42.png
```

**Save individual images**:
```bash
python generator.py \
    --num_images 100 \
    --save_individual \
    --individual_output_dir ./generated/individual/ \
    --output_path ./generated/batch.png
```

**CLI Parameters**:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `--model_path` | `./models/generator_model.safetensors` | Path to trained model |
| `--output_path` | `./generated/output.png` | Output path for grid image |
| `--num_images` | `16` | Number of images to generate |
| `--grid_size` | `None` | Grid size N for NxN layout |
| `--seed` | `None` | Random seed for reproducibility |
| `--save_individual` | `False` | Save each image separately |
| `--individual_output_dir` | `./generated/individual/` | Directory for individual images |

---

### 3. GGUF Model Support

Use quantized GGUF models for smaller file sizes:

```bash
cd gguf/
python generator.py
```

The GGUF generator will:
1. Detect available `.gguf` files in the directory
2. Prompt you to select a model
3. Convert GGUF → SafeTensors format
4. Launch the standard generator

---

## Configuration

### Model Architecture Configuration

Modify these parameters in both `trainer.py` and `generator.py`:

```python
--codings_size 100        # Latent vector dimension
--image_size 24           # Output image size
--image_channels 4        # RGBA (4) or RGB (3)
```

### Training Hyperparameters

In `trainer.py`:

```python
# Optimizer
gen_optimizer = optim.RMSprop(generator.parameters(), lr=0.001)
disc_optimizer = optim.RMSprop(discriminator.parameters(), lr=0.001)

# Loss function
criterion = nn.BCELoss()

# Dropout rate (in Discriminator)
nn.Dropout(0.4)
```

### Data Preprocessing

In `trainer.py` → `ImageDataset`:

```python
transforms.Compose([
    transforms.Resize((image_size, image_size)),
    transforms.ToTensor(),
    transforms.Normalize([0.5] * channels, [0.5] * channels)  # [-1, 1]
])
```

---

## Examples

### Example 1: Train on Custom Dataset

```bash
# Prepare your data
# data/images/punk000.png, punk001.png, ..., punk099.png
# data/attributes.csv with ids 0-99

# Train for 100 epochs
python trainer.py \
    --data_path ./data/attributes.csv \
    --images_path ./data/images/ \
    --epochs 100 \
    --batch_size 32 \
    --model_output_path ./models/my_model.safetensors
```

### Example 2: Generate with Specific Seed

```bash
# Generate same images every time
python generator.py \
    --model_path ./models/generator_model.safetensors \
    --grid_size 5 \
    --seed 12345 \
    --output_path ./results/reproducible.png
```

### Example 3: Batch Generation

```bash
# Generate 1000 individual images
python generator.py \
    --num_images 1000 \
    --save_individual \
    --individual_output_dir ./dataset_synthetic/ \
    --output_path ./dataset_synthetic/overview.png
```

### Example 4: Monitor Training Progress

```bash
# Training with progress visualization
python trainer.py \
    --epochs 200 \
    --images_output_path ./training_progress/

# View progress images
ls ./training_progress/
# epoch_0.png, epoch_1.png, ..., epoch_199.png
```

---

## Technical Details

### Model File Format

Models are saved in **SafeTensors** format (`.safetensors`) with embedded metadata:

```python
metadata = {
    'codings_size': '100',
    'image_size': '24',
    'image_channels': '4'
}
```

This ensures the generator automatically loads the correct architecture.

### Image Value Ranges

- **Training**: Images normalized to [-1, 1]
- **Generation output**: Images scaled to [0, 1]
- **Saved files**: Images saved as uint8 [0, 255]

### GPU Support

The code automatically detects and uses CUDA if available:

```python
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
```

---

## Troubleshooting

**Q: Training loss not decreasing?**
- Try adjusting learning rates
- Increase batch size or epochs
- Check if dataset has sufficient variety

**Q: Generated images look like noise?**
- Model needs more training epochs
- Dataset may be too small (need 50+ images minimum)
- Try adjusting discriminator dropout rate

**Q: GUI not launching?**
- Check Tkinter installation: `python -m tkinter`
- On Linux: `sudo apt-get install python3-tk`

**Q: CUDA out of memory?**
- Reduce batch size: `--batch_size 8`
- Reduce image size: `--image_size 16`

---

## License

This project is provided as-is for educational and creative purposes.

---

## Acknowledgments

- Built with PyTorch
- Inspired by DCGAN architecture
- Uses SafeTensors for model serialization