copick logical clipseg

utils

Limit segmentation voxels by distance to a reference.

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.

DefaultInvert (beyond)

copick logical clipseg Default input — Input

copick logical clipseg Default output — Output

Limit segmentation voxels by distance to a reference.

copick logical clipseg Invert (beyond) input — Input

copick logical clipseg Invert (beyond) output — Output

Limit segmentation voxels by distance to a reference.

Usage

copick logical clipseg [OPTIONS]

Description

The reference surface can be a mesh, a segmentation, or a tomogram boundary. Each input segmentation voxel is kept or dropped based on its distance to that surface. By default, voxels within --max-distance (in angstroms) of the surface are kept; pass --invert to instead keep only the voxels beyond that distance.

Provide exactly one reference via --ref-mesh, --ref-seg, or --ref-tomogram.

URI Format

Segmentations: name:user_id/session_id@voxel_spacing
Meshes: object_name:user_id/session_id
Tomograms: tomo_type@voxel_spacing

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 segmentation URI (format: name:user_id/session_id@voxel_spacing). Supports glob patterns.

Reference Options

Option	Type	Default	Description
`--ref-mesh, -rm`	COPICK_URI	—	Reference mesh URI (format: object_name:user_id/session_id). Supports glob patterns.
`--ref-seg, -rs`	COPICK_URI	—	Reference segmentation URI (format: name:user_id/session_id@voxel_spacing). Supports glob patterns.
`--ref-tomogram, -rt`	COPICK_URI	—	Reference tomogram boundary URI (format: tomo_type@voxel_spacing). Uses tomogram volume boundaries as reference surface. Example: 'wbp@10.0'

Tool Options

Option	Type	Default	Description
`--max-distance, -d`	float	`100.0`	Maximum distance from reference surface (in angstroms).
`--mesh-voxel-spacing, -mvs`	float	—	Voxel spacing for mesh voxelization when using mesh reference (defaults to target voxel spacing).
`--invert / --no-invert`	boolean flag	`False`	Invert filtering: keep data BEYOND max_distance instead of WITHIN (default: keep within).
`--workers, -w`	integer	`8`	Number of worker processes.

Output Options

Option	Type	Default	Description
`--output, -o`	COPICK_URI	required	Output segmentation URI. Supports smart defaults (e.g., "membrane", "membrane/my-session", or "/my-session"). Full format: object_name:user_id/session_id@voxel_spacing.

Examples

# Keep voxels within 50Å of a mesh reference
copick logical clipseg -i "membrane:user1/full-001@10.0" \
    -rm "boundary:user1/boundary-001" \
    -o "membrane:clipseg/near-001@10.0" --max-distance 50.0

# Remove voxels within 50Å of the tomogram boundary (keep the interior)
copick logical clipseg -i "membrane:user1/full-001@10.0" \
    -rt "wbp@10.0" \
    -o "membrane:clipseg/interior-001@10.0" --max-distance 50.0 --invert

# Keep voxels beyond 100Å from a segmentation reference
copick logical clipseg -i "membrane:user1/full-001@10.0" \
    -rs "mask:user1/mask-001@10.0" \
    -o "membrane:clipseg/far-001@10.0" --max-distance 100.0 --invert