DARE3D is a deep learning framework for detecting cell divisions in 3D biological image volumes and estimating their key attributes. This Python implementation leverages PyTorch Lightning and Hydra for configuration management to provide a flexible, reproducible pipeline for:
- Segmentation: Detect the center of cell divisions, defined as the barycenter between the two daughter cells.
- Regression: Estimate the
- Orientation angle
- Division axis length between the two daughter cells.
The framework supports both training from custom datasets and inference on new data using pre-trained models.
The easiest way to get started is with the included demo dataset and pre-trained weights (downloaded automatically from Zenodo on first run):
# 1. Clone the repository
git clone https://github.com/JFRupprecht-OM/DARE3d
cd DARE3d
# 2. Create and activate conda environment
conda create -n dare3d python=3.10
conda activate dare3d
# 3. Install PyTorch (adapt CUDA version if needed)
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# 4. Install DARE3D and dependencies
pip install -r requirements.txt
pip install -e .
# 5. Run the prediction notebook
# Open and run: Run_dare3d_Prediction.ipynbNote: The demo dataset and pre-trained models (segmentation & regression) will be automatically downloaded on first use. No manual setup needed!
- Python 3.10
- CUDA 11.8+ (for GPU training) or CPU-only mode
- Conda (recommended)
# 1. Clone the repository
git clone https://github.com/JFRupprecht-OM/DARE3d
cd DARE3d
# 2. Initialize your shell for conda (optional but recommended)
conda init powershell # Windows PowerShell
# OR
conda init bash # Linux/macOS
# 3. Create a fresh conda environment
conda create -n dare3d python=3.10
conda activate dare3dPyTorch wheels are CUDA-version specific. Install the correct variant before other dependencies:
# CUDA 12.1 (latest, recommended)
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# OR for CUDA 11.8
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# OR for CPU-only
python -m pip install torch torchvision torchaudio# Install remaining dependencies
pip install -r requirements.txt
# Install DARE3D in development mode
pip install -e .If you encounter issues with napari GUI (specifically Qt):
# Install PyQt via conda-forge (recommended)
conda install -c conda-forge pyqt
# OR use an isolated napari environment
conda create -n napari-env python=3.10
conda activate napari-env
conda install -c conda-forge napari pyqtFor better debugging, enable full Hydra stack traces:
# For current session only:
$Env:HYDRA_FULL_ERROR = "1"
# To persist across sessions, add to your PowerShell profile:
notepad $PROFILE
# Add the line: $Env:HYDRA_FULL_ERROR = "1"
# Save and restart PowerShellFor Linux/macOS:
HYDRA_FULL_ERROR=1 python -m dare3d.train_evaldare3d/ # Main package
├── data/ # Data loading and preprocessing
│ ├── dare_datamodule.py # PyTorch Lightning DataModule
│ ├── augmend_wrapper.py # GPU-accelerated augmentations
│ ├── gpu_augmentations.py
│ ├── augmentations/ # Augmentation pipeline definitions
│ ├── components/ # Data pipeline components
│ └── visualization/ # Data visualization utilities
│
├── models/ # Neural network architectures
│ ├── regression_module.py # Regression model (attributes)
│ ├── segmentation_module.py # Segmentation model (centers)
│ ├── tap_module.py # Multi-task model variant
│ ├── sequence_ordered_module.py
│ ├── components/ # Model subcomponents
│ └── net/ # Network backbone definitions
│
├── losses/ # Custom loss functions
│ ├── angle3d.py # 3D angle prediction loss
│ ├── decorrelation.py # Decorrelation loss
│ └── pixelwise_crossentropy.py
│
├── metrics/ # Evaluation metrics
│ ├── inference.py # Inference pipeline
│ ├── infer_measure.py # Measurement utilities
│ ├── object_level.py # Object-level metrics
│ └── (others)
│
├── loggers/ # Custom logging utilities
│ ├── segmentation_logger.py
│ └── regression_logger.py
│
├── tools/ # Utility scripts and tools
├── utils/ # Helper functions and utilities
│
├── train.py # Main training script (Hydra-based)
├── train_eval.py # Combined training & evaluation
├── eval.py # Evaluation-only script
├── predict.py # Inference script
├── demo.py # Demo data download utility
└── __init__.py
configs/ # Hydra configuration files
├── train.yaml # Training config template
├── eval.yaml # Evaluation config
├── predict.yaml # Inference config
├── data/ # Data config (segmentation, regression, etc.)
├── model/ # Model architectures config
│ ├── criterion/ # Loss functions config
│ ├── metric/ # Metrics config
│ ├── net/ # Network config
│ ├── optimizer/ # Optimizer config
│ └── scheduler/ # LR scheduler config
├── trainer/ # Trainer config (CPU, GPU, DDP, etc.)
├── logger/ # Logger config (MLflow, TensorBoard, etc.)
├── callbacks/ # PyTorch Lightning callbacks
├── debug/ # Debug modes
├── experiment/ # Experiment presets
└── hparams_search/ # Hyperparameter search configs
scripts/ # Experiment generation scripts
├── generate_exp1.py # Generate train/val/test splits
├── generate_exp2-7.py # Other experiment variants
└── generation_utils.py
notebooks/ # Jupyter notebooks
├── Run_dare3d_Prediction.ipynb # Main prediction notebook (START HERE!)
├── data_visualization.ipynb # Interactive data exploration
└── data_normalization.ipynb # Data preprocessing
tests/ # Unit and integration tests
├── test_train.py
├── test_eval.py
├── test_configs.py
├── test_datamodules.py
└── helpers/
data/ # Data storage (you'll populate this)
└── 3D/ # Your 3D image data goes here
logs/ # Training outputs (auto-generated)
├── segmentation_{dataset_name}/
│ └── runs/{date}/
│ ├── checkpoints/ # Model weights
│ ├── .hydra/ # Training config
│ └── (tensorboard logs)
└── regression_{dataset_name}/
└── runs/{date}/
├── checkpoints/
├── .hydra/
└── (tensorboard logs)
requirements.txt # Python dependencies
setup.py # Package setup configuration
pyproject.toml # Project metadata & pytest config
Makefile # Development commands
README.md # This file
README.md.backup # Original README (for reference)
DARE3D uses Hydra for configuration management. This enables:
- Composable configs: Override settings via CLI without editing files
- Experiment tracking: Configs are automatically saved with each run
- Multi-run capabilities: Launch parameter sweeps with a single command
# Change device
python dare3d/train.py trainer=gpu # GPU training
python dare3d/train.py trainer=cpu # CPU training
# Change model
python dare3d/train.py model=segmentation # Segmentation only
python dare3d/train.py model=regression # Regression only
# Override specific parameters
python dare3d/train.py data.batch_size=8 model.lr=0.001
# Use an experiment preset
python dare3d/train.py experiment=segmentationSee configs/ for all available configuration options.
Use the included demo dataset for a quick validation run:
python dare3d/train_eval.pyRequired folder structure:
your_dataset/
├── train/
│ ├── im/
│ │ ├── movie1.tif
│ │ └── movie2.tif
│ ├── label/
│ │ ├── movie1.tif
│ │ └── movie2.tif
│ └── sparse/ (optional - per-voxel weighting)
│ └── movie1.tif
├── val/
│ ├── im/
│ ├── label/
│ └── sparse/
└── test/
├── im/
├── label/
└── sparse/
Movie Dimensions: All .tif movies (both images and labels) are stored as 4D arrays with axis order (T, Z, Y, X):
| Axis | Description |
|---|---|
| T | Time (number of frames) |
| Z | Depth (number of Z-slices) |
| Y | Height (pixels) |
| X | Width (pixels) |
Label Format: Binary labeling of daughter cell pairs
- First daughter cell → odd values (1, 3, 5, ...)
- Second daughter cell → even values (2, 4, 6, ...)
- Connected component analysis extracts center pairs
Sparse Weighting (optional): 2D mask per frame indicating which voxels to use. Defaults to all-ones if omitted.
Edit data/3D/scales.json:
{
"movie1": [1.0, 1.0, 1.0],
"movie2": [0.5, 0.5, 2.8]
}Scales should be in µm/voxel for X, Y, Z respectively.
# Train both segmentation and regression
python dare3d/train_eval.py --set_folder path/to/your_dataset --epoch 50
# Train segmentation only
python dare3d/train_eval.py --set_folder path/to/your_dataset --epoch 50 --train_segmentation True
# Train regression only
python dare3d/train_eval.py --set_folder path/to/your_dataset --epoch 50 --train_regression True
# Additional parameters (see train_eval.py for all)
python dare3d/train_eval.py \
--set_folder path/to/your_dataset \
--epoch 50 \
--date 2025-05-01 \
--batch_size 4 \
--cell_radius 15Checkpoints and logs are saved to:
logs/
├── segmentation_{dataset_name}/runs/{date}/
│ ├── checkpoints/
│ │ ├── epoch_10.ckpt
│ │ ├── epoch_best.ckpt
│ │ └── last.ckpt
│ └── .hydra/config.yaml # Configuration used
└── regression_{dataset_name}/runs/{date}/
└── checkpoints/
View tensorboard logs:
tensorboard --logdir logs/The easiest way to run inference is the Jupyter notebook:
jupyter notebook Run_dare3d_Prediction.ipynbThis notebook:
- Guides you through path setup
- Downloads demo data automatically (if needed)
- Runs both segmentation and regression
- Produces visualization outputs
- Supports comparison with ground truth
For programmatic or batch processing:
python dare3d/predict.pyConfiguration is in configs/predict.yaml. Key parameters:
python dare3d/predict.py \
+model_dir=logs/segmentation_myDataset/runs/2025-05-01 \
+data.test_data.data_dir=/path/to/input/movies \
+output_dir=/path/to/outputThe script automatically loads .hydra/config.yaml from the model directory. Specify which checkpoint:
python dare3d/predict.py \
+model_dir=logs/segmentation_myDataset/runs/2025-05-01 \
+ckpt_dir=checkpoints/epoch_best.ckptMovies must be registered with their correct pixel scales (in µm/voxel):
Option 1 - JSON file (preferred):
{
"movie1.tif": [1.0, 1.0, 1.0],
"movie2.tif": [0.5, 0.5, 2.8]
}python dare3d/predict.py +scale_file=data/3D/scales.jsonOption 2 - Default scale (same for all movies):
python dare3d/predict.py +default_scale=1.0
# OR for anisotropic voxels
python dare3d/predict.py +default_scale=[1.0, 1.0, 2.8]Option 3 - Target scale (for network that was trained on specific scale):
python dare3d/predict.py +default_scale=1.0 +target_scale=1.0Run the test suite to verify your installation:
# Quick tests (excludes slow tests)
make test
# All tests (including slow ones)
make test-full
# Or using pytest directly
pytest -k "not slow"
pytestExpected test categories:
test_configs.py- Configuration loadingtest_datamodules.py- Data pipelinetest_train.py- Training mechanicstest_eval.py- Evaluation pipeline
Use the provided scripts to organize your raw data:
# 1. Split movies along X axis (recommended preprocessing)
python scripts/generate_split_movies.py --data_dir data/3D
# 2. Generate experiment-specific train/val/test splits
python scripts/generate_exp1.py --data_dir data/3D
# exp2, exp3, ... exp7 also availableTo exclude specific regions from training (e.g., damaged areas):
python dare3d/tools/generate_sparse_weights.py \
--annotated_label path/to/label.tifmake help # Show all available commands
make test # Run quick tests
make test-full # Run all tests
make format # Run pre-commit hooks (code formatting)
make clean # Remove build artifacts and caches
make clean-logs # Remove all training logs
make sync # Sync with upstream main branchVisualize data:
jupyter notebook notebooks/data_visualization.ipynbNormalize data:
jupyter notebook notebooks/data_normalization.ipynbCheck imports and dependencies:
pip check # Verify environment consistency
python -c "from dare3d import *; print('Package imports OK')"This work was granted access to the HPC resources of IDRIS under the allocation AD010314339 made by GENCI.
Authors: Romain Karpinski, Marc Karnat, Alice Gros, Qazi Saaheelur Rahaman, Jules Vanaret, Mehdi Saadaoui, Sham Tlili, and Jean-Francois Rupprecht
- Reduce batch size:
--batch_size 2 - Use CPU training:
trainer=cpu - Use gradient accumulation:
trainer.accumulate_grad_batches=2
conda install -c conda-forge pyqtpip install -e . # Reinstall in editable mode$Env:HYDRA_FULL_ERROR = "1" # PowerShell - show full tracebackThe demo folder downloads automatically from Zenodo on first run. If this fails:
- Check internet connection
- Verify Zenodo is accessible
- Manual download: DARE3d_data.zip
- Hydra Documentation: https://hydra.cc/
- PyTorch Lightning: https://www.pytorchlightning.ai/
- MONAI: https://monai.io/ (medical imaging toolkit)
Questions? Check the demo notebook or open an issue on the repository.