Processing

The copick_utils.process module provides segmentation-processing utilities: connected-component analysis, skeletonization, spline fitting, rescaling, label splitting, valid-box generation, and thickness filtering.

These are the functional building blocks behind the copick process ... CLI commands.

Connected components

copick_utils.process.connected_components.separate_segmentation_components

separate_segmentation_components(segmentation: CopickSegmentation, connectivity: Union[int, str] = 'all', min_size: Optional[float] = None, session_id_template: str = 'inst-{instance_id}', output_user_id: str = 'components', multilabel: bool = True, session_id_prefix: str = None) -> List[CopickSegmentation]

Separate connected components in a segmentation into individual segmentations.

Parameters:

segmentation (CopickSegmentation) –

Input segmentation to process
connectivity (Union[int, str], default: 'all' ) –

Connectivity for connected components (default: "all") String format: "face" (6-connected), "face-edge" (18-connected), "all" (26-connected) Legacy int format: 6, 18, or 26 (for backward compatibility)
min_size (Optional[float], default: None ) –

Minimum component volume in cubic angstroms (Å³) to keep (None = keep all)
session_id_template (str, default: 'inst-{instance_id}' ) –

Template for output session IDs with {instance_id} placeholder
output_user_id (str, default: 'components' ) –

User ID for output segmentations
multilabel (bool, default: True ) –

Whether to treat input as multilabel segmentation
session_id_prefix (str, default: None ) –

Deprecated. Use session_id_template instead.

Returns:

List[CopickSegmentation] –

List of created segmentations, one per component

copick_utils.process.connected_components.separate_connected_components_3d

separate_connected_components_3d(volume: ndarray, voxel_spacing: float, connectivity: Union[int, str] = 'all', min_size: Optional[float] = None) -> Tuple[np.ndarray, int, Dict[int, Dict[str, Any]]]

Separate connected components in a 3D binary or labeled volume.

Parameters:

volume (ndarray) –

3D binary or labeled segmentation volume
voxel_spacing (float) –

Voxel spacing in angstroms
connectivity (Union[int, str], default: 'all' ) –

Connectivity for connected components (default: "all") String format: "face" (6-connected), "face-edge" (18-connected), "all" (26-connected) Legacy int format: 6, 18, or 26 (for backward compatibility)
min_size (Optional[float], default: None ) –

Minimum component volume in cubic angstroms (Å³) to keep (None = keep all)

Returns:

Tuple[ndarray, int, Dict[int, Dict[str, Any]]] –

Tuple of (labeled_volume, num_components, component_info): - labeled_volume: Volume with each connected component labeled with unique integer - num_components: Number of connected components found - component_info: Dictionary with information about each component

copick_utils.process.connected_components.extract_individual_components

extract_individual_components(labeled_volume: ndarray) -> List[np.ndarray]

Extract each connected component as a separate binary volume.

Parameters:

labeled_volume (ndarray) –

Volume with labeled connected components

Returns:

List[ndarray] –

List of binary volumes, each containing one component

copick_utils.process.connected_components.print_component_stats

print_component_stats(component_info: Dict[int, Dict[str, Any]]) -> None

Print statistics about connected components.

Skeletonization

copick_utils.process.skeletonize.TubeSkeletonizer3D

3D tube skeletonization class based on scikit-image.

load_volume

load_volume(volume_array: ndarray)

Load 3D volume from array.

Parameters:

volume_array (ndarray) –

3D binary array where tube is 1, background is 0

preprocess_volume

preprocess_volume(remove_noise: bool = True, min_object_size: int = 100)

Preprocess the volume before skeletonization.

Parameters:

remove_noise (bool, default: True ) –

Whether to remove small objects (noise)
min_object_size (int, default: 100 ) –

Minimum size of objects to keep

skeletonize

skeletonize(method: str = 'skimage')

Perform 3D skeletonization.

Parameters:

method (str, default: 'skimage' ) –

Method to use ('skimage', 'distance_transform')

post_process_skeleton

post_process_skeleton(remove_short_branches: bool = True, min_branch_length: int = 5)

Post-process the skeleton to remove artifacts.

Parameters:

remove_short_branches (bool, default: True ) –

Whether to remove short branches
min_branch_length (int, default: 5 ) –

Minimum length of branches to keep

get_skeleton_properties

get_skeleton_properties() -> Dict[str, Any]

Calculate properties of the skeleton.

Returns:

Dict[str, Any] –

Dict of skeleton properties

copick_utils.process.skeletonize.skeletonize_segmentation

skeletonize_segmentation(segmentation: CopickSegmentation, method: str = 'skimage', remove_noise: bool = True, min_object_size: int = 50, remove_short_branches: bool = True, min_branch_length: int = 5, output_session_id: Optional[str] = None, output_user_id: str = 'skel') -> Optional[CopickSegmentation]

Skeletonize a segmentation volume.

Parameters:

segmentation (CopickSegmentation) –

Input segmentation to skeletonize
method (str, default: 'skimage' ) –

Skeletonization method ('skimage', 'distance_transform')
remove_noise (bool, default: True ) –

Whether to remove small objects before skeletonization
min_object_size (int, default: 50 ) –

Minimum size of objects to keep during preprocessing
remove_short_branches (bool, default: True ) –

Whether to remove short branches from skeleton
min_branch_length (int, default: 5 ) –

Minimum length of branches to keep
output_session_id (Optional[str], default: None ) –

Session ID for output segmentation (default: same as input)
output_user_id (str, default: 'skel' ) –

User ID for output segmentation

Returns:

Optional[CopickSegmentation] –

Created skeleton segmentation or None if failed

Spline fitting

copick_utils.process.spline_fitting.SkeletonSplineFitter

3D spline fitting to skeleton coordinates with point sampling and orientation computation.

extract_skeleton_coordinates

extract_skeleton_coordinates(binary_volume: ndarray) -> np.ndarray

Extract skeleton coordinates from binary volume.

order_skeleton_points_longest_path

order_skeleton_points_longest_path(coords: ndarray, connectivity_radius: float = 2.0) -> np.ndarray

Order skeleton points by finding the longest path through the skeleton.

fit_regularized_spline

fit_regularized_spline(coords: ndarray, smoothing_factor: Optional[float] = None, degree: int = 3) -> Tuple[np.ndarray, Dict[str, Any]]

Fit regularized 3D parametric spline using scipy.interpolate.splprep.

sample_points_along_spline

sample_points_along_spline(spacing_distance: float) -> np.ndarray

Sample points along the spline at regular intervals using arc-length parameterization.

compute_transforms

compute_transforms() -> np.ndarray

Compute 4x4 transformation matrices for each sampled point. Follows the ArtiaX pattern: z_align(last_pos, curr_pos).zero_translation().inverse() The rotation from particle i-1 to particle i is applied to particle i-1.

Returns:

ndarray –

np.ndarray: [N, 4, 4] array of transformation matrices

get_spline_properties

get_spline_properties() -> Dict[str, Any]

Get properties of the fitted spline.

detect_high_curvature_outliers

detect_high_curvature_outliers(coords: ndarray, curvature_threshold: float = 0.2) -> np.ndarray

Detect points that contribute to high curvature.

copick_utils.process.spline_fitting.fit_spline_to_skeleton

fit_spline_to_skeleton(binary_volume: ndarray, spacing_distance: float, smoothing_factor: Optional[float] = None, degree: int = 3, connectivity_radius: float = 2.0, compute_transforms: bool = True, curvature_threshold: float = 0.2, max_iterations: int = 5) -> Tuple[np.ndarray, Optional[np.ndarray], SkeletonSplineFitter, Dict[str, Any]]

Main function to fit a regularized 3D spline to a skeleton and sample points.

Parameters:

binary_volume (ndarray) –

3D binary volume where skeleton is True/1
spacing_distance (float) –

Distance between consecutive sampled points along the spline
smoothing_factor (Optional[float], default: None ) –

Smoothing parameter for spline fitting (auto if None)
degree (int, default: 3 ) –

Degree of the spline (1-5)
connectivity_radius (float, default: 2.0 ) –

Maximum distance to consider skeleton points as connected
compute_transforms (bool, default: True ) –

Whether to compute 4x4 transformation matrices for each point
curvature_threshold (float, default: 0.2 ) –

Maximum allowed curvature before outlier removal (default 0.2)
max_iterations (int, default: 5 ) –

Maximum number of outlier removal iterations (default 5)

Returns:

Tuple[ndarray, Optional[ndarray], SkeletonSplineFitter, Dict[str, Any]] –

Tuple of (sampled_points, transforms, spline_fitter, properties): - sampled_points: Nx3 array of evenly spaced points along spline - transforms: [N, 4, 4] array of transformation matrices (or None if compute_transforms=False) - spline_fitter: SkeletonSplineFitter object for further analysis - properties: dict with spline properties

copick_utils.process.spline_fitting.fit_spline_to_segmentation

fit_spline_to_segmentation(segmentation: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, spacing_distance: float, smoothing_factor: Optional[float] = None, degree: int = 3, connectivity_radius: float = 2.0, compute_transforms: bool = True, curvature_threshold: float = 0.2, max_iterations: int = 5, voxel_spacing: float = 1.0) -> Optional[Tuple[CopickPicks, Dict[str, int]]]

Fit a spline to a segmentation (skeleton) volume and create picks with orientations.

Matches the lazy converter signature

(segmentation, run, object_name, session_id, user_id, **tool_kwargs)

Parameters:

segmentation (CopickSegmentation) –

Input segmentation containing skeleton to fit spline to
run (CopickRun) –

CopickRun object
object_name (str) –

Name for the output pick object
session_id (str) –

Session ID for output picks
user_id (str) –

User ID for output picks
spacing_distance (float) –

Distance between consecutive sampled points along the spline
smoothing_factor (Optional[float], default: None ) –

Smoothing parameter for spline fitting (auto if None)
degree (int, default: 3 ) –

Degree of the spline (1-5)
connectivity_radius (float, default: 2.0 ) –

Maximum distance to consider skeleton points as connected
compute_transforms (bool, default: True ) –

Whether to compute orientations for picks
curvature_threshold (float, default: 0.2 ) –

Maximum allowed curvature before outlier removal
max_iterations (int, default: 5 ) –

Maximum number of outlier removal iterations
voxel_spacing (float, default: 1.0 ) –

Voxel spacing for coordinate scaling

Returns:

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

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

Stats dict contains 'picks_created'.

Rescaling

copick_utils.process.rescale.rescale_segmentation

rescale_segmentation(segmentation: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, target_voxel_spacing: float, tomo_type: Optional[str] = None, order: int = 0, **kwargs) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Rescale a segmentation to a different voxel spacing.

Parameters:

segmentation (CopickSegmentation) –

Input CopickSegmentation object.
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.
target_voxel_spacing (float) –

Target voxel spacing in angstroms.
tomo_type (Optional[str], default: None ) –

Tomogram type for shape reference. When provided, output shape matches the tomogram at the target spacing exactly.
order (int, default: 0 ) –

Interpolation order (0=nearest-neighbor, 1=linear).
**kwargs –

Additional keyword arguments from lazy converter.

Returns:

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

Tuple of (CopickSegmentation, stats dict) or None if operation failed.

Label operations

copick_utils.process.split_labels.split_multilabel_segmentation

split_multilabel_segmentation(segmentation: CopickSegmentation, run: CopickRun, output_user_id: str = 'split', labels: Optional[Dict[str, int]] = None) -> List[CopickSegmentation]

Split a multilabel segmentation into individual single-class binary segmentations.

For each label value in the multilabel segmentation, this function looks up the corresponding PickableObject and creates a binary segmentation named after that object.

Parameters:

segmentation (CopickSegmentation) –

Input multilabel segmentation to split
run (CopickRun) –

CopickRun object containing the segmentation
output_user_id (str, default: 'split' ) –

User ID for output segmentations (default: "split")
labels (Optional[Dict[str, int]], default: None ) –

Optional explicit {name: label_value} mapping. When provided, the outputs are named by this mapping (instead of looking the label value up in the pickable-objects config), and only the listed label values are split. Useful when the segmentation's label values do not match the config object labels (e.g. argmax predictions with values 1/2 vs config labels 102/25).

Returns:

List[CopickSegmentation] –

List of created CopickSegmentation objects, one per label found in the input

copick_utils.process.split_labels.split_labels_batch

split_labels_batch(root: CopickRoot, segmentation_name: str, segmentation_user_id: str, segmentation_session_id: str, voxel_spacing: float, output_user_id: str = 'split', run_names: Optional[List[str]] = None, workers: int = 8, labels: Optional[Dict[str, int]] = None) -> Dict[str, Any]

Batch split multilabel segmentations across multiple runs.

Parameters:

root (CopickRoot) –

The copick root containing runs to process
segmentation_name (str) –

Name of the input segmentation
segmentation_user_id (str) –

User ID of the input segmentation
segmentation_session_id (str) –

Session ID of the input segmentation
voxel_spacing (float) –

Voxel spacing in angstroms
output_user_id (str, default: 'split' ) –

User ID for output segmentations (default: "split")
run_names (Optional[List[str]], default: None ) –

List of run names to process. If None, processes all runs.
workers (int, default: 8 ) –

Number of worker processes (default: 8)
labels (Optional[Dict[str, int]], default: None ) –

Optional explicit {name: label_value} mapping for naming outputs (see split_multilabel_segmentation). None = resolve names from config.

Returns:

Dict[str, Any] –

Dictionary with processing results and statistics per run

Valid-box generation

copick_utils.process.validbox.create_validbox_mesh

create_validbox_mesh(run: CopickRun, voxel_spacing: float, tomo_type: str = 'wbp', angle: float = 0.0) -> Optional[tm.Trimesh]

Create a box mesh representing the valid area of a reconstruction.

Parameters:

run (CopickRun) –

Copick run object
voxel_spacing (float) –

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

Type of tomogram to use as reference
angle (float, default: 0.0 ) –

Rotation angle around Z-axis in degrees

Returns:

Optional[Trimesh] –

Trimesh box object or None if tomogram not found

copick_utils.process.validbox.generate_validbox

generate_validbox(run: CopickRun, voxel_spacing: float, mesh_object_name: str, mesh_user_id: str, mesh_session_id: str, tomo_type: str = 'wbp', angle: float = 0.0) -> Optional[Dict[str, Any]]

Generate a valid area box mesh for a single run.

Parameters:

run (CopickRun) –

Copick run object
voxel_spacing (float) –

Voxel spacing for the tomogram
mesh_object_name (str) –

Name of the mesh object to create
mesh_user_id (str) –

User ID for the mesh
mesh_session_id (str) –

Session ID for the mesh
tomo_type (str, default: 'wbp' ) –

Type of tomogram to use as reference
angle (float, default: 0.0 ) –

Rotation angle around Z-axis in degrees

Returns:

Optional[Dict[str, Any]] –

Dictionary with result information or None if failed

Thickness filtering

copick_utils.process.thickness_filter.thickness_filter_segmentation

thickness_filter_segmentation(segmentation: CopickSegmentation, run: CopickRun, object_name: str, session_id: str, user_id: str, min_thickness: float = 50.0, **kwargs) -> Optional[Tuple[CopickSegmentation, Dict[str, int]]]

Filter thin regions from a segmentation by thickness.

Parameters:

segmentation (CopickSegmentation) –

Input CopickSegmentation object.
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.
min_thickness (float, default: 50.0 ) –

Minimum thickness in angstroms (diameter) to keep.
**kwargs –

Additional keyword arguments from lazy converter.

Returns:

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

Tuple of (CopickSegmentation object, stats dict) or None if operation failed.

Usage Examples

Split a segmentation into connected components

import copick
from copick_utils.process.connected_components import separate_segmentation_components

root = copick.from_file("config.json")
run = root.get_run("TS_001")
seg = run.get_segmentations(name="membrane")[0]

components = separate_segmentation_components(
    segmentation=seg,
    connectivity="all",      # 26-connectivity
    min_size=1000.0,         # drop components smaller than 1000 Å³
    output_user_id="components",
)
print(f"found {len(components)} components")

Rescale a segmentation to a new voxel spacing

from copick_utils.process.rescale import rescale_segmentation

rescaled, stats = rescale_segmentation(
    segmentation=seg,
    run=run,
    object_name="membrane",
    session_id="0",
    user_id="copick-utils",
    target_voxel_spacing=20.0,
    tomo_type="wbp",
)