A conditional Deep Convolutional Generative Adversarial Network (DCGAN) for generating synthetic dermoscopic skin lesion images based on the HAM10000 dataset. This project implements class-conditional image generation for 7 different types of skin lesions with support for both 64Γ64 and 128Γ128 resolutions.
This project trains a conditional GAN to generate realistic synthetic dermoscopic images of skin lesions across 7 diagnostic categories. The model can generate high-quality 64x64 or 128x128 images conditioned on specific disease classes.
- akiec - Actinic keratoses and intraepithelial carcinoma
- bcc - Basal cell carcinoma
- bkl - Benign keratosis-like lesions
- df - Dermatofibroma
- mel - Melanoma
- nv - Melanocytic nevi
- vasc - Vascular lesions
- Conditional Generation: Generate synthetic images for specific disease classes
- Multi-Resolution Support: Configurable 64Γ64 and 128Γ128 image generation
- Modern PyTorch Implementation: Fully type-hinted, well-documented codebase
- Flexible Training Pipeline: Configurable hyperparameters and training options
- Model Checkpointing: Save and resume training with automatic checkpoint management
- Real-time Monitoring: Generate sample images during training to track progress
- Quality Metrics: Built-in Inception Score calculation for model evaluation
- Professional Logging: Color-coded console output with multiple log levels
- Reproducibility: Fixed random seeds across PyTorch, NumPy, and CUDA
- Cross-Platform: Compatible with Windows, Linux, and macOS
- CPU/GPU Flexibility: Seamless switching between CPU and GPU training
- Python 3.8 or higher
torch>=2.0.0
torchvision>=0.15.0
numpy>=1.20.0
pandas>=1.3.0
pillow>=8.0.0
matplotlib>=3.3.0
colorama>=0.4.4- Clone or download the repository
cd HamGenAI- Install dependencies
pip install torch torchvision numpy pandas pillow matplotlib coloramaFor GPU support (recommended):
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118- Prepare the HAM10000 dataset
Place the HAM10000 dataset in one of the following structures:
Option 1: In project root
HamGenAI/
βββ HAM10000_metadata.csv
βββ HAM10000_images_part_1/
β βββ *.jpg
βββ HAM10000_images_part_2/
βββ *.jpg
Option 2: In separate data directory (update IMG_PATH in config.py)
data/
βββ HAM10000_metadata.csv
βββ HAM10000_images_part_1/
β βββ *.jpg
βββ HAM10000_images_part_2/
βββ *.jpg
Basic training:
python main.pyTraining with all features enabled:
python main.py --save_best_model --save_generated_images --verboseTraining on CPU only:
python main.py --use_cpu| Argument | Description |
|---|---|
--use_cpu |
Force CPU usage even if GPU is available |
--load_model |
Load pre-trained generator instead of training |
--save_best_model |
Save model checkpoints every 5 epochs |
--save_generated_images |
Save generated image samples during training |
--verbose |
Print detailed loss information during training |
Using the command-line script:
python use_generator.pyProgrammatic usage:
from use_generator import load_generator, generate_images, generate_single_class
# Load pre-trained generator
generator = load_generator()
# Generate 9 random images across all classes
images, labels = generate_images(generator, n_images=9, seed=42)
# Generate images of a specific class (melanoma)
melanoma_images, labels = generate_single_class(generator, 'mel', n_images=9)
# Generate images for all classes
from use_generator import generate_all_classes
all_images, labels = generate_all_classes(generator, images_per_class=3)
# Calculate Inception Score for quality evaluation
from inception_score import calculate_inception_score
images_tensor = torch.stack([images for images, _ in generate_images(generator, 50)])
score_mean, score_std = calculate_inception_score(images_tensor)HamGenAI/
βββ config.py # Configuration and hyperparameters
βββ data_loader.py # Dataset loading and preprocessing
βββ generator_adversarial_nets.py # Generator and Discriminator architectures
βββ train.py # Training loop and utilities
βββ main.py # Command-line interface for training
βββ use_generator.py # Image generation and inference utilities
βββ logger.py # Colored logging system
βββ inception_score.py # Inception Score evaluation
βββ test_gpu.py # GPU testing utility
βββ architecture_test.py # Model architecture debugging
βββ conditional_vae_experiments.ipynb # VAE experiments notebook
βββ HAM10000_metadata.csv # Dataset metadata
βββ models/ # Saved model checkpoints
β βββ generator.pth
β βββ discriminator.pth
βββ output/ # Generated images during training
βββ __pycache__/ # Python cache files
Edit config.py to customize:
# Training parameters
NUM_EPOCHS = 200 # Number of training epochs
BATCH_SIZE = 64 # Batch size (auto-adjusted for image size)
LEARNING_RATE = 0.0002 # Learning rate for Adam optimizer
BETA_1 = 0.5 # Beta1 for Adam optimizer
BETA_2 = 0.999 # Beta2 for Adam optimizer
# Architecture
IMAGE_SIZE = 64 # Image resolution (64 or 128)
nz = 128 # Latent vector dimension
ngf = 128 # Generator feature maps
ndf = 64 # Discriminator feature maps
# System
SEED = 42 # Random seed for reproducibility
NUM_WORKERS = 0 # Data loader workers (0 for Windows)- Input: Noise vector (128-dim) + One-hot class label (7-dim)
- Architecture: Transposed convolutional layers
- Output: RGB image (64Γ64 or 128Γ128)
- Activation: Tanh (output range: [-1, 1])
- Input: RGB image + One-hot class label
- Architecture: Convolutional layers with LeakyReLU
- Output: Real/fake probability
- Activation: Sigmoid
- Train discriminator on real and fake images
- Train generator to fool the discriminator
- Alternating optimization using Adam
- Binary cross-entropy loss
- Generator Parameters: ~31.6M (64Γ64) or ~126M (128Γ128)
- Discriminator Parameters: ~2.8M (64Γ64) or ~11.2M (128Γ128)
- Training Time: ~2-3 hours on GPU (200 epochs, 64Γ64)
- Memory Requirements: ~2GB GPU memory (64Γ64), ~4GB (128Γ128)
The model generates realistic synthetic skin lesion images that can be used for:
- Data augmentation in medical image analysis
- Training datasets for classification models
- Research and educational purposes
- Privacy-preserving medical image sharing
Generator Network (Generator64 / Generator128):
- Conditional architecture with label embedding
- Transposed convolutional layers for upsampling
- Batch normalization for training stability
- ReLU activation in hidden layers, Tanh output
- Parameters: ~31.6M (64Γ64) or ~126M (128Γ128)
Discriminator Network (Discriminator64 / Discriminator128):
- Conditional architecture with label embedding
- Convolutional layers with stride 2 for downsampling
- LeakyReLU activation with negative slope 0.2
- Dropout for regularization
- Parameters: ~2.8M (64Γ64) or ~11.2M (128Γ128)
Training Pipeline:
- Binary Cross-Entropy loss with logits
- Adam optimizer with Ξ²β=0.5, Ξ²β=0.999
- Alternating discriminator and generator updates
- Learning rate: 0.0002
- Gradient clipping for stability
Data Processing:
- Image resizing and normalization to [-1, 1]
- One-hot encoding for class labels
- Automatic train/validation/test split (70/15/15)
- Data augmentation ready
- Type Safety: Comprehensive type hints throughout codebase
- Documentation: Detailed docstrings following Google style
- Error Handling: Robust error handling with informative messages
- Modularity: Clean separation of concerns across modules
- Reproducibility: Deterministic training with fixed seeds
- Monitoring: Real-time loss tracking and image generation
If you use this code or the HAM10000 dataset in your research, please cite:
@article{tschandl2018ham10000,
title={The HAM10000 dataset, a large collection of multi-source dermatoscopic images of common pigmented skin lesions},
author={Tschandl, Philipp and Rosendahl, Cliff and Kittler, Harald},
journal={Scientific data},
volume={5},
number={1},
pages={1--9},
year={2018},
publisher={Nature Publishing Group}
}CUDA not available:
- Install PyTorch with CUDA support:
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 - Or use
--use_cpuflag for CPU training
Out of memory:
- Reduce
BATCH_SIZEin config.py - Use smaller
IMAGE_SIZE(64 instead of 128) - Enable gradient checkpointing
Dataset not found:
- Ensure
HAM10000_metadata.csvis in the correct location - Check that image folders are named correctly
- Verify file paths in config.py
This project is provided for educational and research purposes. Please ensure you have the appropriate permissions to use the HAM10000 dataset.
Contributions are welcome! Areas for improvement:
-
Architecture Enhancements:
- Support for higher resolutions (256Γ256, 512Γ512)
- Progressive GAN training implementation
- StyleGAN2/StyleGAN3 architecture
- Self-attention mechanisms
-
Evaluation Metrics:
- FrΓ©chet Inception Distance (FID)
- Kernel Inception Distance (KID)
- Precision and Recall metrics
- Medical image quality assessment
-
Training Improvements:
- Spectral normalization
- Gradient penalty (WGAN-GP)
- Mixed precision training
- Distributed training support
-
Dataset Support:
- Additional medical imaging datasets
- Multi-modal image generation
- Cross-dataset training
For questions, issues, or suggestions, please open an issue on the project repository.
- HAM10000 dataset creators
- PyTorch team for the excellent deep learning framework
- DCGAN paper authors for the architecture inspiration