Logical Operations

The copick_utils.logical module performs boolean and distance-based operations on meshes, segmentations, and picks. These are the functional building blocks behind the copick logical ... CLI commands.

Mesh boolean operations

copick_utils.logical.mesh_operations.mesh_union

mesh_union(mesh1: CopickMesh, mesh2: CopickMesh, run: CopickRun, object_name: str, session_id: str, user_id: str, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Union of two meshes.

copick_utils.logical.mesh_operations.mesh_difference

mesh_difference(mesh1: CopickMesh, mesh2: CopickMesh, run: CopickRun, object_name: str, session_id: str, user_id: str, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Difference of two meshes (mesh1 - mesh2).

copick_utils.logical.mesh_operations.mesh_intersection

mesh_intersection(mesh1: CopickMesh, mesh2: CopickMesh, run: CopickRun, object_name: str, session_id: str, user_id: str, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Intersection of two meshes.

copick_utils.logical.mesh_operations.mesh_exclusion

mesh_exclusion(mesh1: CopickMesh, mesh2: CopickMesh, run: CopickRun, object_name: str, session_id: str, user_id: str, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Exclusive or (XOR) of two meshes.

Segmentation boolean operations

copick_utils.logical.segmentation_operations.segmentation_union

segmentation_union(segmentation1: CopickSegmentation, segmentation2: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, voxel_spacing: float, is_multilabel: bool = False, **kwargs) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Union of two segmentations.

copick_utils.logical.segmentation_operations.segmentation_difference

segmentation_difference(segmentation1: CopickSegmentation, segmentation2: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, voxel_spacing: float, is_multilabel: bool = False, **kwargs) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Difference of two segmentations (seg1 - seg2).

copick_utils.logical.segmentation_operations.segmentation_intersection

segmentation_intersection(segmentation1: CopickSegmentation, segmentation2: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, voxel_spacing: float, is_multilabel: bool = False, **kwargs) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Intersection of two segmentations.

copick_utils.logical.segmentation_operations.segmentation_exclusion

segmentation_exclusion(segmentation1: CopickSegmentation, segmentation2: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, voxel_spacing: float, is_multilabel: bool = False, **kwargs) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Exclusive or (XOR) of two segmentations.

Distance-based limiting

copick_utils.logical.distance_operations.limit_mesh_by_distance

limit_mesh_by_distance(mesh: CopickMesh, run: CopickRun, object_name: str, session_id: str, user_id: str, reference_mesh: Optional[CopickMesh] = None, reference_segmentation: Optional[CopickSegmentation] = None, reference_tomogram_info: Optional[Tuple[str, float]] = None, max_distance: float = 100.0, mesh_voxel_spacing: float = None, invert: bool = False, **kwargs) -> Optional[Tuple[CopickMesh, Dict[str, int]]]

Limit a mesh to vertices within a certain distance of a reference surface.

Parameters:

mesh (CopickMesh) –

CopickMesh to limit
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output mesh
session_id (str) –

Session ID for the output mesh
user_id (str) –

User ID for the output mesh
reference_mesh (Optional[CopickMesh], default: None ) –

Reference CopickMesh (one of mesh/segmentation/tomogram must be provided)
reference_segmentation (Optional[CopickSegmentation], default: None ) –

Reference CopickSegmentation
reference_tomogram_info (Optional[Tuple[str, float]], default: None ) –

Tuple of (tomo_type, voxel_spacing) for tomogram boundary reference
max_distance (float, default: 100.0 ) –

Maximum distance from reference surface
mesh_voxel_spacing (float, default: None ) –

Voxel spacing for mesh voxelization (defaults to 10.0)
invert (bool, default: False ) –

If False (default), keep vertices within max_distance. If True, keep vertices beyond max_distance.
**kwargs –

Additional keyword arguments

Returns:

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

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

Stats dict contains 'vertices_created' and 'faces_created'.

copick_utils.logical.distance_operations.limit_segmentation_by_distance

limit_segmentation_by_distance(segmentation: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, reference_mesh: Optional[CopickMesh] = None, reference_segmentation: Optional[CopickSegmentation] = None, reference_tomogram_info: Optional[Tuple[str, float]] = None, max_distance: float = 100.0, voxel_spacing: float = 10.0, mesh_voxel_spacing: float = None, is_multilabel: bool = False, invert: bool = False, **kwargs) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Limit a segmentation to voxels within a certain distance of a reference surface.

Parameters:

segmentation (CopickSegmentation) –

CopickSegmentation to limit
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
reference_mesh (Optional[CopickMesh], default: None ) –

Reference CopickMesh (one of mesh/segmentation/tomogram must be provided)
reference_segmentation (Optional[CopickSegmentation], default: None ) –

Reference CopickSegmentation
reference_tomogram_info (Optional[Tuple[str, float]], default: None ) –

Tuple of (tomo_type, voxel_spacing) for tomogram boundary reference
max_distance (float, default: 100.0 ) –

Maximum distance from reference surface
voxel_spacing (float, default: 10.0 ) –

Voxel spacing for the output segmentation
mesh_voxel_spacing (float, default: None ) –

Voxel spacing for mesh voxelization (defaults to target voxel spacing)
is_multilabel (bool, default: False ) –

Whether the segmentation is multilabel
invert (bool, default: False ) –

If False (default), keep voxels within max_distance. If True, keep voxels beyond max_distance.
**kwargs –

Additional keyword arguments

Returns:

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

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

Stats dict contains 'voxels_created'.

copick_utils.logical.distance_operations.limit_picks_by_distance

limit_picks_by_distance(picks: CopickPicks, run: CopickRun, object_name: str, session_id: str, user_id: str, reference_mesh: Optional[CopickMesh] = None, reference_segmentation: Optional[CopickSegmentation] = None, reference_tomogram_info: Optional[Tuple[str, float]] = None, max_distance: float = 100.0, mesh_voxel_spacing: float = None, invert: bool = False, **kwargs) -> Optional[Tuple[CopickPicks, Dict[str, int]]]

Limit picks to those within a certain distance of a reference surface.

Parameters:

picks (CopickPicks) –

CopickPicks to limit
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output picks
session_id (str) –

Session ID for the output picks
user_id (str) –

User ID for the output picks
reference_mesh (Optional[CopickMesh], default: None ) –

Reference CopickMesh (one of mesh/segmentation/tomogram must be provided)
reference_segmentation (Optional[CopickSegmentation], default: None ) –

Reference CopickSegmentation
reference_tomogram_info (Optional[Tuple[str, float]], default: None ) –

Tuple of (tomo_type, voxel_spacing) for tomogram boundary reference
max_distance (float, default: 100.0 ) –

Maximum distance from reference surface
mesh_voxel_spacing (float, default: None ) –

Voxel spacing for mesh voxelization (defaults to 10.0)
invert (bool, default: False ) –

If False (default), keep picks within max_distance. If True, keep picks beyond max_distance.
**kwargs –

Additional keyword arguments

Returns:

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

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

Stats dict contains 'points_created'.

Point inclusion / exclusion

copick_utils.logical.point_operations.picks_inclusion_by_mesh

picks_inclusion_by_mesh(picks: CopickPicks, run: CopickRun, object_name: str, session_id: str, user_id: str, reference_mesh: Optional[CopickMesh] = None, reference_segmentation: Optional[CopickSegmentation] = None, **kwargs) -> Optional[Tuple[CopickPicks, Dict[str, int]]]

Filter picks to include only those inside a reference mesh or segmentation.

Parameters:

picks (CopickPicks) –

CopickPicks to filter
reference_mesh (Optional[CopickMesh], default: None ) –

Reference CopickMesh (either this or reference_segmentation must be provided)
reference_segmentation (Optional[CopickSegmentation], default: None ) –

Reference CopickSegmentation
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output picks
session_id (str) –

Session ID for the output picks
user_id (str) –

User ID for the output picks
**kwargs –

Additional keyword arguments (e.g. voxel_spacing, reference_tomogram_info; ignored)

Returns:

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

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

Stats dict contains 'points_created'.

copick_utils.logical.point_operations.picks_exclusion_by_mesh

picks_exclusion_by_mesh(picks: CopickPicks, run: CopickRun, object_name: str, session_id: str, user_id: str, reference_mesh: Optional[CopickMesh] = None, reference_segmentation: Optional[CopickSegmentation] = None, **kwargs) -> Optional[Tuple[CopickPicks, Dict[str, int]]]

Filter picks to exclude those inside a reference mesh or segmentation.

Parameters:

picks (CopickPicks) –

CopickPicks to filter
reference_mesh (Optional[CopickMesh], default: None ) –

Reference CopickMesh (either this or reference_segmentation must be provided)
reference_segmentation (Optional[CopickSegmentation], default: None ) –

Reference CopickSegmentation
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output picks
session_id (str) –

Session ID for the output picks
user_id (str) –

User ID for the output picks
**kwargs –

Additional keyword arguments (e.g. voxel_spacing, reference_tomogram_info; ignored)

Returns:

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

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

Stats dict contains 'points_created'.

Usage Examples

Keep only picks within a distance of a reference mesh

import copick
from copick_utils.logical.distance_operations import limit_picks_by_distance

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

kept, stats = limit_picks_by_distance(
    picks=run.get_picks(object_name="ribosome")[0],
    run=run,
    object_name="ribosome",
    session_id="near-membrane",
    user_id="copick-utils",
    reference_mesh=run.get_meshes(object_name="membrane")[0],
    max_distance=150.0,      # angstroms
)
print(stats)

Union of two meshes

from copick_utils.logical.mesh_operations import mesh_union

merged, stats = mesh_union(
    mesh1=run.get_meshes(object_name="compartment-a")[0],
    mesh2=run.get_meshes(object_name="compartment-b")[0],
    run=run,
    object_name="compartments",
    session_id="0",
    user_id="copick-utils",
)