A PyQt6-based interactive segmentation tool with U-Net training, prediction, and mask editing capabilities. MOSS provides an intuitive interface for training deep learning models on microscopy images through direct annotation and real-time feedback.
MOSS-lite is the first version of MOSS and my personal copy. All future work and updates will be reflected in https://github.com/StructuralNeurobiologyLab/MOSS .
- Interactive Training: Paint masks on images and train U-Net models in real-time
- Multiple Architectures: Standard UNet plus a family of "Deep Dice v2" 2D and 2.5D models (see Architectures)
- Large Volumes (OME-Zarr / Pyramids): Load multiscale
.zarrstores with automatic resolution selection by zoom level, or generate pyramids from TIFF stacks (see Loading Data) - Selectable Crop Size: Train at 128, 256, or 512 px tiles
- Live Predictions: See model predictions as you work
- Refiner Mode: Train a refinement model that learns from your edits
- Subprojects: Organize multiple labels/targets within a single project
- Reslice & Voting: Generate orthogonal/diagonal views and combine predictions across them for consensus segmentation
- Mask Editing Tools: Brush, eraser, fill, and component-based editing
- Multi-User Training: Collaborate with others anywhere (requires relay server)
MOSS ships several model architectures, selectable from the training UI:
| Architecture | Notes |
|---|---|
| UNet (Standard) | Baseline 2D U-Net. |
| UNet Deep Dice v2 (Stable) | Recommended default. Combined BCE+Dice loss, gradient clipping, robust resume. |
| UNet Deep Dice 2.5D v2 (Stable) | 2.5D variant taking 3 z-slices (z−3, z, z+3) as input channels. |
| UNet Deep 2.5D v2 (11-slice) | Wider z-context: 11 channels spanning z−10…z+10 (every 2nd slice). |
| UNet Deep 2.5D v2 (11-slice + Z-coord) | As above, plus a z-coordinate channel encoding the slice's normalized depth — useful when appearance varies systematically with depth. |
The "v2" models are recommended for new projects. (A few additional experimental architectures exist in the codebase but are hidden from the UI.)
MOSS reads both image stacks and chunked volumes:
- TIFF stacks (
.tif,.tiff), plus PNG and JPEG. Single-channel grayscale is recommended. - OME-Zarr / multiscale pyramids (
.zarrdirectories, zarr v2 and v3). MOSS reads themultiscalesmetadata and automatically renders from the appropriate pyramid level for the current zoom, so very large volumes stay responsive.
For large datasets, convert a TIFF stack to a pyramidal OME-Zarr from the home screen via Generate Pyramids. This writes a multi-level (4-level) OME-Zarr store; subsequent loads use the downsampled levels when zoomed out. Volumes without a pyramid structure still load via a zarr fallback path.
# Create environment from file
conda env create -f environment.yml
# Activate environment
conda activate moss
# Install the package
pip install -e .python -m venv moss-env
source moss-env/bin/activate
pip install torch torchvision
pip install -e .python -m venv moss-env
source moss-env/bin/activate
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install -e .python -m venv moss-env
source moss-env/bin/activate # On Windows: moss-env\Scripts\activate
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install -e .# Install dependencies
pip install -r requirements.txt
# Install the package
pip install -e .On shared HPC clusters, pip-installed PyQt6 often fails because its pre-compiled binaries
expect newer system libraries than the cluster provides (e.g. libharfbuzz, FreeType).
The fix is to replace the pip PyQt6 with the conda-forge build.
# 1. Create conda environment
conda env create -f environment.yml
conda activate moss
# 2. Replace pip PyQt6 with conda-forge version
pip uninstall -y PyQt6 PyQt6-Qt6 PyQt6-sip
conda install -c conda-forge pyqt6
# 3. Install the package
pip install -e .
# 4. Launch (requires interactive session with X11 forwarding)
srun --partition=cpu --pty --x11 --cpus-per-task=4 bash
conda activate moss
mossFor heavy training on cluster data, use LAN network mode: host a session on the cluster and connect from your laptop via "Advanced (LAN)" in the multi-user dialog. This avoids X11 lag — you annotate locally and the cluster trains on received crops.
After installation, run:
mossOr run as a Python module:
python -m segmentation_suite| Key | Action |
|---|---|
| A / Left Arrow | Previous slice |
| D / Right Arrow | Next slice |
| B | Brush tool |
| E | Eraser tool |
| H | Hand (pan) tool |
| F + Click | Fill tool |
| S | Toggle predictions |
| Space | Accept hovered prediction component |
| Shift + Space | Accept ALL predictions (replace mask) |
| Tab | Capture crop for training |
| Ctrl + S | Save project |
| Ctrl + Z | Undo |
| +/- | Zoom in/out |
| [ / ] | Decrease / increase brush size |
| Shift + Scroll | Adjust brush size |
When you create a project, MOSS lays out roughly the following:
project_folder/
├── project.json # Project settings
├── masks/ # Saved masks (mask_00000.tif, etc.)
├── train_images/ # Training image crops (256 px default)
├── train_masks/ # Training mask crops (256 px default)
├── train_images_128/ 512/ # Crop-size-specific folders (when 128/512 selected)
├── train_masks_128/ 512/ # (mirrors train_images_*)
├── train_images_25d/ ... # 2.5D / 11-slice variants, per crop size
├── checkpoint*.pth # Model checkpoints (per architecture)
├── refiner_images/ # Refiner training data
├── refiner_masks_before/ # Mask state before edits
├── refiner_masks_after/ # Mask state after edits
└── refiner_checkpoint.pth # Refiner model checkpoint
Notes:
- The project config file is named
project.json. - Training data is organized per crop size: the default 256 px uses
train_images/train_masks, while 128 and 512 px get suffixed folders (train_images_128,train_images_512, …). 2.5D architectures use parallel_25d/_dwarf25dfolders, and 3D usestrain_images_3d/train_masks_3d. - Projects that use subprojects nest the per-label data under
subprojects/<name>/, each with its ownproject.json,masks/, and training folders.
- Python 3.9+
- PyQt6 6.4+
- PyTorch 2.0+
- CUDA (optional, for GPU acceleration)
- macOS MPS (optional, for Apple Silicon acceleration)
If you get errors about PyQt6, try:
pip install PyQt6 --force-reinstallFor Apple Silicon Macs, ensure you have a recent PyTorch version:
pip install --upgrade torch torchvisionReduce batch size in the training settings or use a smaller tile size.
Supported formats: TIFF (.tif, .tiff), PNG, JPEG, and OME-Zarr (.zarr) stores. For best results, use single-channel grayscale images. See Loading Data for large-volume / pyramid handling.
Pip-installed PyQt6 bundles binaries compiled against newer system libraries than most clusters have. Replace it with the conda-forge build:
pip uninstall -y PyQt6 PyQt6-Qt6 PyQt6-sip
conda install -c conda-forge pyqt6Nelson Medina - Creator and primary developer GitHub: @nelsmedina
If you use MOSS in your research, please cite:
Medina, N. (2025). MOSS: Microscopy Oriented Segmentation with Supervision [Computer software].
https://github.com/nelsmedina/MOSS
MIT License