copick convert picks2ellipsoid

utils

Convert picks to ellipsoid meshes.

Plugin command — copick-utils

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

pip install copick-utils

See the plugin system guide for details.

copick convert picks2ellipsoid input — Input

copick convert picks2ellipsoid output — Output

Convert picks to ellipsoid meshes.

Usage

copick convert picks2ellipsoid [OPTIONS]

Description

Build an ellipsoid mesh for each pick (or for each cluster of picks), tessellating the surface at the requested subdivision level. Picks can optionally be grouped first with a clustering method (DBSCAN or k-means) so that one ellipsoid is fit per cluster, and overlapping ellipsoids can be deduplicated by their center distance.

The result is written either as a single combined mesh per pick set or, with --individual-meshes, as one mesh per instance (enabling the {instance_id} placeholder in the output URI).

URI Format

Picks: object_name:user_id/session_id
Meshes: object_name:user_id/session_id

Options

Option	Type	Default	Description
`-c, --config`	path	—	Path to the configuration file.
`--debug / --no-debug`	boolean flag	`False`	Enable debug logging.

Input Options

Option	Type	Default	Description
`--run-names, -r`	text · multiple	—	Specific run names to process (default: all runs).
`--input, -i`	COPICK_URI	required	Input picks URI (format: object_name:user_id/session_id). Supports glob patterns.

Tool Options

Option	Type	Default	Description
`--subdivisions`	integer	`2`	Number of ellipsoid subdivisions for mesh resolution.
`--deduplicate-ellipsoids / --no-deduplicate-ellipsoids`	boolean flag	`True`	Merge overlapping ellipsoids to avoid duplicates.
`--min-ellipsoid-distance`	float	—	Minimum distance between ellipsoid centers for deduplication (default: 0.5 * average major axis).
`--use-clustering, -cl / --no-use-clustering`	boolean flag	`False`	Cluster points before mesh creation.
`--clustering-method`	choice (dbscan \| kmeans)	`dbscan`	Clustering method.
`--clustering-eps`	float	`1.0`	DBSCAN eps parameter - maximum distance between points in a cluster (in angstroms).
`--clustering-min-samples`	integer	`3`	DBSCAN min_samples parameter.
`--clustering-n-clusters`	integer	`1`	K-means n_clusters parameter.
`--all-clusters, -mm / --largest-cluster-only`	boolean flag	`True`	Use all clusters (True) or only the largest cluster (False).
`--workers, -w`	integer	`8`	Number of worker processes.

Output Options

Option	Type	Default	Description
`--output, -o`	COPICK_URI	required	Output mesh URI. Supports smart defaults (e.g., "membrane", "membrane/my-session", or "/my-session"). Full format: object_name:user_id/session_id.
`--individual-meshes, -im / --no-individual-meshes`	boolean flag	`False`	Create individual meshes for each instance (enables {instance_id} placeholder).

Examples

# Convert single pick set to single ellipsoid mesh
copick convert picks2ellipsoid -i "ribosome:user1/manual-001" -o "ribosome:picks2ellipsoid/ellipsoid-001"

# Create individual ellipsoid meshes
copick convert picks2ellipsoid -i "ribosome:user1/manual-001" \
    -o "ribosome:picks2ellipsoid/ellipsoid-{instance_id}" --individual-meshes

# Convert all manual picks using pattern matching
copick convert picks2ellipsoid -i "ribosome:user1/manual-.*" \
    -o "ribosome:picks2ellipsoid/ellipsoid-{input_session_id}"