Skip to content

copick logical meshop

utils

Perform boolean operations between meshes.

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.

copick logical meshop Default input
Input

copick logical meshop Default output
Output

Perform boolean operations between meshes.

copick logical meshop Difference input
Input

copick logical meshop Difference output
Output

Perform boolean operations between meshes.

copick logical meshop Intersection input
Input

copick logical meshop Intersection output
Output

Perform boolean operations between meshes.

copick logical meshop Exclusion input
Input

copick logical meshop Exclusion output
Output

Perform boolean operations between meshes.

Usage

copick logical meshop [OPTIONS]

Description

Combine, subtract, or intersect mesh annotations across runs using boolean geometry. Supported operations are union (combine matching meshes, accepts N>=1 inputs), difference (first minus second, requires exactly 2 inputs), intersection (common volume, requires exactly 2 inputs), exclusion (exclusive-or / XOR, requires exactly 2 inputs), and concatenate (simple concatenation without boolean ops, accepts N>=1 inputs).

Input meshes are selected by URI. Patterns use glob wildcards (* and ?) by default, or regular expressions when prefixed with re:. When a single -i flag is given with a pattern, union and concatenate expand that pattern within each run and merge all matching meshes, which is useful for combining multiple versions or annotations per run.

URI Format

Meshes: object_name:user_id/session_id

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 · multiple required Input mesh URI (format: object_name:user_id/session_id). Can be specified multiple times for N-way operations. Supports glob patterns (default) or regex patterns (re: prefix).

Tool Options

Option Type Default Description
--operation, -op choice (union | difference | intersection | exclusion | concatenate) required Boolean operation to perform.
--workers, -w integer 8 Number of worker processes.

Output Options

Option Type Default Description
--output, -o COPICK_URI required Output mesh URI. Supports smart defaults (e.g., "membrane", "membrane/my-session", or "/my-session"). Full format: object_name:user_id/session_id.
--individual-meshes, -im / --no-individual-meshes boolean flag False Create individual meshes for each instance (enables {instance_id} placeholder).

Examples

# Single-input union: merge all matching meshes within each run
copick logical meshop --operation union \
    -i "membrane:user*/manual-*" \
    -o "merged"

# Single-input concatenation: concatenate all matching meshes per run
copick logical meshop --operation concatenate \
    -i "part*:user1/session-*" \
    -o "combined"

# N-way union with multiple -i flags (merge across different objects)
copick logical meshop --operation union \
    -i "membrane:user1/manual-*" \
    -i "vesicle:user2/auto-*" \
    -i "ribosome:user3/pred-*" \
    -o "merged"

# N-way union with regex patterns
copick logical meshop --operation union \
    -i "re:membrane:user1/manual-\d+" \
    -i "re:vesicle:user2/auto-\d+" \
    -o "merged"

# 2-way difference (exactly 2 inputs required)
copick logical meshop --operation difference \
    -i "membrane:user1/manual-001" \
    -i "mask:user1/mask-001" \
    -o "membrane:meshop/masked"

# N-way concatenation with multiple -i flags
copick logical meshop --operation concatenate \
    -i "part1:user1/session" \
    -i "part2:user1/session" \
    -i "part3:user1/session" \
    -o "combined"

See also