copick convert picks2sphere

utils

Convert picks to sphere 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 picks2sphere input — Input

copick convert picks2sphere output — Output

Convert picks to sphere meshes.

Usage

copick convert picks2sphere [OPTIONS]

Description

Fits a sphere to the pick points using a least-squares fit and emits a triangulated icosphere mesh at the fitted center and radius. The --subdivisions option controls the icosphere tessellation, trading smoothness against face count.

When --use-clustering is set, the picks are grouped first; with --all-clusters one sphere is fit per cluster, otherwise only the largest cluster is used. Overlapping spheres can be merged with --deduplicate-spheres (centers closer than --min-sphere-distance, defaulting to half the average radius, are treated as duplicates and volume-averaged). By default a single combined mesh is written per run; --individual-meshes instead writes one mesh per sphere using the {instance_id} placeholder in the output session id.

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 sphere subdivisions for mesh resolution.
`--deduplicate-spheres / --no-deduplicate-spheres`	boolean flag	`True`	Merge overlapping spheres to avoid duplicates.
`--min-sphere-distance`	float	—	Minimum distance between sphere centers for deduplication (default: 0.5 * average radius).
`--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 a single pick set to one sphere mesh
copick convert picks2sphere -i "ribosome:user1/manual-001" -o "ribosome:picks2sphere/sphere-001"

# Cluster the picks and write one sphere mesh per instance
copick convert picks2sphere --use-clustering --all-clusters --individual-meshes \
    -i "ribosome:user1/manual-001" -o "ribosome:picks2sphere/sphere-{instance_id}"

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