Converters

The copick_utils.converters module converts between copick data types — picks, segmentations, and meshes. Each converter reads copick entities (or raw arrays) and writes a new entity back into the run.

These are the functional building blocks behind the copick convert ... CLI commands; import and call them directly when scripting.

Picks → Segmentation, Mesh, and geometry

copick_utils.converters.segmentation_from_picks.segmentation_from_picks

segmentation_from_picks(picks: CopickPicks, run: CopickRun, object_name: str, session_id: str, user_id: str, radius: float, voxel_spacing: float, tomo_type: str = 'wbp') -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Convert CopickPicks to a segmentation by painting spheres.

Parameters:

picks (CopickPicks) –

CopickPicks object to convert
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output segmentation
session_id (str) –

Session ID for the output segmentation
user_id (str) –

User ID for the output segmentation
radius (float) –

Radius of the spheres in physical units
voxel_spacing (float) –

Voxel spacing for the segmentation
tomo_type (str, default: 'wbp' ) –

Type of tomogram to use as reference

Returns:

Optional[Tuple[CopickSegmentation, Dict[str, int]]] –

Tuple of (CopickSegmentation object, stats dict) or None if creation failed.
Optional[Tuple[CopickSegmentation, Dict[str, int]]] –

Stats dict contains 'points_converted' and 'voxels_created'.

copick_utils.converters.mesh_from_picks.mesh_from_picks

mesh_from_picks(points: ndarray, run: CopickRun, object_name: str, session_id: str, user_id: str, mesh_type: str = 'convex_hull', alpha: Optional[float] = None, use_clustering: bool = False, clustering_method: str = 'dbscan', clustering_params: Optional[Dict[str, Any]] = None, all_clusters: bool = False, individual_meshes: bool = False, session_id_template: Optional[str] = None) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Create mesh(es) from pick points.

Parameters:

points (ndarray) –

Nx3 array of pick positions.
run (CopickRun) –

Copick run object.
object_name (str) –

Name of the mesh object.
session_id (str) –

Session ID for the mesh.
user_id (str) –

User ID for the mesh.
mesh_type (str, default: 'convex_hull' ) –

Type of mesh to create ('convex_hull', 'alpha_shape').
alpha (Optional[float], default: None ) –

Alpha parameter for alpha shapes (required if mesh_type='alpha_shape').
use_clustering (bool, default: False ) –

Whether to cluster points first.
clustering_method (str, default: 'dbscan' ) –

Clustering method ('dbscan', 'kmeans').
clustering_params (Optional[Dict[str, Any]], default: None ) –

Parameters for clustering. e.g. - {'eps': 5.0, 'min_samples': 3} for DBSCAN - {'n_clusters': 3} for KMeans
all_clusters (bool, default: False ) –

If True, use all clusters; if False, use only the largest cluster.
individual_meshes (bool, default: False ) –

If True, create separate mesh objects for each mesh.
session_id_template (Optional[str], default: None ) –

Template for individual mesh session IDs.

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh object, stats dict) or None if creation failed.
Optional[Tuple[CopickMesh, Dict[str, int]]] –

Stats dict contains 'vertices_created' and 'faces_created' totals.

copick_utils.converters.sphere_from_picks.sphere_from_picks

sphere_from_picks(points: ndarray, run: CopickRun, object_name: str, session_id: str, user_id: str, use_clustering: bool = False, clustering_method: str = 'dbscan', clustering_params: Optional[Dict[str, Any]] = None, subdivisions: int = 2, all_clusters: bool = False, deduplicate_spheres_flag: bool = True, min_sphere_distance: Optional[float] = None, individual_meshes: bool = False, session_id_template: Optional[str] = None) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Create sphere mesh(es) from pick points.

Parameters:

points (ndarray) –

Nx3 array of pick positions.
run (CopickRun) –

Copick run object.
object_name (str) –

Name of the mesh object.
session_id (str) –

Session ID for the mesh.
user_id (str) –

User ID for the mesh.
use_clustering (bool, default: False ) –

Whether to cluster points first.
clustering_method (str, default: 'dbscan' ) –

Clustering method ('dbscan', 'kmeans').
clustering_params (Optional[Dict[str, Any]], default: None ) –

Parameters for clustering. e.g. - {'eps': 5.0, 'min_samples': 3} for DBSCAN - {'n_clusters': 3} for KMeans
subdivisions (int, default: 2 ) –

Number of subdivisions for sphere resolution.
all_clusters (bool, default: False ) –

If True and clustering is used, use all clusters. If False, use only largest cluster.
deduplicate_spheres_flag (bool, default: True ) –

Whether to merge overlapping spheres.
min_sphere_distance (Optional[float], default: None ) –

Minimum distance between sphere centers for deduplication.
individual_meshes (bool, default: False ) –

If True, create separate mesh objects for each sphere.
session_id_template (Optional[str], default: None ) –

Template for individual mesh session IDs.

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh object, stats dict) or None if creation failed.
Optional[Tuple[CopickMesh, Dict[str, int]]] –

Stats dict contains 'vertices_created' and 'faces_created' totals.

copick_utils.converters.ellipsoid_from_picks.ellipsoid_from_picks

ellipsoid_from_picks(points: ndarray, run: CopickRun, object_name: str, session_id: str, user_id: str, use_clustering: bool = False, clustering_method: str = 'dbscan', clustering_params: Optional[Dict[str, Any]] = None, subdivisions: int = 2, all_clusters: bool = True, deduplicate_ellipsoids_flag: bool = True, min_ellipsoid_distance: Optional[float] = None, individual_meshes: bool = False, session_id_template: Optional[str] = None) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Create ellipsoid mesh(es) from pick points.

Parameters:

points (ndarray) –

Nx3 array of pick positions.
run (CopickRun) –

Copick run object.
object_name (str) –

Name of the mesh object.
session_id (str) –

Session ID for the mesh.
user_id (str) –

User ID for the mesh.
use_clustering (bool, default: False ) –

Whether to cluster points first.
clustering_method (str, default: 'dbscan' ) –

Clustering method ('dbscan', 'kmeans').
clustering_params (Optional[Dict[str, Any]], default: None ) –

Parameters for clustering. e.g. - {'eps': 5.0, 'min_samples': 3} for DBSCAN - {'n_clusters': 3} for KMeans
subdivisions (int, default: 2 ) –

Number of subdivisions for ellipsoid resolution.
all_clusters (bool, default: True ) –

If True, use all clusters; if False, use only the largest cluster.
deduplicate_ellipsoids_flag (bool, default: True ) –

Whether to merge overlapping ellipsoids.
min_ellipsoid_distance (Optional[float], default: None ) –

Minimum distance between ellipsoid centers for deduplication.
individual_meshes (bool, default: False ) –

If True, create separate mesh objects for each ellipsoid.
session_id_template (Optional[str], default: None ) –

Template for individual mesh session IDs.

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh object, stats dict) or None if creation failed.
Optional[Tuple[CopickMesh, Dict[str, int]]] –

Stats dict contains 'vertices_created' and 'faces_created' totals.

copick_utils.converters.plane_from_picks.plane_from_picks

plane_from_picks(points: ndarray, run: CopickRun, object_name: str, session_id: str, user_id: str, use_clustering: bool = False, clustering_method: str = 'dbscan', clustering_params: Optional[Dict[str, Any]] = None, padding: float = 1.2, all_clusters: bool = True, individual_meshes: bool = False, session_id_template: Optional[str] = None) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Create plane mesh(es) from pick points.

Parameters:

points (ndarray) –

Nx3 array of pick positions.
run (CopickRun) –

Copick run object.
object_name (str) –

Name of the mesh object.
session_id (str) –

Session ID for the mesh.
user_id (str) –

User ID for the mesh.
use_clustering (bool, default: False ) –

Whether to cluster points first.
clustering_method (str, default: 'dbscan' ) –

Clustering method ('dbscan', 'kmeans').
clustering_params (Optional[Dict[str, Any]], default: None ) –

Parameters for clustering. e.g. - {'eps': 5.0, 'min_samples': 3} for DBSCAN - {'n_clusters': 3} for KMeans
padding (float, default: 1.2 ) –

Padding factor for plane size (1.0 = exact fit, >1.0 = larger plane).
all_clusters (bool, default: True ) –

If True, use all clusters; if False, use only the largest cluster.
individual_meshes (bool, default: False ) –

If True, create separate mesh objects for each plane.
session_id_template (Optional[str], default: None ) –

Template for individual mesh session IDs.

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh object, stats dict) or None if creation failed.
Optional[Tuple[CopickMesh, Dict[str, int]]] –

Stats dict contains 'vertices_created' and 'faces_created' totals.

copick_utils.converters.surface_from_picks.surface_from_picks

surface_from_picks(points: ndarray, run: CopickRun, object_name: str, session_id: str, user_id: str, surface_method: str = 'delaunay', grid_resolution: int = 50, use_clustering: bool = False, clustering_method: str = 'dbscan', clustering_params: Optional[Dict[str, Any]] = None, all_clusters: bool = True, individual_meshes: bool = False, session_id_template: Optional[str] = None) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Create surface mesh(es) from pick points.

Parameters:

points (ndarray) –

Nx3 array of pick positions.
run (CopickRun) –

Copick run object.
object_name (str) –

Name of the mesh object.
session_id (str) –

Session ID for the mesh.
user_id (str) –

User ID for the mesh.
surface_method (str, default: 'delaunay' ) –

Surface fitting method ('delaunay', 'rbf', 'grid').
grid_resolution (int, default: 50 ) –

Resolution for grid-based methods.
use_clustering (bool, default: False ) –

Whether to cluster points first.
clustering_method (str, default: 'dbscan' ) –

Clustering method ('dbscan', 'kmeans').
clustering_params (Optional[Dict[str, Any]], default: None ) –

Parameters for clustering. e.g. - {'eps': 5.0, 'min_samples': 3} for DBSCAN - {'n_clusters': 3} for KMeans
all_clusters (bool, default: True ) –

If True, use all clusters; if False, use only the largest cluster.
individual_meshes (bool, default: False ) –

If True, create separate mesh objects for each surface.
session_id_template (Optional[str], default: None ) –

Template for individual mesh session IDs.

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh object, stats dict) or None if creation failed.
Optional[Tuple[CopickMesh, Dict[str, int]]] –

Stats dict contains 'vertices_created' and 'faces_created' totals.

Segmentation ↔ Mesh ↔ Picks

copick_utils.converters.mesh_from_segmentation.mesh_from_segmentation

mesh_from_segmentation(segmentation: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, level: float = 0.5, step_size: int = 1, voxel_spacing: Optional[float] = None, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Convert a CopickSegmentation to a mesh.

Parameters:

segmentation (CopickSegmentation) –

CopickSegmentation object to convert
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output mesh object
session_id (str) –

Session ID for the output mesh
user_id (str) –

User ID for the output mesh
level (float, default: 0.5 ) –

Isosurface level for marching cubes
step_size (int, default: 1 ) –

Step size for marching cubes

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh object, stats dict) or None if creation failed.
Optional[Tuple[CopickMesh, Dict[str, int]]] –

Stats dict contains 'vertices_created' and 'faces_created'.

copick_utils.converters.segmentation_from_mesh.segmentation_from_mesh

segmentation_from_mesh(mesh: CopickMesh, run: CopickRun, object_name: str, session_id: str, user_id: str, voxel_spacing: float, tomo_type: str = 'wbp', is_multilabel: bool = False, mode: str = 'watertight', boundary_sampling_density: float = 1.0, invert: bool = False) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Convert a CopickMesh to a segmentation volume.

Parameters:

mesh (CopickMesh) –

CopickMesh object to convert
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output segmentation
session_id (str) –

Session ID for the output segmentation
user_id (str) –

User ID for the output segmentation
voxel_spacing (float) –

Voxel spacing for the segmentation
tomo_type (str, default: 'wbp' ) –

Type of tomogram to use for reference dimensions
is_multilabel (bool, default: False ) –

Whether the segmentation is multilabel
mode (str, default: 'watertight' ) –

Voxelization mode ('watertight' or 'boundary')
boundary_sampling_density (float, default: 1.0 ) –

Surface sampling density for boundary mode (samples per voxel edge length)
invert (bool, default: False ) –

Whether to invert the volume (fill outside instead of inside)

Returns:

Optional[Tuple[CopickSegmentation, Dict[str, int]]] –

Tuple of (CopickSegmentation object, stats dict) or None if creation failed.
Optional[Tuple[CopickSegmentation, Dict[str, int]]] –

Stats dict contains 'voxels_created'.

copick_utils.converters.picks_from_segmentation.picks_from_segmentation

picks_from_segmentation(segmentation: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, segmentation_idx: int, maxima_filter_size: int = 9, min_particle_size: int = 1000, max_particle_size: int = 50000, voxel_spacing: Optional[float] = None, **kwargs) -> Optional[Tuple[CopickPicks, Dict[str, int]]]

Convert a CopickSegmentation to picks by extracting centroids.

Parameters:

segmentation (CopickSegmentation) –

CopickSegmentation object to convert
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output pick object
session_id (str) –

Session ID for the output picks
user_id (str) –

User ID for the output picks
segmentation_idx (int) –

The specific label from the segmentation to process
maxima_filter_size (int, default: 9 ) –

Size of the maximum detection filter
min_particle_size (int, default: 1000 ) –

Minimum size threshold for particles
max_particle_size (int, default: 50000 ) –

Maximum size threshold for particles

Returns:

Optional[Tuple[CopickPicks, Dict[str, int]]] –

Tuple of (CopickPicks object, stats dict) or None if creation failed.
Optional[Tuple[CopickPicks, Dict[str, int]]] –

Stats dict contains 'points_created'.

copick_utils.converters.picks_from_mesh.picks_from_mesh

picks_from_mesh(mesh: Trimesh, sampling_type: str, n_points: int, run: CopickRun, object_name: str, session_id: str, user_id: str, voxel_spacing: float, tomo_type: str = 'wbp', min_dist: Optional[float] = None, edge_dist: float = 32.0, include_normals: bool = False, random_orientations: bool = False, seed: Optional[int] = None) -> Optional[CopickPicks]

Sample points from a mesh using different strategies.

Parameters:

mesh (Trimesh) –

Trimesh object to sample from
sampling_type (str) –

Type of sampling ('inside', 'surface', 'outside', 'vertices')
n_points (int) –

Number of points to sample (ignored for 'vertices')
run (CopickRun) –

Copick run object
object_name (str) –

Name of the object for the picks
session_id (str) –

Session ID for the picks
user_id (str) –

User ID for the picks
voxel_spacing (float) –

Voxel spacing for coordinate scaling
tomo_type (str, default: 'wbp' ) –

Tomogram type for getting volume dimensions
min_dist (Optional[float], default: None ) –

Minimum distance between points (if None, uses voxel_spacing)
edge_dist (float, default: 32.0 ) –

Distance from volume edges in voxels
include_normals (bool, default: False ) –

Include surface normals as orientations (surface sampling only)
random_orientations (bool, default: False ) –

Generate random orientations for points
seed (Optional[int], default: None ) –

Random seed for reproducible results

Returns:

Optional[CopickPicks] –

CopickPicks object or None if sampling failed

copick_utils.converters.caps_from_mesh.caps_from_mesh

caps_from_mesh(mesh: CopickMesh, run: CopickRun, object_name: str, session_id: str, user_id: str, axis: str = 'z', angle_threshold: float = 45.0, which: str = 'both', auto_axis: bool = False, voxel_spacing: Optional[float] = None, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Converter: extract slab caps from a CopickMesh and store the result as a new mesh.

Parameters:

mesh (CopickMesh) –

CopickMesh to extract caps from.
run (CopickRun) –

Copick run object.
object_name (str) –

Name for the output mesh object.
session_id (str) –

Session ID for the output mesh.
user_id (str) –

User ID for the output mesh.
axis (str, default: 'z' ) –

Slab-normal axis ('x', 'y', 'z').
angle_threshold (float, default: 45.0 ) –

Max angle (degrees) from the axis for a face to count as a cap.
which (str, default: 'both' ) –

Which caps to keep ('both', 'top', 'bottom').
auto_axis (bool, default: False ) –

Infer the slab normal from the mesh's thinnest OBB extent.
voxel_spacing (Optional[float], default: None ) –

Unused (absorbs the value the lazy task dict carries for mesh inputs).
**kwargs –

Additional arguments (ignored).

Returns:

Optional[Tuple[CopickMesh, Dict[str, int]]] –

Tuple of (CopickMesh, stats dict) or None if extraction failed. Stats contain
Optional[Tuple[CopickMesh, Dict[str, int]]] –

'vertices_created' and 'faces_created'.

Usage Examples

Paint picks into a segmentation volume

import numpy as np

import copick
from copick_utils.converters.segmentation_from_picks import segmentation_from_picks

root = copick.from_file("config.json")
run = root.get_run("TS_001")

# Paint a sphere at every pick into a new multiscale segmentation.
seg, stats = segmentation_from_picks(
    picks=run.get_picks(object_name="ribosome")[0],
    run=run,
    object_name="ribosome",
    session_id="painted-001",
    user_id="copick-utils",
    radius=80.0,            # angstroms
    voxel_spacing=10.0,
    tomo_type="wbp",
)
print(stats)

Extract the caps of a slab mesh

import copick
from copick_utils.converters.caps_from_mesh import caps_from_mesh

root = copick.from_file("config.json")
run = root.get_run("TS_001")

# Keep only the top/bottom faces of a closed slab box, dropping the side walls.
caps, stats = caps_from_mesh(
    mesh=run.get_meshes(object_name="valid-sample")[0],
    run=run,
    object_name="valid-sample-caps",
    session_id="0",
    user_id="copick-utils",
    which="both",
)