---

What is PyTorch Connectomics?

Automatic segmentation of neural structures in electron microscopy images 🔬🧠

PyTorch Connectomics (PyTC) helps neuroscientists:

• ✅ Segment mitochondria, synapses, and neurons in 3D EM volumes
• ✅ Train models without deep ML expertise
• ✅ Process large-scale connectomics datasets efficiently

Built on: PyTorch Lightning + MONAI for modern, scalable deep learning.

Used by: Harvard, MIT, Janelia Research Campus, and 100+ labs worldwide.

---

Quick Start (5 Minutes)

1. Install

Choose your preferred method:

🚀 One-Command Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/zudi-lin/pytorch_connectomics/refs/heads/master/quickstart.sh | bash
conda activate pytc

Done! ✅

🐍 Python Script Install

git clone https://github.com/zudi-lin/pytorch_connectomics.git
cd pytorch_connectomics
python install.py
conda activate pytc

🛠️ Manual Install

conda create -n pytc python=3.10 -y
conda activate pytc
conda install -c conda-forge numpy h5py cython connected-components-3d -y
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
git clone https://github.com/zudi-lin/pytorch_connectomics.git
cd pytorch_connectomics
pip install -e . --no-build-isolation

📖 Detailed instructions: INSTALLATION.md | 🚀 Quick start: QUICKSTART.md

---

2. Run Demo

Verify your installation with a 30-second demo:

python scripts/main.py --demo

Expected output:

🎯 PyTorch Connectomics Demo Mode
...
✅ DEMO COMPLETED SUCCESSFULLY!

---

3. Try a Tutorial

Train on real mitochondria segmentation data:

# Download tutorial data (~100 MB)
mkdir -p datasets/
wget https://huggingface.co/datasets/pytc/tutorial/resolve/main/Lucchi%2B%2B.zip
unzip Lucchi++.zip -d datasets/
rm Lucchi++.zip

# Quick test (1 batch)
python scripts/main.py --config tutorials/monai_lucchi++.yaml --fast-dev-run

# Full training
python scripts/main.py --config tutorials/monai_lucchi++.yaml

Monitor progress:

tensorboard --logdir outputs/lucchi++_monai_unet

---

Key Features

🚀 Modern Architecture (v2.0)

• PyTorch Lightning: Automatic distributed training, mixed precision, callbacks
• MONAI: Medical imaging models, transforms, losses optimized for 3D volumes
• Hydra/OmegaConf: Type-safe configurations with CLI overrides
• Extensible: Easy to add custom models, losses, and transforms

🏗️ State-of-the-Art Models

• MONAI Models: BasicUNet3D, UNet, UNETR, Swin UNETR
• MedNeXt (MICCAI 2023): ConvNeXt-based architecture for medical imaging
• Custom Models: Easily integrate your own architectures

⚡ Performance

• Distributed Training: Automatic multi-GPU with DDP
• Mixed Precision: FP16/BF16 training for 2x speedup
• Efficient Data Loading: Pre-loaded caching, MONAI transforms
• Gradient Accumulation: Train with large effective batch sizes

📊 Monitoring & Logging

• TensorBoard: Training curves, images, metrics
• Weights & Biases: Experiment tracking (optional)
• Early Stopping: Automatic stopping when training plateaus
• Checkpointing: Save best models automatically

---

Documentation

• 🚀 Quick Start Guide - Get running in 5 minutes
• 📦 Installation Guide - Detailed setup instructions
• 📚 Full Documentation - Complete reference
• 🎯 Tutorials - Example configurations
• 🔧 Troubleshooting - Common issues and solutions
• 👨‍💻 Developer Guide - Contributing and architecture

---

Example: Train a Model

Create a config file (my_config.yaml):

system:
  training:
    num_gpus: 1
    num_cpus: 4
    batch_size: 2

model:
  architecture: monai_basic_unet3d
  in_channels: 1
  out_channels: 2
  loss_functions: [DiceLoss]

data:
  train_image: "path/to/train_image.h5"
  train_label: "path/to/train_label.h5"
  patch_size: [128, 128, 128]

optimization:
  max_epochs: 100
  precision: "16-mixed"  # Mixed precision for speed

optimizer:
  name: AdamW
  lr: 1e-4

Train:

python scripts/main.py --config my_config.yaml

Override from CLI:

python scripts/main.py --config my_config.yaml data.batch_size=4 optimization.max_epochs=200

---

Supported Models

MONAI Models

• BasicUNet3D - Fast, simple 3D U-Net (recommended for beginners)
• UNet - U-Net with residual units
• UNETR - Transformer-based architecture
• Swin UNETR - Swin Transformer U-Net

MedNeXt Models (MICCAI 2023)

• MedNeXt-S - 5.6M parameters (fast)
• MedNeXt-B - 10.5M parameters (balanced)
• MedNeXt-M - 17.6M parameters (accurate)
• MedNeXt-L - 61.8M parameters (state-of-the-art)

See: .claude/MEDNEXT.md for MedNeXt integration guide

---

Data Formats

• HDF5 (.h5) - Primary format (recommended)
• TIFF (.tif, .tiff) - Multi-page TIFF stacks
• Zarr - For large-scale datasets
• NumPy - Direct array loading

Input shape: (batch, channels, depth, height, width)

---

Community & Support

• 💬 Slack: Join our community (friendly and helpful!)
• 🐛 Issues: GitHub Issues
• 📧 Contact: See lab website
• 📄 Paper: arXiv:2112.05754

---

Citation

If PyTorch Connectomics helps your research, please cite:

@article{lin2021pytorch,
  title={PyTorch Connectomics: A Scalable and Flexible Segmentation Framework for EM Connectomics},
  author={Lin, Zudi and Wei, Donglai and Lichtman, Jeff and Pfister, Hanspeter},
  journal={arXiv preprint arXiv:2112.05754},
  year={2021}
}

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas where we need help:

• 🏗️ New model architectures
• 🧩 Additional loss functions
• 🔧 Data augmentation techniques
• 📖 Documentation improvements
• 🐛 Bug fixes and optimizations

---

Acknowledgements

Powered by:

• PyTorch Lightning - Lightning AI Team
• MONAI - MONAI Consortium
• MedNeXt - DKFZ Medical Image Computing

Supported by:

• NSF awards IIS-1835231, IIS-2124179, IIS-2239688

---

License

MIT License - See LICENSE for details.

Copyright © PyTorch Connectomics Contributors

---

Version History

• v2.0 (2025) - Complete rewrite with PyTorch Lightning + MONAI
• v1.0 (2021) - Initial release

See RELEASE_NOTES.md for detailed release notes.

---