copick-utils 0.6.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

copick_utils/cli/segop.py

@@ -0,0 +1,248 @@
+"""CLI commands for segmentation logical operations (boolean operations)."""
+
+import click
+import copick
+from click_option_group import optgroup
+from copick.cli.util import add_config_option, add_debug_option
+from copick.util.log import get_logger
+from copick.util.uri import parse_copick_uri
+
+from copick_utils.cli.util import (
+    add_boolean_operation_option,
+    add_multi_input_options,
+    add_output_option,
+    add_workers_option,
+)
+from copick_utils.util.config_models import (
+    create_dual_selector_config,
+    create_multi_selector_config,
+)
+
+
+@click.command(
+    context_settings={"show_default": True},
+    short_help="Perform boolean operations between segmentations.",
+    no_args_is_help=True,
+)
+@add_config_option
+@optgroup.group("\nInput Options", help="Options related to input segmentations.")
+@optgroup.option(
+    "--run-names",
+    "-r",
+    multiple=True,
+    help="Specific run names to process (default: all runs).",
+)
+@add_multi_input_options("segmentation")
+@optgroup.group("\nTool Options", help="Options related to this tool.")
+@add_boolean_operation_option
+@optgroup.option(
+    "--voxel-spacing",
+    "-vs",
+    type=float,
+    required=True,
+    help="Voxel spacing for input and output segmentations.",
+)
+@add_workers_option
+@optgroup.group("\nOutput Options", help="Options related to output segmentations.")
+@add_output_option("segmentation", default_tool="segop")
+@add_debug_option
+def segop(
+    config,
+    run_names,
+    input_uris,
+    operation,
+    voxel_spacing,
+    workers,
+    output_uri,
+    debug,
+):
+    """
+    Perform boolean operations between segmentations.
+
+    \b
+    URI Format:
+        Segmentations: name:user_id/session_id (voxel spacing via --voxel-spacing)
+
+    \b
+    Pattern Support:
+        - Glob (default): Use * and ? wildcards (e.g., "membrane:user*/session-*")
+        - Regex: Prefix with 're:' (e.g., "re:membrane:user\\d+/session-\\d+")
+
+    \b
+    Operations:
+        - union: Combine segmentations (logical OR) - accepts N≥1 inputs
+        - difference: First minus second - requires exactly 2 inputs
+        - intersection: Common voxels (logical AND) - requires exactly 2 inputs
+        - exclusion: Exclusive or (XOR) - requires exactly 2 inputs
+
+    \b
+    Note: All segmentations are converted to binary for boolean operations.
+    Voxel spacing applies globally to all inputs and output.
+
+    \b
+    Single-Input Pattern Expansion (union only):
+        When providing a single -i flag with a pattern, the union operation will
+        expand the pattern within each run and merge all matching segmentations.
+        This is useful for combining multiple versions/annotations within each run.
+
+    \b
+    Examples:
+        # Single-input union: merge all matching segmentations within each run
+        copick logical segop --operation union -vs 10.0 \\
+            -i "membrane:user*/manual-*" \\
+            -o "merged"
+
+        # N-way union with multiple -i flags (merge across different objects)
+        copick logical segop --operation union -vs 10.0 \\
+            -i "membrane:user1/manual-*" \\
+            -i "vesicle:user2/auto-*" \\
+            -i "ribosome:user3/pred-*" \\
+            -o "merged"
+
+        # N-way union with regex patterns
+        copick logical segop --operation union -vs 10.0 \\
+            -i "re:membrane:user1/manual-\\d+" \\
+            -i "re:vesicle:user2/auto-\\d+" \\
+            -o "merged"
+
+        # 2-way difference (exactly 2 inputs required)
+        copick logical segop --operation difference -vs 10.0 \\
+            -i "membrane:user1/manual-001" \\
+            -i "mask:user1/mask-001" \\
+            -o "membrane:segop/masked"
+    """
+    logger = get_logger(__name__, debug=debug)
+
+    # VALIDATION: Check input count vs operation
+    num_inputs = len(input_uris)
+
+    if operation in ["difference", "intersection", "exclusion"]:
+        if num_inputs != 2:
+            raise click.BadParameter(
+                f"'{operation}' operation requires exactly 2 inputs, got {num_inputs}. Provide exactly 2 -i flags.",
+            )
+    elif operation == "union" and num_inputs < 1:
+        raise click.BadParameter(
+            f"'{operation}' operation requires at least 1 input, got {num_inputs}. Provide 1 or more -i flags.",
+        )
+
+    root = copick.from_file(config)
+    run_names_list = list(run_names) if run_names else None
+
+    # Append voxel spacing to all URIs
+    input_uris_full = [f"{uri}@{voxel_spacing}" if "@" not in uri else uri for uri in input_uris]
+    output_uri_full = f"{output_uri}@{voxel_spacing}" if "@" not in output_uri else output_uri
+
+    # Create appropriate config based on input count
+    try:
+        if num_inputs == 1:
+            # Single input with pattern expansion (only for union)
+            from copick_utils.util.config_models import create_single_selector_config
+
+            task_config = create_single_selector_config(
+                input_uri=input_uris_full[0],
+                input_type="segmentation",
+                output_uri=output_uri_full,
+                output_type="segmentation",
+                command_name="segop",
+                operation=operation,
+            )
+        elif num_inputs == 2:
+            # Use existing dual selector for 2-input operations
+            task_config = create_dual_selector_config(
+                input1_uri=input_uris_full[0],
+                input2_uri=input_uris_full[1],
+                input_type="segmentation",
+                output_uri=output_uri_full,
+                output_type="segmentation",
+                command_name="segop",
+            )
+        else:
+            # Use new multi selector for N-way operations (N≥3)
+            task_config = create_multi_selector_config(
+                input_uris=input_uris_full,
+                input_type="segmentation",
+                output_uri=output_uri_full,
+                output_type="segmentation",
+                command_name="segop",
+            )
+    except ValueError as e:
+        raise click.BadParameter(str(e)) from e
+
+    # Logging
+    if num_inputs == 1:
+        logger.info(f"Performing {operation} operation with pattern-based input expansion")
+        params = parse_copick_uri(input_uris[0], "segmentation")
+        logger.info(f"  Pattern: {params['name']} ({params['user_id']}/{params['session_id']})")
+        logger.info("  Note: Pattern will be expanded to multiple segmentations per run")
+    else:
+        logger.info(f"Performing {operation} operation on {num_inputs} segmentations")
+        for i, uri in enumerate(input_uris, start=1):
+            params = parse_copick_uri(uri, "segmentation")
+            logger.info(f"  Input {i}: {params['name']} ({params['user_id']}/{params['session_id']})")
+
+    output_params = parse_copick_uri(output_uri_full, "segmentation")
+    logger.info(f"Target: {output_params['name']} ({output_params['user_id']}/{output_params['session_id']})")
+
+    # Select appropriate lazy batch converter
+    if num_inputs == 1:
+        # Single input with pattern expansion (only union supports this)
+        from copick_utils.logical.segmentation_operations import segmentation_multi_union_lazy_batch
+
+        lazy_batch_functions = {
+            "union": segmentation_multi_union_lazy_batch,
+        }
+    elif num_inputs == 2:
+        # Use existing dual converters
+        from copick_utils.logical.segmentation_operations import (
+            segmentation_difference_lazy_batch,
+            segmentation_exclusion_lazy_batch,
+            segmentation_intersection_lazy_batch,
+            segmentation_union_lazy_batch,
+        )
+
+        lazy_batch_functions = {
+            "union": segmentation_union_lazy_batch,
+            "difference": segmentation_difference_lazy_batch,
+            "intersection": segmentation_intersection_lazy_batch,
+            "exclusion": segmentation_exclusion_lazy_batch,
+        }
+    else:
+        # Use new N-way converters (only union supports N>2)
+        from copick_utils.logical.segmentation_operations import segmentation_multi_union_lazy_batch
+
+        lazy_batch_functions = {
+            "union": segmentation_multi_union_lazy_batch,
+        }
+
+    lazy_batch_function = lazy_batch_functions[operation]
+
+    # Execute parallel discovery and processing
+    results = lazy_batch_function(
+        root=root,
+        config=task_config,
+        run_names=run_names_list,
+        workers=workers,
+        voxel_spacing=voxel_spacing,
+    )
+
+    # Aggregate results
+    successful = sum(1 for r in results.values() if r and r.get("processed", 0) > 0)
+    total_voxels = sum(r.get("voxels_created", 0) for r in results.values() if r)
+    total_processed = sum(r.get("processed", 0) for r in results.values() if r)
+
+    all_errors = []
+    for result in results.values():
+        if result and result.get("errors"):
+            all_errors.extend(result["errors"])
+
+    logger.info(f"Completed: {successful}/{len(results)} runs processed successfully")
+    logger.info(f"Total {operation} operations completed: {total_processed}")
+    logger.info(f"Total voxels created: {total_voxels}")
+
+    if all_errors:
+        logger.warning(f"Encountered {len(all_errors)} errors during processing")
+        for error in all_errors[:5]:
+            logger.warning(f"  - {error}")
+        if len(all_errors) > 5:
+            logger.warning(f"  ... and {len(all_errors) - 5} more errors")

copick_utils/cli/separate_components.py

@@ -0,0 +1,155 @@
+import click
+import copick
+from click_option_group import optgroup
+from copick.cli.util import add_config_option, add_debug_option
+from copick.util.log import get_logger
+from copick.util.uri import expand_output_uri, parse_copick_uri
+
+from copick_utils.cli.util import add_input_option, add_output_option
+
+
+@click.command(
+    context_settings={"show_default": True},
+    short_help="Separate connected components in segmentations.",
+    no_args_is_help=True,
+)
+@add_config_option
+@optgroup.group("\nInput Options", help="Options related to the input segmentation.")
+@optgroup.option(
+    "--run-names",
+    multiple=True,
+    help="Specific run names to process (default: all runs).",
+)
+@add_input_option("segmentation")
+@optgroup.group("\nTool Options", help="Options related to this tool.")
+@optgroup.option(
+    "--connectivity",
+    "-cn",
+    type=click.Choice(["face", "face-edge", "all"]),
+    default="all",
+    help="Connectivity for connected components (face=6-connected, face-edge=18-connected, all=26-connected).",
+)
+@optgroup.option(
+    "--min-size",
+    type=float,
+    default=None,
+    help="Minimum component volume in cubic angstroms (ų) to keep (optional).",
+)
+@optgroup.option(
+    "--multilabel/--binary",
+    is_flag=True,
+    default=True,
+    help="Process as multilabel segmentation (analyze each label separately).",
+)
+@optgroup.option(
+    "--workers",
+    type=int,
+    default=8,
+    help="Number of worker processes.",
+)
+@optgroup.group("\nOutput Options", help="Options related to output segmentations.")
+@add_output_option("segmentation", default_tool="components")
+@add_debug_option
+def separate_components(
+    config,
+    run_names,
+    input_uri,
+    connectivity,
+    min_size,
+    multilabel,
+    workers,
+    output_uri,
+    debug,
+):
+    """Separate connected components in segmentations into individual segmentations.
+
+    \b
+    URI Format:
+        Segmentations: name:user_id/session_id@voxel_spacing
+
+    \b
+    For multilabel segmentations, connected components analysis is performed on each
+    label separately. Output segmentations use {instance_id} placeholder for auto-numbering
+    (e.g., "inst-0", "inst-1", etc.).
+
+    \b
+    Examples:
+        # Separate components with smart defaults (auto user_id and session template)
+        copick process separate_components -i "membrane:user1/manual-001@10.0" -o "{instance_id}"
+
+        # Custom session prefix
+        copick process separate_components -i "membrane:user1/manual-001@10.0" -o "membrane:components/inst-{instance_id}"
+
+        # Full URI specification
+        copick process separate_components -i "membrane:user1/manual-001@10.0" -o "membrane:components/comp-{instance_id}@10.0"
+    """
+    from copick_utils.process.connected_components import separate_components_batch
+
+    logger = get_logger(__name__, debug=debug)
+
+    root = copick.from_file(config)
+    run_names_list = list(run_names) if run_names else None
+
+    # Expand output URI with smart defaults (individual_outputs=True for {instance_id})
+    try:
+        output_uri = expand_output_uri(
+            output_uri=output_uri,
+            input_uri=input_uri,
+            input_type="segmentation",
+            output_type="segmentation",
+            command_name="components",
+            individual_outputs=True,
+        )
+    except ValueError as e:
+        raise click.BadParameter(f"Error expanding output URI: {e}") from e
+
+    # Parse input URI
+    try:
+        input_params = parse_copick_uri(input_uri, "segmentation")
+    except ValueError as e:
+        raise click.BadParameter(f"Invalid input URI: {e}") from e
+
+    segmentation_name = input_params["name"]
+    segmentation_user_id = input_params["user_id"]
+    segmentation_session_id = input_params["session_id"]
+
+    # Parse output URI (now fully expanded)
+    try:
+        output_params = parse_copick_uri(output_uri, "segmentation")
+    except ValueError as e:
+        raise click.BadParameter(f"Invalid output URI: {e}") from e
+
+    output_user_id = output_params["user_id"]
+    output_session_id_template = output_params["session_id"]
+
+    # Validate that output_session_id_template contains {instance_id}
+    if "{instance_id}" not in output_session_id_template:
+        raise click.BadParameter("Output URI must contain {instance_id} placeholder for separate_components command")
+
+    logger.info(f"Separating connected components for segmentation '{segmentation_name}'")
+    logger.info(f"Source segmentation: {segmentation_user_id}/{segmentation_session_id}")
+    logger.info(f"Output template: {output_params['name']} ({output_user_id}/{output_session_id_template})")
+    logger.info(f"Connectivity: {connectivity}")
+    if min_size is not None:
+        logger.info(f"Minimum size: {min_size} ų")
+    logger.info(f"Processing as {'multilabel' if multilabel else 'binary'} segmentation")
+
+    results = separate_components_batch(
+        root=root,
+        segmentation_name=segmentation_name,
+        segmentation_user_id=segmentation_user_id,
+        segmentation_session_id=segmentation_session_id,
+        connectivity=connectivity,
+        min_size=min_size,
+        session_id_template=output_session_id_template,
+        output_user_id=output_user_id,
+        multilabel=multilabel,
+        run_names=run_names_list,
+        workers=workers,
+    )
+
+    successful = sum(1 for result in results.values() if result and result.get("processed", 0) > 0)
+    total_components = sum(result.get("components_created", 0) for result in results.values() if result)
+
+    logger.info(f"Completed: {successful}/{len(results)} runs processed successfully")
+    logger.info(f"Total components created: {total_components}")

copick_utils/cli/skeletonize.py

@@ -0,0 +1,164 @@
+import click
+import copick
+from click_option_group import optgroup
+from copick.cli.util import add_config_option, add_debug_option
+from copick.util.log import get_logger
+from copick.util.uri import expand_output_uri, parse_copick_uri
+
+from copick_utils.cli.util import add_input_option, add_output_option
+
+
+@click.command(
+    context_settings={"show_default": True},
+    short_help="3D skeletonization of segmentations.",
+    no_args_is_help=True,
+)
+@add_config_option
+@optgroup.group("\nInput Options", help="Options related to the input segmentation.")
+@optgroup.option(
+    "--run-names",
+    multiple=True,
+    help="Specific run names to process (default: all runs).",
+)
+@add_input_option("segmentation")
+@optgroup.group("\nTool Options", help="Options related to this tool.")
+@optgroup.option(
+    "--method",
+    type=click.Choice(["skimage", "distance_transform"]),
+    default="skimage",
+    help="Skeletonization method.",
+)
+@optgroup.option(
+    "--remove-noise/--keep-noise",
+    is_flag=True,
+    default=True,
+    help="Remove small objects before skeletonization.",
+)
+@optgroup.option(
+    "--min-object-size",
+    type=int,
+    default=50,
+    help="Minimum size of objects to keep during preprocessing.",
+)
+@optgroup.option(
+    "--remove-short-branches/--keep-short-branches",
+    is_flag=True,
+    default=True,
+    help="Remove short branches from skeleton.",
+)
+@optgroup.option(
+    "--min-branch-length",
+    type=int,
+    default=5,
+    help="Minimum length of branches to keep.",
+)
+@optgroup.option(
+    "--workers",
+    type=int,
+    default=8,
+    help="Number of worker processes.",
+)
+@optgroup.group("\nOutput Options", help="Options related to output segmentations.")
+@add_output_option("segmentation", default_tool="skel")
+@add_debug_option
+def skeletonize(
+    config,
+    run_names,
+    input_uri,
+    method,
+    remove_noise,
+    min_object_size,
+    remove_short_branches,
+    min_branch_length,
+    workers,
+    output_uri,
+    debug,
+):
+    """3D skeletonization of segmentations using pattern matching.
+
+    \b
+    URI Format:
+        Segmentations: name:user_id/session_id@voxel_spacing
+
+    \b
+    This command can process multiple segmentations by matching session IDs against
+    a pattern. This is useful for processing the output of connected components
+    separation (e.g., pattern "inst-.*" to match "inst-0", "inst-1", etc.).
+
+    \b
+    Examples:
+        # Skeletonize exact match
+        copick process skeletonize -i "membrane:user1/inst-0@10.0" -o "membrane:skel/skel-0@10.0"
+
+        # Skeletonize all instances using pattern
+        copick process skeletonize -i "membrane:user1/inst-.*@10.0" -o "membrane:skel/skel-{input_session_id}@10.0"
+    """
+    from copick_utils.process.skeletonize import skeletonize_batch
+
+    logger = get_logger(__name__, debug=debug)
+
+    root = copick.from_file(config)
+    run_names_list = list(run_names) if run_names else None
+
+    # Expand output URI with smart defaults
+    try:
+        output_uri = expand_output_uri(
+            output_uri=output_uri,
+            input_uri=input_uri,
+            input_type="segmentation",
+            output_type="segmentation",
+            command_name="skeletonize",
+            individual_outputs=False,
+        )
+    except ValueError as e:
+        raise click.BadParameter(f"Error expanding output URI: {e}") from e
+
+    # Parse input URI
+    try:
+        input_params = parse_copick_uri(input_uri, "segmentation")
+    except ValueError as e:
+        raise click.BadParameter(f"Invalid input URI: {e}") from e
+
+    segmentation_name = input_params["name"]
+    segmentation_user_id = input_params["user_id"]
+    session_id_pattern = input_params["session_id"]
+
+    # Parse output URI (now fully expanded)
+    try:
+        output_params = parse_copick_uri(output_uri, "segmentation")
+    except ValueError as e:
+        raise click.BadParameter(f"Invalid output URI: {e}") from e
+
+    output_user_id = output_params["user_id"]
+    output_session_id_template = output_params["session_id"]
+
+    logger.info(f"Skeletonizing segmentations '{segmentation_name}'")
+    logger.info(f"Source segmentations: {segmentation_user_id} matching pattern '{session_id_pattern}'")
+    logger.info(f"Method: {method}, output user ID: {output_user_id}")
+    logger.info(f"Preprocessing: remove_noise={remove_noise} (min_size={min_object_size})")
+    logger.info(f"Post-processing: remove_short_branches={remove_short_branches} (min_length={min_branch_length})")
+    logger.info(f"Output session ID template: '{output_session_id_template}'")
+
+    results = skeletonize_batch(
+        root=root,
+        segmentation_name=segmentation_name,
+        segmentation_user_id=segmentation_user_id,
+        session_id_pattern=session_id_pattern,
+        method=method,
+        remove_noise=remove_noise,
+        min_object_size=min_object_size,
+        remove_short_branches=remove_short_branches,
+        min_branch_length=min_branch_length,
+        output_session_id_template=output_session_id_template,
+        output_user_id=output_user_id,
+        run_names=run_names_list,
+        workers=workers,
+    )
+
+    successful = sum(1 for result in results.values() if result and result.get("processed", 0) > 0)
+    total_skeletons = sum(result.get("skeletons_created", 0) for result in results.values() if result)
+    total_processed = sum(result.get("segmentations_processed", 0) for result in results.values() if result)
+
+    logger.info(f"Completed: {successful}/{len(results)} runs processed successfully")
+    logger.info(f"Total segmentations processed: {total_processed}")
+    logger.info(f"Total skeletons created: {total_skeletons}")