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, prune_length: Optional[float] = None)

Post-process the skeleton to remove artifacts.

Parameters:

remove_short_branches (bool, default: True ) –

Whether to remove small skeleton pieces. Despite the name, this removes whole connected skeleton pieces with fewer than min_branch_length voxels; it does not shorten side branches of a larger skeleton (prune_length does).
min_branch_length (int, default: 5 ) –

Minimum number of voxels of a skeleton piece to keep
prune_length (Optional[float], default: None ) –

If set, prune side branches (spurs) shorter than this many voxels

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', output_name: Optional[str] = None, prune_length: Optional[float] = None) -> 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
output_name (Optional[str], default: None ) –

Name of the output segmentation (default: the input's name)
prune_length (Optional[float], default: None ) –

If set, prune skeleton side branches shorter than this many voxels

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.

Coordinates are voxel indices: skeleton coordinates in (z, y, x) order, as np.argwhere returns them, and spline points in (x, y, z) order.

extract_skeleton_coordinates

extract_skeleton_coordinates(binary_volume: ndarray) -> np.ndarray

Extract (z, y, x) coordinates of the skeleton voxels.

order_skeleton_points_longest_path

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

Order skeleton points along the longest filament chain.

The skeleton is split into chains between ends and junctions, continuing straight through junctions, and the longest chain is returned in order.

Parameters:

coords (ndarray) –

(N, 3) skeleton voxel coordinates (z, y, x).
connectivity_radius (float, default: 2.0 ) –

Unused; skeleton voxels are connected to their 26 neighbours.

Returns:

ndarray –

(M, 3) ordered coordinates (z, y, x) of the longest chain.

fit_regularized_spline

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

Fit a smoothing spline to ordered (z, y, x) coordinates.

Parameters:

coords (ndarray) –

(N, 3) ordered coordinates (z, y, x).
smoothing_factor (Optional[float], default: None ) –

scipy splprep smoothing factor s in voxels squared; None uses scipy's default m - sqrt(2 m) for m points.
degree (int, default: 3 ) –

Spline degree (1-5).

Returns:

Any –

The spline as scipy's (knots, [cx, cy, cz], degree) in (x, y, z) voxel coordinates.

sample_points_along_spline

sample_points_along_spline(spacing_distance: float) -> np.ndarray

Sample points along the spline at exactly spacing_distance voxels, from its start.

Parameters:

spacing_distance (float) –

Distance between consecutive points along the spline, in voxels.

Returns:

ndarray –

(N, 3) sampled points (x, y, z) in voxel coordinates.

compute_transforms

compute_transforms() -> np.ndarray

Compute 4x4 transformation matrices for each sampled point.

The rotation's +Z axis is the spline's tangent (its exact derivative) at the point, in the direction of the sampling. The rotation about the axis is rotation-minimizing along the spline, starting from the coordinate axis least aligned with the first tangent, so it never flips. The translation is 0.

Returns:

ndarray –

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

get_spline_properties

get_spline_properties() -> Dict[str, Any]

Properties of the fitted spline: length, sampled point count and spacing, and curvature (1/voxel).

max_turn

max_turn() -> float

The largest sine of the turning angle between consecutive sampled segments (the --curvature-threshold quantity; it depends on the sampling spacing).

detect_high_curvature_outliers

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

Deprecated: returns coords unchanged.

Earlier versions deleted skeleton points around sharp bends, which also removed real curves. Sharp bends are now handled by raising the spline's smoothing (fit_spline_to_skeleton).

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]]

Fit a smoothing spline to the longest filament of a skeleton and sample points along it.

Parameters:

binary_volume (ndarray) –

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

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

Smoothing parameter for spline fitting (scipy's s, voxels squared; auto if None)
degree (int, default: 3 ) –

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

Unused; skeleton voxels are connected to their 26 neighbours
compute_transforms (bool, default: True ) –

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

Largest sine of the turning angle between consecutive samples; a sharper fit is smoothed further
max_iterations (int, default: 5 ) –

Maximum number of smoothing increases

Returns:

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

Tuple of (sampled_points, transforms, spline_fitter, properties): - sampled_points: Nx3 array of points (x, y, z, voxels) exactly spacing_distance apart - 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, label: Optional[int] = None, filaments_object_name: Optional[str] = None, filaments_user_id: Optional[str] = None, filaments_session_id: Optional[str] = None, **kwargs) -> Optional[Tuple[CopickPicks, Dict[str, int]]]

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

Matches the lazy converter signature

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

Every filament gets its own spline. The picks of all filaments go into one pick set, grouped by filament and in order along it, with the filament's ID (1..K by length, longest first) as instance_id.

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, in voxels
smoothing_factor (Optional[float], default: None ) –

Smoothing parameter for spline fitting (scipy's s, voxels squared; auto if None)
degree (int, default: 3 ) –

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

Unused; skeleton voxels are connected to their 26 neighbours
compute_transforms (bool, default: True ) –

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

Largest sine of the turning angle between consecutive samples
max_iterations (int, default: 5 ) –

Maximum number of smoothing increases
voxel_spacing (float, default: 1.0 ) –

Voxel spacing for coordinate scaling (the segmentation's own voxel size is used when known)
label (Optional[int], default: None ) –

Label to fit in a multilabel segmentation (default: every non-zero voxel)
filaments_object_name (Optional[str], default: None ) –

Also store the fitted splines as copick Filaments under this object name
filaments_user_id (Optional[str], default: None ) –

User ID of the Filaments
filaments_session_id (Optional[str], default: None ) –

Session ID of the Filaments ({input_session_id} is replaced)
**kwargs –

Additional keyword arguments from the lazy converter

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' and 'filaments_fitted'.

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, panoptic: bool = False) -> 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.
panoptic (bool, default: False ) –

Split a panoptic segmentation (see split_panoptic_segmentation).

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",
)