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

copick_utils/cli/enclosed.py

@@ -0,0 +1,191 @@
+"""CLI command for enclosed segmentation operations (finding and absorbing enclosed components)."""
+
+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_dual_input_options, add_output_option, add_workers_option
+from copick_utils.util.config_models import create_dual_selector_config
+
+
+@click.command(
+    context_settings={"show_default": True},
+    short_help="Remove enclosed components from a segmentation.",
+    no_args_is_help=True,
+)
+@add_config_option
+@optgroup.group("\nInput Options", help="Options related to the input segmentations.")
+@optgroup.option(
+    "--run-names",
+    "-r",
+    multiple=True,
+    help="Specific run names to process (default: all runs).",
+)
+@add_dual_input_options("segmentation")
+@optgroup.group("\nTool Options", help="Options related to this tool.")
+@optgroup.option(
+    "--voxel-spacing",
+    "-vs",
+    type=float,
+    required=True,
+    help="Voxel spacing for input and output segmentations.",
+)
+@optgroup.option(
+    "--margin",
+    "-m",
+    type=int,
+    default=1,
+    help="Number of voxels to dilate when checking if components are enclosed.",
+)
+@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 consider (optional).",
+)
+@optgroup.option(
+    "--max-size",
+    type=float,
+    default=None,
+    help="Maximum component volume in cubic angstroms (ų) to consider (optional).",
+)
+@add_workers_option
+@optgroup.group("\nOutput Options", help="Options related to output segmentations.")
+@add_output_option("segmentation", default_tool="enclosed")
+@add_debug_option
+def enclosed(
+    config,
+    run_names,
+    input1_uri,
+    input2_uri,
+    voxel_spacing,
+    margin,
+    connectivity,
+    min_size,
+    max_size,
+    workers,
+    output_uri,
+    debug,
+):
+    """
+    Remove enclosed components from a segmentation.
+
+    This command identifies connected components in the first segmentation (inner) that are
+    completely surrounded by the second segmentation (outer), and removes them from the inner
+    segmentation. Useful for cleaning up noise, artifacts, or unwanted fragments.
+
+    \b
+    URI Format:
+        Segmentations: name:user_id/session_id (voxel spacing specified via --voxel-spacing)
+
+    \b
+    Algorithm:
+        1. Label connected components in the inner segmentation (input1)
+        2. Dilate each component by the specified margin
+        3. Check if the dilated component is fully contained within the outer segmentation (input2)
+        4. If enclosed (and within size limits), remove the component from the inner segmentation
+        5. Output cleaned version of the inner segmentation
+
+    \b
+    Examples:
+        # Remove small vesicle fragments that are enclosed by membrane
+        copick logical enclosed -vs 10.0 -i1 "vesicle:user1/auto-001" -i2 "membrane:user1/manual-001" -o "vesicle_clean"
+
+        # Remove noise fragments with size filtering (volumes in ų)
+        copick logical enclosed -vs 10.0 -i1 "fragments:user1/.*" -i2 "cell:user1/.*" -o "cleaned" --min-size 1000 --max-size 100000 --margin 2
+    """
+
+    logger = get_logger(__name__, debug=debug)
+
+    root = copick.from_file(config)
+    run_names_list = list(run_names) if run_names else None
+
+    # Append voxel spacing to URIs (only if not already present)
+    input1_uri_full = f"{input1_uri}@{voxel_spacing}" if "@" not in input1_uri else input1_uri
+    input2_uri_full = f"{input2_uri}@{voxel_spacing}" if "@" not in input2_uri else input2_uri
+    output_uri_full = f"{output_uri}@{voxel_spacing}" if "@" not in output_uri else output_uri
+
+    # Create config directly from URIs with smart defaults
+    try:
+        task_config = create_dual_selector_config(
+            input1_uri=input1_uri_full,
+            input2_uri=input2_uri_full,
+            input_type="segmentation",
+            output_uri=output_uri_full,
+            output_type="segmentation",
+            command_name="enclosed",
+        )
+    except ValueError as e:
+        raise click.BadParameter(str(e)) from e
+
+    # Extract parameters for logging
+    input1_params = parse_copick_uri(input1_uri, "segmentation")
+    input2_params = parse_copick_uri(input2_uri, "segmentation")
+    output_params = parse_copick_uri(output_uri_full, "segmentation")
+
+    logger.info(
+        f"Removing enclosed components from '{input1_params['name']}' using '{input2_params['name']}' as reference",
+    )
+    logger.info(f"Segmentation to clean: {input1_params['user_id']}/{input1_params['session_id']}")
+    logger.info(f"Reference segmentation: {input2_params['user_id']}/{input2_params['session_id']}")
+    logger.info(
+        f"Target segmentation template: {output_params['name']} ({output_params['user_id']}/{output_params['session_id']})",
+    )
+    logger.info(f"Parameters: margin={margin}, connectivity={connectivity}, min_size={min_size}, max_size={max_size}")
+
+    # Map connectivity string to numeric value
+    connectivity_map = {
+        "face": 1,
+        "face-edge": 2,
+        "all": 3,
+    }
+    connectivity_value = connectivity_map[connectivity]
+
+    # Import the lazy batch converter
+    from copick_utils.logical.enclosed_operations import segmentation_enclosed_lazy_batch
+
+    # Parallel discovery and processing
+    results = segmentation_enclosed_lazy_batch(
+        root=root,
+        config=task_config,
+        run_names=run_names_list,
+        workers=workers,
+        voxel_spacing=voxel_spacing,
+        margin=margin,
+        connectivity=connectivity_value,
+        min_size=min_size,
+        max_size=max_size,
+    )
+
+    successful = sum(1 for result in results.values() if result and result.get("processed", 0) > 0)
+    total_voxels_kept = sum(result.get("voxels_kept", 0) for result in results.values() if result)
+    total_processed = sum(result.get("processed", 0) for result in results.values() if result)
+    total_components_removed = sum(result.get("components_removed", 0) for result in results.values() if result)
+
+    # Collect all errors
+    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 enclosed operations completed: {total_processed}")
+    logger.info(f"Total components removed: {total_components_removed}")
+    logger.info(f"Total voxels remaining in cleaned segmentations: {total_voxels_kept}")
+
+    if all_errors:
+        logger.warning(f"Encountered {len(all_errors)} errors during processing")
+        for error in all_errors[:5]:  # Show first 5 errors
+            logger.warning(f"  - {error}")
+        if len(all_errors) > 5:
+            logger.warning(f"  ... and {len(all_errors) - 5} more errors")

copick_utils/cli/filter_components.py

@@ -0,0 +1,166 @@
+"""CLI command for filtering connected components by size."""
+
+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_input_option, add_output_option, add_workers_option
+
+
+@click.command(
+    context_settings={"show_default": True},
+    short_help="Filter connected components in segmentations by size.",
+    no_args_is_help=True,
+)
+@add_config_option
+@optgroup.group("\nInput Options", help="Options related to the input segmentation.")
+@optgroup.option(
+    "--run-names",
+    "-r",
+    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(
+    "--max-size",
+    type=float,
+    default=None,
+    help="Maximum component volume in cubic angstroms (ų) to keep (optional).",
+)
+@add_workers_option
+@optgroup.group("\nOutput Options", help="Options related to output segmentations.")
+@add_output_option("segmentation", default_tool="filter-components")
+@add_debug_option
+def filter_components(
+    config,
+    run_names,
+    input_uri,
+    connectivity,
+    min_size,
+    max_size,
+    workers,
+    output_uri,
+    debug,
+):
+    """
+    Filter connected components in segmentations by size.
+
+    This command identifies connected components in a segmentation and removes those
+    that fall outside the specified size range (in cubic angstroms). Useful for
+    removing noise, small artifacts, or overly large components.
+
+    \b
+    URI Format:
+        Segmentations: name:user_id/session_id@voxel_spacing
+
+    \b
+    Examples:
+        # Remove small noise components (keep only larger than 50000 ų)
+        copick process filter-components -i "membrane:user1/auto-001@10.0" -o "membrane_clean" --min-size 50000
+
+        # Keep only medium-sized components (between 10000 and 1000000 ų)
+        copick process filter-components -i "particles:user1/.*@10.0" -o "particles_filtered" --min-size 10000 --max-size 1000000
+
+        # Remove large components (keep only smaller than 500000 ų)
+        copick process filter-components -i "noise:user1/pred@10.0" -o "small_features" --max-size 500000
+    """
+
+    logger = get_logger(__name__, debug=debug)
+
+    root = copick.from_file(config)
+    run_names_list = list(run_names) if run_names else None
+
+    # 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"]
+    voxel_spacing = input_params.get("voxel_spacing")
+
+    if voxel_spacing is None:
+        raise click.BadParameter("Input URI must include voxel spacing (e.g., @10.0)")
+
+    # Parse output URI - if no voxel spacing specified, inherit from input
+    if "@" not in output_uri:
+        output_uri = f"{output_uri}@{voxel_spacing}"
+
+    try:
+        output_params = parse_copick_uri(output_uri, "segmentation")
+    except ValueError as e:
+        raise click.BadParameter(f"Invalid output URI: {e}") from e
+
+    output_name = output_params["name"]
+    output_user_id = output_params["user_id"]
+    output_session_id = output_params["session_id"]
+
+    logger.info(f"Filtering components for segmentation '{segmentation_name}'")
+    logger.info(f"Input segmentation: {segmentation_user_id}/{segmentation_session_id} @ {voxel_spacing}Å")
+    logger.info(f"Output segmentation: {output_name} ({output_user_id}/{output_session_id})")
+    logger.info(f"Connectivity: {connectivity}")
+    if min_size is not None:
+        logger.info(f"Minimum size: {min_size} ų")
+    if max_size is not None:
+        logger.info(f"Maximum size: {max_size} ų")
+
+    # Import batch function
+    from copick_utils.process.filter_components import filter_components_batch
+
+    # Process runs
+    results = filter_components_batch(
+        root=root,
+        segmentation_name=segmentation_name,
+        segmentation_user_id=segmentation_user_id,
+        segmentation_session_id=segmentation_session_id,
+        voxel_spacing=voxel_spacing,
+        connectivity=connectivity,
+        min_size=min_size,
+        max_size=max_size,
+        output_user_id=output_user_id,
+        output_session_id=output_session_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_kept = sum(result.get("components_kept", 0) for result in results.values() if result)
+    total_removed = sum(result.get("components_removed", 0) for result in results.values() if result)
+    total_voxels = sum(result.get("voxels_kept", 0) for result in results.values() if result)
+
+    # Collect all errors
+    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 components kept: {total_kept}")
+    logger.info(f"Total components removed: {total_removed}")
+    logger.info(f"Total voxels in filtered segmentations: {total_voxels}")
+
+    if all_errors:
+        logger.warning(f"Encountered {len(all_errors)} errors during processing")
+        for error in all_errors[:5]:  # Show first 5 errors
+            logger.warning(f"  - {error}")
+        if len(all_errors) > 5:
+            logger.warning(f"  ... and {len(all_errors) - 5} more errors")

copick_utils/cli/fit_spline.py

@@ -0,0 +1,191 @@
+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="Fit 3D splines to skeletons and generate picks with orientations.",
+    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.option(
+    "--voxel-spacing",
+    "-vs",
+    type=float,
+    required=True,
+    help="Voxel spacing for coordinate scaling.",
+)
+@optgroup.group("\nTool Options", help="Options related to this tool.")
+@optgroup.option(
+    "--spacing-distance",
+    type=float,
+    required=True,
+    help="Distance between consecutive sampled points along the spline.",
+)
+@optgroup.option(
+    "--smoothing-factor",
+    type=float,
+    help="Smoothing parameter for spline fitting (auto if not provided).",
+)
+@optgroup.option(
+    "--degree",
+    type=int,
+    default=3,
+    help="Degree of the spline (1-5).",
+)
+@optgroup.option(
+    "--connectivity-radius",
+    type=float,
+    default=2.0,
+    help="Maximum distance to consider skeleton points as connected.",
+)
+@optgroup.option(
+    "--compute-transforms/--no-compute-transforms",
+    is_flag=True,
+    default=True,
+    help="Whether to compute orientations for picks.",
+)
+@optgroup.option(
+    "--curvature-threshold",
+    type=float,
+    default=0.2,
+    help="Maximum allowed curvature before outlier removal.",
+)
+@optgroup.option(
+    "--max-iterations",
+    type=int,
+    default=5,
+    help="Maximum number of outlier removal iterations.",
+)
+@optgroup.option(
+    "--workers",
+    type=int,
+    default=8,
+    help="Number of worker processes.",
+)
+@optgroup.group("\nOutput Options", help="Options related to output picks.")
+@add_output_option("picks", default_tool="spline")
+@add_debug_option
+def fit_spline(
+    config,
+    run_names,
+    input_uri,
+    voxel_spacing,
+    spacing_distance,
+    smoothing_factor,
+    degree,
+    connectivity_radius,
+    compute_transforms,
+    curvature_threshold,
+    max_iterations,
+    workers,
+    output_uri,
+    debug,
+):
+    """Fit 3D splines to skeletonized segmentations and generate picks with orientations.
+
+    \b
+    URI Format:
+        Segmentations: name:user_id/session_id@voxel_spacing
+        Picks: object_name:user_id/session_id
+
+    \b
+    This command fits regularized 3D parametric splines to skeleton volumes and samples
+    points along the spline at regular intervals. Orientations are computed based on
+    the spline direction.
+
+    \b
+    Examples:
+        # Fit splines to skeletonized components
+        copick process fit_spline -i "skeleton:skel/inst-.*@10.0" -o "skeleton:spline/spline-{input_session_id}" --spacing-distance 4.4 --voxel-spacing 10.0
+
+        # Process specific skeleton
+        copick process fit_spline -i "skeleton:skel/skel-0@10.0" -o "skeleton:spline/spline-0" --spacing-distance 2.0 --voxel-spacing 10.0
+    """
+    from copick_utils.process.spline_fitting import fit_spline_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="picks",
+            command_name="fit_spline",
+            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, "picks")
+    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"Fitting splines to segmentations '{segmentation_name}'")
+    logger.info(f"Source segmentations: {segmentation_user_id} matching pattern '{session_id_pattern}'")
+    logger.info(f"Spacing distance: {spacing_distance}, degree: {degree}")
+    logger.info(f"Smoothing factor: {smoothing_factor}, connectivity radius: {connectivity_radius}")
+    logger.info(f"Compute transforms: {compute_transforms}, output user ID: {output_user_id}")
+    logger.info(f"Curvature threshold: {curvature_threshold}, max iterations: {max_iterations}")
+    logger.info(f"Voxel spacing: {voxel_spacing}")
+    logger.info(f"Output session ID template: '{output_session_id_template}'")
+
+    results = fit_spline_batch(
+        root=root,
+        segmentation_name=segmentation_name,
+        segmentation_user_id=segmentation_user_id,
+        session_id_pattern=session_id_pattern,
+        spacing_distance=spacing_distance,
+        smoothing_factor=smoothing_factor,
+        degree=degree,
+        connectivity_radius=connectivity_radius,
+        compute_transforms=compute_transforms,
+        curvature_threshold=curvature_threshold,
+        max_iterations=max_iterations,
+        output_session_id_template=output_session_id_template,
+        output_user_id=output_user_id,
+        voxel_spacing=voxel_spacing,
+        run_names=run_names_list,
+        workers=workers,
+    )
+
+    successful = sum(1 for result in results.values() if result and result.get("processed", 0) > 0)
+    total_picks = sum(result.get("picks_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 picks created: {total_picks}")

copick_utils/cli/hull.py

@@ -0,0 +1,138 @@
+"""CLI command for computing various hull operations on meshes."""
+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_input_option,
+    add_output_option,
+    add_workers_option,
+)
+from copick_utils.util.config_models import create_simple_config
+
+
+@click.command(
+    context_settings={"show_default": True},
+    short_help="Compute hull operations on meshes.",
+    no_args_is_help=True,
+)
+@add_config_option
+@optgroup.group("\nInput Options", help="Options related to the input meshes.")
+@optgroup.option(
+    "--run-names",
+    "-r",
+    multiple=True,
+    help="Specific run names to process (default: all runs).",
+)
+@add_input_option("mesh")
+@optgroup.group("\nTool Options", help="Options related to this tool.")
+@optgroup.option(
+    "--hull-type",
+    type=click.Choice(["convex"]),
+    default="convex",
+    help="Type of hull to compute.",
+)
+@add_workers_option
+@optgroup.group("\nOutput Options", help="Options related to output meshes.")
+@add_output_option("mesh", default_tool="hull")
+@optgroup.option(
+    "--individual-meshes/--no-individual-meshes",
+    "-im",
+    is_flag=True,
+    default=False,
+    help="Create individual meshes for each instance (enables {instance_id} placeholder).",
+)
+@add_debug_option
+def hull(
+    config,
+    run_names,
+    input_uri,
+    hull_type,
+    workers,
+    output_uri,
+    individual_meshes,
+    debug,
+):
+    """
+    Compute hull operations on meshes.
+
+    \b
+    URI Format:
+        Meshes: object_name:user_id/session_id
+
+    \b
+    Currently supports convex hull computation, where the convex hull is the
+    smallest convex shape that contains all vertices of the original mesh.
+
+    \b
+    Examples:
+        # Compute convex hull for meshes
+        copick process hull -i "membrane:user1/session1" -o "membrane:hull/hull-session"
+
+        # Process specific runs
+        copick process hull -r run1 -r run2 -i "membrane:user1/session1" -o "membrane:hull/convex-001" --hull-type convex
+    """
+    from copick_utils.process.hull import hull_lazy_batch
+
+    logger = get_logger(__name__, debug=debug)
+
+    root = copick.from_file(config)
+    run_names_list = list(run_names) if run_names else None
+
+    # Create config directly from URIs with smart defaults
+    try:
+        task_config = create_simple_config(
+            input_uri=input_uri,
+            input_type="mesh",
+            output_uri=output_uri,
+            output_type="mesh",
+            individual_outputs=individual_meshes,
+            command_name="hull",
+        )
+    except ValueError as e:
+        raise click.BadParameter(str(e)) from e
+
+    # Extract parameters for logging
+    input_params = parse_copick_uri(input_uri, "mesh")
+    output_params = parse_copick_uri(output_uri, "mesh")
+
+    logger.info(f"Computing {hull_type} hull for meshes '{input_params['object_name']}'")
+    logger.info(f"Source mesh pattern: {input_params['user_id']}/{input_params['session_id']}")
+    logger.info(
+        f"Target mesh template: {output_params['object_name']} ({output_params['user_id']}/{output_params['session_id']})",
+    )
+
+    # Parallel discovery and processing - no sequential bottleneck!
+    results = hull_lazy_batch(
+        root=root,
+        config=task_config,
+        run_names=run_names_list,
+        workers=workers,
+        hull_type=hull_type,
+    )
+
+    successful = sum(1 for result in results.values() if result and result.get("processed", 0) > 0)
+    total_vertices = sum(result.get("vertices_created", 0) for result in results.values() if result)
+    total_faces = sum(result.get("faces_created", 0) for result in results.values() if result)
+    total_processed = sum(result.get("processed", 0) for result in results.values() if result)
+
+    # Collect all errors
+    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 {hull_type} hull operations completed: {total_processed}")
+    logger.info(f"Total vertices created: {total_vertices}")
+    logger.info(f"Total faces created: {total_faces}")
+
+    if all_errors:
+        logger.warning(f"Encountered {len(all_errors)} errors during processing")
+        for error in all_errors[:5]:  # Show first 5 errors
+            logger.warning(f"  - {error}")
+        if len(all_errors) > 5:
+            logger.warning(f"  ... and {len(all_errors) - 5} more errors")