labelimage-tools 0.1.3__py3-none-any.whl

labelimage_tools/__init__.py

@@ -0,0 +1,117 @@
+"""Reusable utilities for 2-D labeled tissue segmentation images."""
+
+from .adjacency import (
+    adjacency_from_labels,
+    adjacency_pairs_from_labels,
+    adjacency_with_contact_from_labels,
+    adjacency_with_unique_from_labels,
+    border_labels,
+    centroids_from_labels,
+    get_centroids,
+    graph_from_labels,
+    label_is_border,
+    label_pixel_counts,
+)
+from .coloring import (
+    apply_color_lut_int,
+    color_planar_with_variety,
+    dsatur_color,
+    rebalance_K_colors,
+    refine_to_K_colors,
+    show_map_with_colors,
+)
+from .contours import ordered_contour_from_mask, ordered_contours_from_labels
+from .io import (
+    load_img,
+    load_label_graph,
+    load_label_image,
+    save_img,
+    save_label_graph,
+    save_label_graph_from_labels,
+    save_label_image,
+)
+from .junctions import (
+    Junction,
+    cluster_junctions_with_labels,
+    junction_pixels_with_labels,
+    junctions_from_labels,
+    merge_close_junctions,
+)
+from .plotting import (
+    draw_graph,
+    label_map,
+    plot_adjacency_graph,
+    plot_contours,
+    plot_junctions,
+    plot_label_boundaries,
+    plot_label_image,
+)
+from .preprocessing import (
+    crop_to_foreground_bbox,
+    dialate_labels,
+    dilate_labels,
+    erode_labels,
+    fill_internal_gaps_edt,
+    find_non_self_connected_labels,
+    load_image_pipeline,
+    remove_non_self_connected_bits,
+    shuffle_labels,
+    skeletonize_dilate,
+    skeletonize_erode,
+    skeletonize_labels,
+)
+from .validation import unique_labels, validate_label_image
+
+__all__ = [
+    "Junction",
+    "adjacency_from_labels",
+    "adjacency_pairs_from_labels",
+    "adjacency_with_contact_from_labels",
+    "adjacency_with_unique_from_labels",
+    "apply_color_lut_int",
+    "border_labels",
+    "centroids_from_labels",
+    "cluster_junctions_with_labels",
+    "color_planar_with_variety",
+    "crop_to_foreground_bbox",
+    "dialate_labels",
+    "dilate_labels",
+    "draw_graph",
+    "dsatur_color",
+    "erode_labels",
+    "fill_internal_gaps_edt",
+    "find_non_self_connected_labels",
+    "get_centroids",
+    "graph_from_labels",
+    "junction_pixels_with_labels",
+    "junctions_from_labels",
+    "label_is_border",
+    "label_pixel_counts",
+    "label_map",
+    "load_image_pipeline",
+    "load_img",
+    "load_label_graph",
+    "load_label_image",
+    "merge_close_junctions",
+    "ordered_contour_from_mask",
+    "ordered_contours_from_labels",
+    "plot_adjacency_graph",
+    "plot_contours",
+    "plot_junctions",
+    "plot_label_boundaries",
+    "plot_label_image",
+    "rebalance_K_colors",
+    "refine_to_K_colors",
+    "remove_non_self_connected_bits",
+    "save_label_graph",
+    "save_label_graph_from_labels",
+    "save_img",
+    "save_label_image",
+    "show_map_with_colors",
+    "shuffle_labels",
+    "skeletonize_dilate",
+    "skeletonize_erode",
+    "skeletonize_labels",
+    "unique_labels",
+    "validate_label_image",
+]

labelimage_tools/_bbox.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy import ndimage as ndi
+
+from .validation import unique_labels
+
+
+def _clip_padded_slice(
+    slc: tuple[slice, slice],
+    shape: tuple[int, ...],
+    padding: int,
+) -> tuple[slice, slice]:
+    """Pad a 2-D slice tuple, clipping the result to image bounds."""
+    return (
+        slice(max(0, slc[0].start - padding), min(shape[0], slc[0].stop + padding)),
+        slice(max(0, slc[1].start - padding), min(shape[1], slc[1].stop + padding)),
+    )
+
+
+def _slice_from_coords(coords: np.ndarray) -> tuple[slice, slice]:
+    """Build the tight 2-D bounding-box slice around coordinate rows."""
+    mins = coords.min(axis=0)
+    maxs = coords.max(axis=0) + 1
+    return (slice(int(mins[0]), int(maxs[0])), slice(int(mins[1]), int(maxs[1])))
+
+
+def _compact_problematic_labels(
+    labels: np.ndarray,
+    problematic: list[int],
+) -> tuple[np.ndarray, list[int]]:
+    """
+    Remap sparse/problematic labels to dense positive ids in one image pass.
+
+    ``ndi.find_objects`` is fast for dense positive labels, but cannot directly
+    handle negative labels or very large sparse labels without creating a huge
+    list. This helper creates a compact temporary image whose values are
+    ``1..M`` only where the original image contains one of the problematic
+    labels. The output order is sorted and mapped back by the caller.
+    """
+    sorted_labels = sorted(problematic)
+    lookup = np.asarray(sorted_labels, dtype=labels.dtype)
+    compact = np.zeros(labels.shape, dtype=np.int32)
+
+    indices = np.searchsorted(lookup, labels)
+    in_range = indices < lookup.size
+    matches = np.zeros(labels.shape, dtype=bool)
+    matches[in_range] = lookup[indices[in_range]] == labels[in_range]
+    compact[matches] = indices[matches] + 1
+    return compact, sorted_labels
+
+
+def label_slices(
+    labels,
+    *,
+    background=0,
+    include_background: bool = False,
+    padding: int = 0,
+    max_direct_label: int = 100_000,
+    max_manual_labels: int = 100,
+) -> dict[int, tuple[slice, slice]]:
+    """
+    Return global bounding-box slices for labels in a 2-D label image.
+
+    Parameters
+    ----------
+    labels : np.ndarray
+        2-D integer label image.
+    background : int, optional
+        Background label value. Default is ``0``.
+    include_background : bool, optional
+        If ``False`` (default), the background label is excluded. If ``True``,
+        the background is included when present in the image.
+    padding : int, optional
+        Number of pixels to add around each bounding box. Padding is clipped to
+        the image boundary.
+    max_direct_label : int, optional
+        Largest positive label handled by the direct ``ndi.find_objects`` fast
+        path. Larger labels are handled by the sparse-label fallback.
+    max_manual_labels : int, optional
+        Maximum number of sparse/problematic labels to handle with bounded
+        per-label scans. When there are more, labels are compacted in one pass
+        and processed with ``ndi.find_objects``.
+
+    Returns
+    -------
+    dict[int, tuple[slice, slice]]
+        Mapping from original label value to global ``(row_slice, col_slice)``.
+
+    Notes
+    -----
+    Ordinary positive labels use ``scipy.ndimage.find_objects`` directly. This
+    preserves the windowed design of the original tools, where expensive
+    per-label work happens only inside local crops. Negative labels, zero-valued
+    foreground labels, and very large sparse labels are still supported without
+    requiring a label-indexed list of length ``max_label + 1``.
+    """
+    labels = np.asarray(labels)
+    padding = int(padding)
+    max_direct_label = int(max_direct_label)
+    max_manual_labels = int(max_manual_labels)
+    if labels.ndim != 2:
+        raise ValueError("labels must be a 2-D array")
+    if padding < 0:
+        raise ValueError("padding must be non-negative")
+    if max_direct_label < 1:
+        raise ValueError("max_direct_label must be positive")
+    if max_manual_labels < 0:
+        raise ValueError("max_manual_labels must be non-negative")
+
+    values = [
+        int(label)
+        for label in unique_labels(
+            labels,
+            background=background,
+            include_background=include_background,
+        )
+    ]
+    if not values:
+        return {}
+
+    shape = labels.shape
+    slices: dict[int, tuple[slice, slice]] = {}
+
+    direct = [label for label in values if 0 < label <= max_direct_label]
+    problematic = [label for label in values if label <= 0 or label > max_direct_label]
+
+    if direct:
+        objects = ndi.find_objects(labels, max_label=max_direct_label)
+        for label in direct:
+            slc = objects[label - 1]
+            if slc is not None:
+                slices[label] = _clip_padded_slice(slc, shape, padding)
+
+    if len(problematic) <= max_manual_labels:
+        for label in problematic:
+            coords = np.argwhere(labels == label)
+            if coords.size:
+                slices[label] = _clip_padded_slice(_slice_from_coords(coords), shape, padding)
+    elif problematic:
+        compact, original_labels = _compact_problematic_labels(labels, problematic)
+        objects = ndi.find_objects(compact, max_label=len(original_labels))
+        for compact_id, label in enumerate(original_labels, start=1):
+            slc = objects[compact_id - 1]
+            if slc is not None:
+                slices[label] = _clip_padded_slice(slc, shape, padding)
+
+    return {label: slices[label] for label in values if label in slices}

labelimage_tools/_graph_io.py

@@ -0,0 +1,298 @@
+import json
+from collections import namedtuple
+from pathlib import Path
+
+import numpy as np
+
+from ._optional import optional_import
+from .typing import Cont, Neig
+
+LabelGraphData = namedtuple(
+    "LabelGraphData",
+    ["neighbors", "contacts", "centroids", "pixel_counts", "metadata"],
+)
+
+
+def _json_default(value):
+    if isinstance(value, np.integer):
+        return int(value)
+    if isinstance(value, np.floating):
+        return float(value)
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def _infer_graph_format(path, format: str) -> str:
+    fmt = format.lower()
+    if fmt != "auto":
+        if fmt not in {"npz", "json", "graphml", "gexf"}:
+            raise ValueError("format must be one of 'auto', 'npz', 'json', 'graphml', or 'gexf'")
+        return fmt
+    suffix = Path(path).suffix.lower()
+    if suffix == ".npz":
+        return "npz"
+    if suffix == ".json":
+        return "json"
+    if suffix == ".graphml":
+        return "graphml"
+    if suffix == ".gexf":
+        return "gexf"
+    raise ValueError(
+        "could not infer graph format from suffix; use .npz, .json, .graphml, or .gexf"
+    )
+
+
+def _graph_arrays(
+    neighbors: Neig,
+    *,
+    contacts: Cont | None = None,
+    centroids: dict[int, np.ndarray] | None = None,
+    pixel_counts: dict[int, int] | None = None,
+):
+    node_set = {int(label) for label in neighbors}
+    for nbrs in neighbors.values():
+        node_set.update(int(nbr) for nbr in np.asarray(nbrs).ravel())
+    if centroids is not None:
+        node_set.update(int(label) for label in centroids)
+    if pixel_counts is not None:
+        node_set.update(int(label) for label in pixel_counts)
+    nodes = np.asarray(sorted(node_set), dtype=np.int64)
+
+    edge_contacts: dict[tuple[int, int], float] = {}
+    edge_set: set[tuple[int, int]] = set()
+    for label, nbrs in neighbors.items():
+        label = int(label)
+        weights = contacts.get(label) if contacts is not None else None
+        if weights is None:
+            weights = [None] * len(nbrs)
+        for nbr, weight in zip(np.asarray(nbrs).ravel(), weights, strict=True):
+            edge = tuple(sorted((label, int(nbr))))
+            if edge[0] == edge[1]:
+                continue
+            edge_set.add(edge) # type: ignore (edge is 2-tuple of int, should be fine)
+            if contacts is not None and weight is not None:
+                edge_contacts.setdefault(edge, float(weight)) # type: ignore (edge is 2-tuple of int, should be fine)
+
+    edges = np.asarray(sorted(edge_set), dtype=np.int64).reshape(-1, 2)
+    contact_values = (
+        np.asarray([edge_contacts[tuple(edge)] for edge in edges], dtype=float)
+        if contacts is not None
+        else None
+    )
+    centroid_values = (
+        np.asarray(
+            [np.asarray(centroids.get(int(node), [np.nan, np.nan]), dtype=float) for node in nodes],
+            dtype=float,
+        )
+        if centroids is not None
+        else None
+    )
+    pixel_count_values = (
+        np.asarray([int(pixel_counts.get(int(node), 0)) for node in nodes], dtype=np.int64)
+        if pixel_counts is not None
+        else None
+    )
+    return nodes, edges, contact_values, centroid_values, pixel_count_values
+
+
+def _graph_from_arrays(
+    nodes,
+    edges,
+    *,
+    contacts=None,
+    centroids=None,
+    pixel_counts=None,
+):
+    neighbors_lists: dict[int, list[int]] = {int(node): [] for node in np.asarray(nodes).ravel()}
+    contact_lists: dict[int, list[float]] | None = (
+        {int(node): [] for node in np.asarray(nodes).ravel()} if contacts is not None else None
+    )
+    for idx, edge in enumerate(np.asarray(edges, dtype=np.int64).reshape(-1, 2)):
+        a, b = int(edge[0]), int(edge[1])
+        neighbors_lists.setdefault(a, []).append(b)
+        neighbors_lists.setdefault(b, []).append(a)
+        if contact_lists is not None:
+            weight = float(np.asarray(contacts, dtype=float)[idx])
+            contact_lists.setdefault(a, []).append(weight)
+            contact_lists.setdefault(b, []).append(weight)
+
+    neighbors = {
+        label: np.asarray(values, dtype=np.int64)
+        for label, values in neighbors_lists.items()
+    }
+    contact_map = (
+        {label: np.asarray(values, dtype=float) for label, values in contact_lists.items()}
+        if contact_lists is not None
+        else None
+    )
+    centroid_map = (
+        {
+            int(node): np.asarray(value, dtype=float)
+            for node, value in zip(nodes, centroids, strict=True)
+        }
+        if centroids is not None
+        else None
+    )
+    pixel_count_map = (
+        {int(node): int(value) for node, value in zip(nodes, pixel_counts, strict=True)}
+        if pixel_counts is not None
+        else None
+    )
+    return neighbors, contact_map, centroid_map, pixel_count_map
+
+
+def _json_dict_from_graph_data(neighbors, contacts, centroids, pixel_counts, metadata):
+    nodes, edges, contact_values, _, _ = _graph_arrays(
+        neighbors,
+        contacts=contacts,
+        centroids=centroids,
+        pixel_counts=pixel_counts,
+    )
+    node_items = []
+    for node in nodes:
+        item = {"id": int(node)}
+        if centroids is not None and int(node) in centroids:
+            item["centroid"] = np.asarray(centroids[int(node)], dtype=float).tolist()
+        if pixel_counts is not None and int(node) in pixel_counts:
+            item["pixel_count"] = int(pixel_counts[int(node)])
+        node_items.append(item)
+    edge_items = []
+    for idx, edge in enumerate(edges):
+        item = {"source": int(edge[0]), "target": int(edge[1])}
+        if contact_values is not None:
+            contact = float(contact_values[idx])
+            item["contact"] = contact # type: ignore (contact is types ad float for flexibility, should be fine)
+            item["weight"] = contact # type: ignore (contact is types ad float for flexibility, should be fine)
+        edge_items.append(item)
+    return {"nodes": node_items, "edges": edge_items, "metadata": dict(metadata)}
+
+
+def _graph_data_from_json_dict(data):
+    nodes = np.asarray([int(node["id"]) for node in data.get("nodes", [])], dtype=np.int64)
+    edges = np.asarray(
+        [[int(edge["source"]), int(edge["target"])] for edge in data.get("edges", [])],
+        dtype=np.int64,
+    ).reshape(-1, 2)
+    has_contacts = any("contact" in edge for edge in data.get("edges", []))
+    contacts = (
+        np.asarray([float(edge.get("contact", edge.get("weight", 1.0))) for edge in data["edges"]])
+        if has_contacts
+        else None
+    )
+    has_centroids = any("centroid" in node for node in data.get("nodes", []))
+    centroids = (
+        np.asarray([node.get("centroid", [np.nan, np.nan]) for node in data["nodes"]], dtype=float)
+        if has_centroids
+        else None
+    )
+    has_pixel_counts = any("pixel_count" in node for node in data.get("nodes", []))
+    pixel_counts = (
+        np.asarray([int(node.get("pixel_count", 0)) for node in data["nodes"]], dtype=np.int64)
+        if has_pixel_counts
+        else None
+    )
+    neighbors, contact_map, centroid_map, pixel_count_map = _graph_from_arrays(
+        nodes,
+        edges,
+        contacts=contacts,
+        centroids=centroids,
+        pixel_counts=pixel_counts,
+    )
+    return LabelGraphData(
+        neighbors,
+        contact_map,
+        centroid_map,
+        pixel_count_map,
+        dict(data.get("metadata", {})),
+    )
+
+
+def _graph_to_networkx(neighbors, contacts=None, centroids=None, pixel_counts=None, metadata=None):
+    nx = optional_import(
+        "networkx",
+        extra="graph-standard",
+        feature="GraphML/GEXF graph I/O",
+        package_name="networkx",
+    )
+    graph = nx.Graph()
+    nodes, edges, contact_values, _, _ = _graph_arrays(
+        neighbors,
+        contacts=contacts,
+        centroids=centroids,
+        pixel_counts=pixel_counts,
+    )
+    for node in nodes:
+        attrs = {}
+        if centroids is not None and int(node) in centroids:
+            cy, cx = np.asarray(centroids[int(node)], dtype=float)
+            attrs.update({"centroid_y": float(cy), "centroid_x": float(cx)})
+        if pixel_counts is not None and int(node) in pixel_counts:
+            attrs["pixel_count"] = int(pixel_counts[int(node)])
+        graph.add_node(str(int(node)), **attrs)
+    for idx, edge in enumerate(edges):
+        attrs = {}
+        if contact_values is not None:
+            contact = float(contact_values[idx])
+            attrs.update({"contact": contact, "weight": contact})
+        graph.add_edge(str(int(edge[0])), str(int(edge[1])), **attrs)
+    if metadata:
+        graph.graph["metadata"] = json.dumps(metadata, default=_json_default)
+    return graph
+
+
+def _graph_from_networkx(graph):
+    nodes = np.asarray([int(node) for node in graph.nodes], dtype=np.int64)
+    edges = np.asarray([[int(a), int(b)] for a, b in graph.edges], dtype=np.int64).reshape(-1, 2)
+    has_contacts = any(
+        "contact" in data or "weight" in data
+        for _, _, data in graph.edges(data=True)
+    )
+    contacts = (
+        np.asarray(
+            [
+                float(data.get("contact", data.get("weight", 1.0)))
+                for _, _, data in graph.edges(data=True)
+            ],
+            dtype=float,
+        )
+        if has_contacts
+        else None
+    )
+    has_centroids = any(
+        "centroid_y" in data and "centroid_x" in data
+        for _, data in graph.nodes(data=True)
+    )
+    centroids = (
+        np.asarray(
+            [
+                [float(data.get("centroid_y", np.nan)), float(data.get("centroid_x", np.nan))]
+                for _, data in graph.nodes(data=True)
+            ],
+            dtype=float,
+        )
+        if has_centroids
+        else None
+    )
+    has_pixel_counts = any("pixel_count" in data for _, data in graph.nodes(data=True))
+    pixel_counts = (
+        np.asarray(
+            [int(data.get("pixel_count", 0)) for _, data in graph.nodes(data=True)],
+            dtype=np.int64,
+        )
+        if has_pixel_counts
+        else None
+    )
+    metadata_raw = graph.graph.get("metadata", "{}")
+    try:
+        metadata = json.loads(metadata_raw)
+    except TypeError:
+        metadata = {}
+    neighbors, contact_map, centroid_map, pixel_count_map = _graph_from_arrays(
+        nodes,
+        edges,
+        contacts=contacts,
+        centroids=centroids,
+        pixel_counts=pixel_counts,
+    )
+    return LabelGraphData(neighbors, contact_map, centroid_map, pixel_count_map, metadata)

labelimage_tools/_optional.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+
+def optional_import(
+    module_name: str,
+    *,
+    extra: str,
+    feature: str,
+    package_name: str | None = None,
+) -> Any:
+    """Import an optional dependency or raise a clear installation hint."""
+    display_name = package_name or module_name
+    try:
+        return import_module(module_name)
+    except ImportError as exc:
+        install_hint = f"`pip install labelimage-tools[{extra}]`"
+        if extra != "all":
+            install_hint += " or `pip install labelimage-tools[all]`"
+        raise ImportError(
+            f"{feature} requires the optional dependency `{display_name}`. "
+            f"Install it with {install_hint} "
+            f"or install `{display_name}` directly."
+        ) from exc