Skip to content

copick inference easymode

easymode

Segment tomograms using easymode pretrained models.

Plugin command — copick-easymode

This command is provided by the copick-easymode plugin, not copick core. Install it to make this command available:

pip install git+https://github.com/copick/copick-easymode.git
pip install --no-deps git+https://github.com/mgflast/easymode.git

See the plugin system guide for details.

Usage

copick inference easymode [OPTIONS]

Description

Segment copick tomograms using easymode pretrained models.

This command runs inference using easymode's pretrained segmentation models on tomograms stored in a copick project and saves the results as copick segmentations. Each requested feature is written back as its own single-label segmentation at the input tomogram's voxel size; with --add-objects (on by default) each feature is also registered as a pickable object in the config.

One worker process runs per GPU, and the runs are split among them. Each worker reads and preprocesses the next tomogram and writes the previous segmentation while its GPU segments the current one.

Available models include: ribosome, membrane, microtubule, actin, cytoplasm, mitochondrion, nucleus, nuclear_envelope, npc, and more.

URI Format

Tomograms:     type@voxel_spacing
Segmentations: name:user_id/session_id@voxel_spacing

Options

Option Type Default Description
-c, --config path — Path to the configuration file.
--model, -m text required Comma-separated list of models/features to run (e.g., 'ribosome,membrane').
--tomogram, -t text required Tomogram URI in format 'type@voxel_size' (e.g., 'wbp@10.0').
--run, -r text "" Run name or comma-separated list of runs. Empty = all runs.
--threshold float 0.5 Probability threshold for binarizing segmentation (0.0-1.0).
--batch-size integer 1 Batch size for inference.
--tta integer 4 Test-time augmentation level (1-16; an .scnm model uses at most 8). Higher = better but slower.
--gpus text — Comma-separated GPUs to use, one worker process each: positions in CUDA_VISIBLE_DEVICES when it is set (else nvidia-smi indices), or device UUIDs. A GPU outside the allocation is refused. Default: every GPU this process may use.
--cpu boolean flag False Run on the CPU, with one worker and no GPU.
--max-workers integer range — Use at most this many GPUs (worker processes). Default: one per GPU.
--threads integer range — CPU threads to divide among the workers. Default: the CPUs this process may run on, at most SLURM_CPUS_ON_NODE.
--model-dir directory — easymode model directory (the one holding registry.json and models/). Default: easymode's MODEL_DIRECTORY setting. Applies to this command only; easymode's settings file is not changed.
--offline boolean flag False Never contact the model registry: use only the weights already in the model directory, and write nothing there.
--report file — Write a JSON report: settings, resolved models, devices, each worker's runs and outcome, errors and timings.
--session-id text 1 Session ID for the annotation.
--user-id text copick User ID for the annotation.
--overwrite / --no-overwrite boolean flag False Overwrite existing segmentations.
--add-objects / --no-add-objects boolean flag True Add object definitions to config if missing.
--debug / --no-debug boolean flag False Enable debug logging.

Examples

# Segment ribosomes in all runs, on every GPU of the allocation
copick inference easymode -c config.json -m ribosome -t wbp@10.0

# Segment multiple features
copick inference easymode -c config.json -m ribosome,membrane -t wbp@10.0

# Segment specific runs on GPUs 0 and 1 (one worker process each)
copick inference easymode -c config.json -m membrane -t wbp@10.0 --run run001,run002 --gpus 0,1

# High quality inference with TTA
copick inference easymode -c config.json -m ribosome -t wbp@10.0 --tta 16 --batch-size 2

# Skip adding object definitions to config
copick inference easymode -c config.json -m ribosome -t wbp@10.0 --no-add-objects

# A shared model directory, no downloads, and a JSON report
copick inference easymode -c config.json -m actin -t wbp@10.0 --model-dir /shared/easymode --offline --report easymode.json

See also

Notes

A CUDA GPU is strongly recommended; the weights download automatically on first use. The exit status is non-zero when a model is missing, a run fails or a worker dies.

Acknowledgements

This command uses pretrained models from easymode by Mart G.F. Last. Docs: https://mgflast.github.io/easymode Repo: https://github.com/mgflast/easymode If you use these models in your research, please cite the easymode authors.

Tutorial

See Segmenting cellular features with easymode for an end-to-end walkthrough — creating a project from a CZ cryoET Data Portal dataset and running copick inference easymode to segment membranes, ribosomes and more.

Please cite easymode

copick inference easymode only wraps the tool — the pretrained models and method are the work of the easymode authors. If easymode contributes to your research, please cite the original work in addition to copick:

So-Last, M. G. F., Burt, A., Hale, T., & Allegretti, M. (2026). Easymode: general pretrained networks for cellular cryo-ET enable flexible approaches to subtomogram averaging. bioRxiv.