---
license: mit
tags:
- diffusion
- ddpm
- image-generation
- conditional-image-generation
- pytorch
- sprite
pipeline_tag: unconditional-image-generation
---

# Diffusion-Sprite — Class-Conditional DDPM on 16x16 Sprites

A class-conditional Denoising Diffusion Probabilistic Model (DDPM) trained on a dataset of 16x16 pixel sprites. The model can generate sprites conditioned on one of 5 class labels.

## Model Description

This model implements DDPM (Ho et al., 2020) with a ContextUnet backbone that conditions the denoising process on class labels via context embedding. The architecture uses residual blocks with skip connections and a U-Net-style encoder-decoder structure.

### Architecture — ContextUnet

**Down path:**
- `UnetDown`: two stacked `ResidualBlock`s followed by `MaxPool2d(2)`

**Bottleneck:**
- `ResidualBlock` with is_res=True (residual shortcut)

**Up path:**
- `UnetUp`: `ConvTranspose2d(in, out, 2, 2)` for upsampling, followed by two `ResidualBlock`s; skip connection from corresponding down-path output is concatenated before upsampling

**Context conditioning:**
- Class label embedded and injected into the bottleneck and up-path features

**ResidualBlock:**
- Two `Conv2d(3x3) + BatchNorm2d + GELU` blocks; residual shortcut (with optional `1x1` projection) when `is_res=True`; output scaled by `1/sqrt(2)` for stable training

### Diffusion Process

- **Noise schedule:** Linear, `beta1=1e-4` to `beta2=0.02` over `T=500` timesteps
- **Alpha schedule:** `a_bt = cumprod(1 - b_t)` (cumulative product of alpha values)
- **Forward process:** `x_t = sqrt(a_bt[t]) * x_0 + sqrt(1 - a_bt[t]) * noise`
- **Loss:** MSE between predicted and actual noise (epsilon parameterization)

## Training Details

| Parameter | Value |
|---|---|
| Dataset | 1788 sprites, 16x16 RGB (sprites_1788_16x16.npy) |
| Class labels | 5 classes (sprite_labels_nc_1788_16x16.npy) |
| Epochs | 60 |
| Timesteps (T) | 500 |
| Batch size | 100 |
| Learning rate | 1e-3 (linear decay over epochs) |
| Optimizer | Adam |
| Input normalization | Normalize(0.5, 0.5) → [-1, 1] |
| Feature channels | n_feat=64, n_cfeat=5 |

## Checkpoints

| File | Epoch |
|---|---|
| checkpoints/model_Epoch20.pth | 20 |
| checkpoints/model_Epoch30.pth | 30 |
| checkpoints/model_Epoch31.pth | 31 |

## Repository Contents

| File | Description |
|---|---|
| models.py | ContextUnet, UnetDown, UnetUp, ResidualBlock |
| train.py | Training loop with DDPM noise schedule |
| utils.py | CustomDataset, helper transforms |
| model.ipynb | Notebook version |
| sprites_1788_16x16.npy | Sprite image data |
| sprite_labels_nc_1788_16x16.npy | Class label data |

## References

- Ho et al. (2020). [Denoising Diffusion Probabilistic Models](https://arxiv.org/abs/2006.11239)

## License

MIT