README.md

metadata

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 ResidualBlocks 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 ResidualBlocks; 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

License

MIT