{"id":38675947,"url":"https://github.com/wglab/pdidb","last_synced_at":"2026-01-17T10:01:02.112Z","repository":{"id":327158755,"uuid":"1108007259","full_name":"WGLab/PDIDB","owner":"WGLab","description":"Phenotype Diseased Image Synthesis Database","archived":false,"fork":false,"pushed_at":"2025-12-03T18:46:25.000Z","size":17125,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-04T20:33:19.969Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WGLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-01T22:40:49.000Z","updated_at":"2025-12-03T18:46:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/WGLab/PDIDB","commit_stats":null,"previous_names":["wglab/pdi-db"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/WGLab/PDIDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FPDIDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FPDIDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FPDIDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FPDIDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WGLab","download_url":"https://codeload.github.com/WGLab/PDIDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FPDIDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28505570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T10:00:39.937Z","updated_at":"2026-01-17T10:01:02.026Z","avatar_url":"https://github.com/WGLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PDIDB: Phenotype Diseased Image Synthesis Database \n\n\u003e **A StyleGAN3-based facial image synthesis database for rare genetic disease phenotypes**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![PyTorch](https://img.shields.io/badge/PyTorch-1.9+-ee4c2c.svg)](https://pytorch.org/)\n\n---\n\n## 📋 Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Model Architecture](#model-architecture)\n- [Synthetic Image Gallery](#synthetic-image-gallery)\n- [Interactive Web Gallery](#interactive-web-gallery)\n- [Getting Started](#getting-started)\n  - [1. Environment Setup](#1-environment-setup)\n  - [2. Data Preprocessing](#2-data-preprocessing)\n  - [3. Model Training](#3-model-training)\n  - [4. Generate Synthetic Images](#4-generate-synthetic-images)\n- [License](#license)\n\n---\n\n## Overview\n\nThis repository provides a **class-conditional StyleGAN3 model** trained to generate synthetic facial images representing patients with rare genetic diseases. The generated images capture disease-specific facial phenotype patterns (facial gestalt) and serve multiple purposes in computational biology and medical AI research.\n\n**Primary Use Cases:**\n- **Visualization** of disease-specific facial patterns learned from real patient data\n- **Generation of synthetic training/evaluation data** for rare disease facial recognition models\n- **Educational materials** and clinical teaching resources\n- **Data augmentation** for downstream phenotype analysis tasks\n- **Privacy-preserving research** by providing synthetic alternatives to real patient images\n\n\u003e ℹ️ **Important Note:** This repository focuses on **synthetic face generation** using StyleGAN3. It does not perform disease diagnosis. All generated images are fully synthetic and do not represent real patients.\n\n---\n\n## Key Features\n\n- ✨ **Class-conditional generation** across multiple rare genetic disease categories\n- 🎯 **Alias-free architecture** (StyleGAN3) for improved geometric consistency\n- 🖼️ **High-quality 224×224 resolution** synthetic faces compatible with standard computer vision pipelines\n- 🎮 **Controllable generation** with latent space manipulation capabilities\n- 🌐 **Interactive web gallery** for exploring generated samples by disease type, demographics, and other attributes\n\n---\n\n## Model Architecture\n\nThe model is based on **StyleGAN3** with the following key characteristics:\n\n- **Alias-free generator** ensuring better pose consistency and geometric transformations\n- **Conditional generation** supporting 10+ disease classes (configurable)\n- **Training data**: Preprocessed facial images from genetic disease patient databases\n- **Resolution**: 224×224 pixels (can be adjusted)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/figs/stylegan3_overview.png\" alt=\"StyleGAN3 architecture overview\" width=\"800\"\u003e\n\u003c/p\u003e\n\n---\n\n## Synthetic Image Gallery\n\nWe provide sample synthetic faces generated by our trained StyleGAN3 model across different disease categories:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/figs/synthetic_1.png\" alt=\"Synthetic samples per disease class - Set 1\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/figs/synthetic_2.png\" alt=\"Synthetic samples per disease class - Set 2\" width=\"800\"\u003e\n\u003c/p\u003e\n\n---\n\n## Interactive Web Gallery\n\nExplore our complete synthetic image database through an interactive web interface:\n\n**[🌐 Phenotype-Disease Synthetic Image Database](https://hongzhuochen.github.io/Phenotype-Disease-Image-Database-demo/)**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/figs/web_gallery_screenshot.png\" alt=\"Interactive web gallery interface\" width=\"800\"\u003e\n\u003c/p\u003e\n\n### Gallery Features:\n- **Browse by disease type**: Filter synthetic faces by specific genetic disease categories\n- **Demographic filtering**: Search by age range, gender, and ethnicity\n- **Metadata annotations**: View generation parameters and conditional attributes\n- **Download capability**: Export images for research and educational use\n- **High-quality samples**: Access almost hundreds of synthetic faces per disease class\n\n\u003e ⚠️ **Disclaimer**: All images in the gallery are **fully synthetic** and generated by StyleGAN3. They do not represent real patients and are intended solely for research and educational purposes. Please respect ethical guidelines when using these materials.\n\n---\n\n## Getting Started\n\n### 1. Environment Setup\n\n#### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/WGLab/PDI-DB.git\ncd PDI-DB\n\n# Create a new conda environment\nconda create -n PDI-DB python=3.8\n\n# Activate environment\nconda activate PDI-DB\n\n# Install PyTorch with CUDA support\npip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu118\n\n# Install other dependencies\npip install click pillow scipy numpy requests tqdm ninja matplotlib imageio\npip install imgui glfw pyopengl imageio-ffmpeg pyspng\n```\n\n---\n\n### 2. Data Preprocessing\n\nBefore training, you need to prepare your facial phenotype images in the correct format.\n\n#### Data Organization\n\nOrganize your raw images in the following structure:\n\n```\nraw_data/\n├── disease_0/\n│   ├── patient_001.jpg\n│   ├── patient_002.jpg\n│   └── ...\n├── disease_1/\n│   ├── patient_001.jpg\n│   ├── patient_002.jpg\n│   └── ...\n└── disease_N/\n    ├── patient_001.jpg\n    └── ...\n```\n\n\u003e 📊 **Note: Training Dataset Information**  \n\u003e The synthetic images showcased in this repository were generated using a model trained on 2,357 facial images across 11 categories:\n\u003e - **Disease images** (10 categories, 1,857 images): Cornelia de Lange Syndrome (447), Williams-Beuren Syndrome (273), Noonan Syndrome (217), Kabuki Syndrome (206), KBG Syndrome (179), Angelman Syndrome (160), Rubinstein-Taybi Syndrome (116), Smith-Magenis Syndrome (102), Nicolaides-Baraitser Syndrome (97), and 22q11.2 Deletion Syndrome (60). All disease images are sourced from the [GestaltMatcher Database (GMDB)](https://db.gestaltmatcher.org/).\n\u003e - **Healthy control images** (500 images): Selected from the [FFHQ dataset](https://github.com/NVlabs/ffhq-dataset) with age \u003c 20 years.\n\u003e\n\u003e You can also train the model on your own custom disease categories and sample sizes by following the data preprocessing steps below.\n\n#### Preprocessing Steps\n\n**Manual Preprocessing:**\n\n1. **Face Alignment**: Align all faces to a standard pose using landmark detection\n2. **Resolution**: Resize images to 224×224 pixels\n3. **Format**: Convert to PNG or JPG format\n4. **Quality Control**: Remove low-quality or ambiguous images\n\n#### Create Dataset ZIP\n\n```bash\npython dataset_tool.py \\\n    --source=raw_data/ \\\n    --dest=datasets/phenotype_disease_224x224.zip \\\n    --resolution=224x224\n```\n\n#### Dataset Structure\n\nThe final dataset should be a ZIP file containing:\n\n```\nphenotype_disease_224x224.zip\n├── 00000/\n│   ├── img00000000.png\n│   ├── img00000001.png\n│   └── ...\n├── 00001/\n│   └── ...\n└── dataset.json  # Metadata with class labels\n```\n\n**Example `dataset.json` format:**\n\n```json\n{\n  \"labels\": [\n    [\"img00000000.png\", 0],\n    [\"img00000001.png\", 0],\n    [\"img00000002.png\", 1]\n  ]\n}\n```\n\nWhere the second value in each pair is the disease class index (0, 1, 2, ..., N).\n\n---\n\n### 3. Model Training\n\n#### Basic Training Command\n\nTrain a class-conditional StyleGAN3 model on your phenotype dataset:\n\n```bash\npython train.py \\\n    --outdir=./training-runs \\\n    --data=./datasets/phenotype_disease_224x224.zip \\\n    --cfg=stylegan3-t \\\n    --gpus=8 \\\n    --batch=32 \\\n    --cond=True \\\n    --gamma=2 \\\n    --mirror=1 \\\n    --kimg=5000\n```\n\n#### Training Parameters\n\n| Parameter | Description | Recommended Value |\n|-----------|-------------|-------------------|\n| `--outdir` | Output directory for training results | `./training-runs` |\n| `--data` | Path to your preprocessed dataset ZIP | Required |\n| `--cfg` | Model configuration (`stylegan3-t`, `stylegan3-r`, `stylegan2`) | `stylegan3-t` |\n| `--gpus` | Number of GPUs to use | 1–8 |\n| `--batch` | Total batch size across all GPUs | 32 |\n| `--cond` | Enable class-conditional generation | `True` |\n| `--gamma` | R1 regularization weight | 2–8 |\n| `--mirror` | Enable horizontal flipping augmentation | `1` (enabled) |\n| `--kimg` | Training duration in thousands of images | 5000 |\n| `--snap` | Snapshot interval (in ticks) | 20 |\n\n#### Multi-GPU Training Example\n\n```bash\npython train.py \\\n    --outdir=./training-runs \\\n    --data=./datasets/phenotype_disease_224x224.zip \\\n    --cfg=stylegan3-t \\\n    --gpus=8 \\\n    --batch=32 \\\n    --cond=True \\\n    --gamma=2 \\\n    --mirror=1 \\\n    --kimg=5000 \\\n    --snap=20\n```\n\n#### Monitoring Training Progress\n\nTraining outputs are saved in timestamped directories:\n\n```\ntraining-runs/\n└── 00000-stylegan3-t-phenotype_disease_224x224-gpus8-batch32-gamma2/\n    ├── network-snapshot-000000.pkl    # Initial model\n    ├── network-snapshot-000100.pkl    # Checkpoint at 100k images\n    ├── fakes000000.png                # Sample images at start\n    ├── fakes000100.png                # Sample images at 100k\n    ├── training_stats.jsonl           # Training metrics\n    └── metric-fid50k_full.jsonl       # FID scores (if enabled)\n```\n\n**Key files to monitor:**\n\n- `fakes*.png`: Visual quality of generated images\n- `training_stats.jsonl`: Loss values and training metrics\n- `network-snapshot-*.pkl`: Model checkpoints\n\n---\n\n### 4. Generate Synthetic Images\n\nOnce training is complete, use the trained model to generate synthetic phenotype images.\n\n#### Generate Images for a Specific Disease Class\n\n```bash\npython gen_images.py \\\n    --network=./training-runs/00000-stylegan3-t-.../network-snapshot-005000.pkl \\\n    --outdir=./generated_images \\\n    --samples=100 \\\n    --class=0 \\\n    --trunc=1.0\n```\n\n#### Generation Parameters\n\n| Parameter | Description | Example |\n|-----------|-------------|---------|\n| `--network` | Path to trained model `.pkl` file | `network-snapshot-005000.pkl` |\n| `--outdir` | Output directory for generated images | `./generated_images` |\n| `--samples` | Number of images to generate | `100` |\n| `--class` | Disease class index (0, 1, 2, ...) | `0` |\n| `--trunc` | Truncation psi (0.5–1.0 for quality vs diversity) | `1.0` |\n\n#### Adjusting Image Quality and Diversity\n\nThe `--trunc` parameter controls the trade-off between quality and diversity:\n\n- **`--trunc=0.5`**: Higher quality, less diversity (more typical faces)\n- **`--trunc=0.7`**: Balanced quality and diversity\n- **`--trunc=1.0`**: Maximum diversity, lower average quality\n\n**Examples:**\n\n```bash\n# High quality, low diversity\npython gen_images.py --network=model.pkl --outdir=out_quality --samples=100 --class=0 --trunc=0.5\n\n# Balanced\npython gen_images.py --network=model.pkl --outdir=out_balanced --samples=100 --class=0 --trunc=0.7\n\n# High diversity\npython gen_images.py --network=model.pkl --outdir=out_diverse --samples=100 --class=0 --trunc=1.0\n```\n\n---\n\n## License\n\nThis project is licensed under the **MIT License**.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwglab%2Fpdidb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwglab%2Fpdidb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwglab%2Fpdidb/lists"}