microeye 2.4.62__tar.gz → 2.4.63__tar.gz

{microeye-2.4.62/src/microeye.egg-info → microeye-2.4.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microeye
-Version: 2.4.62
+Version: 2.4.63
 Summary: A python toolkit for fluorescence microscopy         that features hardware control, data analysis and vizualization         for super-resolution single-molecule localization microscopy and         single-partical tracking.
 Home-page: https://github.com/samhitech/microEye
 Author: Mohammad Nour Alsamsam
@@ -14,6 +14,7 @@ Requires-Python: >=3.9.4, <3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: autopep8==2.3.2
+Requires-Dist: cupy-cuda13x==14.2.0
 Requires-Dist: dask==2025.9.1
 Requires-Dist: h5py==3.15.0
 Requires-Dist: hdbscan==0.8.44
@@ -22,6 +23,7 @@ Requires-Dist: ids-peak==1.11.1.0.5
 Requires-Dist: matplotlib==3.10.7
 Requires-Dist: mmpycorex==0.3.16
 Requires-Dist: numba==0.62.1
+Requires-Dist: numba-cuda==0.30.4
 Requires-Dist: numpy==2.2.6
 Requires-Dist: ome_types==0.5.2
 Requires-Dist: opencv_python==4.12.0.88
@@ -69,11 +71,15 @@ Dynamic: summary
 <!-- ![microEye](https://github.com/samhitech/microEye/assets/89871015/37ca0859-0b4b-402d-8652-9a01d0bf0f29) -->
 
 ```bash
-   __  ____              ____                ___  ____  ____ ___ 
-  /  |/  (_)__________  / __/_ _____   _  __|_  |/ / / / __/|_  |
- / /|_/ / / __/ __/ _ \/ _// // / -_) | |/ / __//_  _// _ \/ __/ 
-/_/  /_/_/\__/_/  \___/___/\_, /\__/  |___/____(_)_/(_)___/____/ 
-                          /___/  
+╭─────────────────────────────────────────────────────────────────────╮
+│                                                                     │
+│     __  ____              ____                ___  ____  ____ ____  │
+│    /  |/  (_)__________  / __/_ _____   _  __|_  |/ / / / __/|_  /  │
+│   / /|_/ / / __/ __/ _ \/ _// // / -_) | |/ / __//_  _// _ \_/_ <   │
+│  /_/  /_/_/\__/_/  \___/___/\_, /\__/  |___/____(_)_/(_)___/____/   │
+│                            /___/                                    │
+│                                                                     │
+╰─────────────────────────────────────────────────────────────────────╯
 ```
 
 The **`microEye`** is a Python toolkit for fluorescence microscopy that supports super-resolution single-molecule localization microscopy and single-particle tracking. It features hardware control, data analysis, and visualization.
@@ -597,6 +603,18 @@ Special thanks to the following projects and libraries that make this work possi
 
   > _Martens et al., “Temporal analysis of relative distances (TARDIS) is a robust, parameter-free alternative to single-particle tracking”, Nature Methods (2024). [Article](https://rdcu.be/dv1sr)_
 
+- **RCC (Robust Cross-Correlation)**: We have implemented the RCC algorithm in Python for drift correction in SMLM data.
+  
+  > _Y. Wang, J. Schnitzbauer, Z. Hu, X. Li, Y. Cheng, Z.-L. Huang, and B. Huang, “Localization events-based sample drift correction for localization microscopy with redundant cross-correlation algorithm,” Opt. Express 22(13), 15982 (2014)._ [Paper](https://doi.org/10.1364/OE.22.015982) [GitHub](https://github.com/yinawang28/RCC)
+
+- **AIM (Adaptive Intersection Maximization)**: We have implemented the AIM algorithm in Python for drift correction in SMLM data.
+  
+  > _H. Ma, M. Chen, P. Nguyen, and Y. Liu, “Toward drift-free high-throughput nanoscopy through adaptive intersection maximization,” Sci. Adv. 10(21), eadm7765 (2024)._ [Paper](www.science.org/doi/10.1126/sciadv.adm7765) [GitHub](https://github.com/YangLiuLab/AIM)
+
+- **COMET (Cost-function Optimized Maximal overlap drift EsTimation)**: We have implemented the COMET algorithm in Python for drift correction in SMLM data.
+
+  > _L. Reinkensmeier, S. Aufmkolk, I. Farabella, A. Egner, and M. Bates, “Cost-function Optimized Maximal Overlap Drift Estimation for Single Molecule Localization Microscopy,” (2026)._ [Paper](https://doi.org/10.64898/2026.03.27.714864) [GitHub](https://github.com/gpufit/Comet/tree/master)
+
 > [!IMPORTANT]
 > **Disclaimer**
 > _I'm committed to maintaining an accurate acknowledgment list for our project. However, if I inadvertently miss acknowledging your work, please don't hesitate to reach out to us. I appreciate your understanding, and I'm doing my best to manage all acknowledgments amidst my other responsibilities._

{microeye-2.4.62 → microeye-2.4.63}/README.md

@@ -3,11 +3,15 @@
 <!-- ![microEye](https://github.com/samhitech/microEye/assets/89871015/37ca0859-0b4b-402d-8652-9a01d0bf0f29) -->
 
 ```bash
-   __  ____              ____                ___  ____  ____ ___ 
-  /  |/  (_)__________  / __/_ _____   _  __|_  |/ / / / __/|_  |
- / /|_/ / / __/ __/ _ \/ _// // / -_) | |/ / __//_  _// _ \/ __/ 
-/_/  /_/_/\__/_/  \___/___/\_, /\__/  |___/____(_)_/(_)___/____/ 
-                          /___/  
+╭─────────────────────────────────────────────────────────────────────╮
+│                                                                     │
+│     __  ____              ____                ___  ____  ____ ____  │
+│    /  |/  (_)__________  / __/_ _____   _  __|_  |/ / / / __/|_  /  │
+│   / /|_/ / / __/ __/ _ \/ _// // / -_) | |/ / __//_  _// _ \_/_ <   │
+│  /_/  /_/_/\__/_/  \___/___/\_, /\__/  |___/____(_)_/(_)___/____/   │
+│                            /___/                                    │
+│                                                                     │
+╰─────────────────────────────────────────────────────────────────────╯
 ```
 
 The **`microEye`** is a Python toolkit for fluorescence microscopy that supports super-resolution single-molecule localization microscopy and single-particle tracking. It features hardware control, data analysis, and visualization.
@@ -531,6 +535,18 @@ Special thanks to the following projects and libraries that make this work possi
 
   > _Martens et al., “Temporal analysis of relative distances (TARDIS) is a robust, parameter-free alternative to single-particle tracking”, Nature Methods (2024). [Article](https://rdcu.be/dv1sr)_
 
+- **RCC (Robust Cross-Correlation)**: We have implemented the RCC algorithm in Python for drift correction in SMLM data.
+  
+  > _Y. Wang, J. Schnitzbauer, Z. Hu, X. Li, Y. Cheng, Z.-L. Huang, and B. Huang, “Localization events-based sample drift correction for localization microscopy with redundant cross-correlation algorithm,” Opt. Express 22(13), 15982 (2014)._ [Paper](https://doi.org/10.1364/OE.22.015982) [GitHub](https://github.com/yinawang28/RCC)
+
+- **AIM (Adaptive Intersection Maximization)**: We have implemented the AIM algorithm in Python for drift correction in SMLM data.
+  
+  > _H. Ma, M. Chen, P. Nguyen, and Y. Liu, “Toward drift-free high-throughput nanoscopy through adaptive intersection maximization,” Sci. Adv. 10(21), eadm7765 (2024)._ [Paper](www.science.org/doi/10.1126/sciadv.adm7765) [GitHub](https://github.com/YangLiuLab/AIM)
+
+- **COMET (Cost-function Optimized Maximal overlap drift EsTimation)**: We have implemented the COMET algorithm in Python for drift correction in SMLM data.
+
+  > _L. Reinkensmeier, S. Aufmkolk, I. Farabella, A. Egner, and M. Bates, “Cost-function Optimized Maximal Overlap Drift Estimation for Single Molecule Localization Microscopy,” (2026)._ [Paper](https://doi.org/10.64898/2026.03.27.714864) [GitHub](https://github.com/gpufit/Comet/tree/master)
+
 > [!IMPORTANT]
 > **Disclaimer**
 > _I'm committed to maintaining an accurate acknowledgment list for our project. However, if I inadvertently miss acknowledging your work, please don't hesitate to reach out to us. I appreciate your understanding, and I'm doing my best to manage all acknowledgments amidst my other responsibilities._

{microeye-2.4.62 → microeye-2.4.63}/src/microEye/__init__.py

@@ -1,7 +1,12 @@
+import argparse
 import importlib.util
 import logging
 import os
 
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.traceback import install
+
 from microEye._version import __version__, version_info
 
 # QT bindings affect camera libraries' DLL loading.
@@ -11,6 +16,8 @@ from microEye.hardware import cams
 
 PREFERRED_QT_APIS = ('PySide6', 'PyQt6', 'PyQt5')
 
+HELP_MESSAGE = ''
+
 
 def _select_qt_api(cli_choice: str | None) -> str:
     candidates = (cli_choice,) + PREFERRED_QT_APIS if cli_choice else PREFERRED_QT_APIS
@@ -23,11 +30,16 @@ def _select_qt_api(cli_choice: str | None) -> str:
 
 
 def getArgs():
-    import argparse
     import os
+    import re
     import sys
 
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        add_help=False,
+    )
+    parser.add_argument(
+        '-h', '--help', action='store_true', help='Show this help message and exit.'
+    )
     parser.add_argument(
         '--module',
         help='The module to launch [mieye|viewer], '
@@ -63,6 +75,34 @@ def getArgs():
         action='store_true',
     )
 
+    lines = []
+    for line in parser.format_help().splitlines():
+        # format flags (cyan)
+        line = re.sub(r'(?<=\s|\[)(-\S+)', r'[bold #00d7ff]\1[/bold #00d7ff]', line)
+        line = re.sub(r'(?<=\s|\[)(--\S+)', r'[bold #00d7ff]\1[/bold #00d7ff]', line)
+
+        # format scripts & files (warm yellow)
+        line = re.sub(r'(?<=\s)(\S+\.py)', r'[#ffb86c]\1[/#ffb86c]', line)
+        line = re.sub(r'(?<=\s)(\S+\.exe)', r'[#ffb86c]\1[/#ffb86c]', line)
+        line = re.sub(r'(?<=\s)(\S+\.dll)', r'[#ffb86c]\1[/#ffb86c]', line)
+        line = re.sub(r'(?<=\s)(\S+\.so)', r'[#ffb86c]\1[/#ffb86c]', line)
+        line = re.sub(r'(?<=\s)(\S+\.dylib)', r'[#ffb86c]\1[/#ffb86c]', line)
+
+        # format curly braces (bright green)
+        line = re.sub(r'(?<=\s)(\{.*?\})', r'[bold #5af78e]\1[/bold #5af78e]', line)
+
+        # format flags within brackets (cyan)
+        line = re.sub(r'(?<=\[)(--\S+)', r'[bold #00d7ff]\1[/bold #00d7ff]', line)
+        line = re.sub(r'(?<=\[)(-\S+)', r'[bold #00d7ff]\1[/bold #00d7ff]', line)
+
+        line = line.replace('usage:', '[bold #dcdcaa]usage:[/bold #dcdcaa]')
+        line = line.replace('options:', '[bold #dcdcaa]options:[/bold #dcdcaa]')
+
+        lines.append(line)
+
+    global HELP_MESSAGE
+    HELP_MESSAGE = '\n'.join(lines) + '\n'
+
     args, _ = parser.parse_known_args(sys.argv)
 
     # access the parsed arguments
@@ -75,6 +115,7 @@ def getArgs():
 
     return args
 
+
 def configure_logger(args):
     import os
     import sys
@@ -93,15 +134,31 @@ def configure_logger(args):
         and args.module
     ):
         os.makedirs(os.path.dirname(log_filename))
+
+    if not args.no_log_file and args.module:
+        console = Console(
+            file=open(log_filename, 'a', encoding='utf-8')  # noqa: SIM115, W291
+        )
+        file_handler = RichHandler(
+                        console=console,
+                        rich_tracebacks=True,
+                        tracebacks_show_locals=True,
+                        markup=True,
+                    )
+    else:
+        file_handler = logging.NullHandler()
+
     # set the logging configuration with both file and console handlers
     logging.basicConfig(
         level=level,
-        format='%(asctime)s | %(name)s | %(levelname)s | %(message)s',
+        format='%(message)s',
         handlers=[
-            logging.FileHandler(log_filename)
-            if not args.no_log_file and args.module
-            else logging.NullHandler(),
-            logging.StreamHandler(sys.stdout)
+            file_handler,
+            RichHandler(
+                rich_tracebacks=True,
+                tracebacks_show_locals=True,
+                markup=True,
+            )
             if not args.no_log_console
             else logging.NullHandler(),
         ],
@@ -110,5 +167,10 @@ def configure_logger(args):
     logging.getLogger().debug('Log level set to %s', level_name)
 
 
-
+install(
+    show_locals=False,
+    code_width=150,
+    width=200,
+    extra_lines=2,
+)
 ARGS = getArgs()

{microeye-2.4.62 → microeye-2.4.63}/src/microEye/_version.py

@@ -1,2 +1,2 @@
-version_info = (2, 4, 62)
+version_info = (2, 4, 63)
 __version__ = '.'.join(map(str, version_info))

microeye-2.4.62/src/microEye/analysis/clustering/dbscan.py → microeye-2.4.63/src/microEye/analysis/clustering/core.py

@@ -1,33 +1,17 @@
 import logging
-from dataclasses import dataclass
-from enum import Enum
 
 import numba as nb
 import numpy as np
 from hdbscan import HDBSCAN
-from scipy.spatial import ConvexHull, Delaunay, Voronoi
 from sklearn.cluster import DBSCAN, OPTICS, cluster_optics_dbscan
-from sklearn.preprocessing import StandardScaler
-
-logger = logging.getLogger(__name__)
 
+from microEye.analysis.clustering.dataclasses import (
+    CenteringMode,
+    CenteringOptions,
+    ClusterCenterResult,
+)
 
-@nb.njit(cache=True)
-def geometric_median(points, max_iter=128, tol=1e-6, eps=1e-12):
-    guess = np.median(points, axis=0)
-    for _ in range(max_iter):
-        try:
-            deltas = points - guess
-            distances = np.linalg.norm(deltas, axis=1)
-            weights = 1.0 / np.maximum(distances, eps)
-            new_guess = np.sum(points * weights[:, None], axis=0) / np.sum(weights)
-            if np.linalg.norm(new_guess - guess) < tol:
-                return new_guess
-            guess = new_guess
-        except Exception as e:
-            logger.error(f'Error in geometric_median: {e}')
-            break
-    return guess
+logger = logging.getLogger(__name__)
 
 
 @nb.njit(fastmath=True, cache=True)
@@ -159,11 +143,16 @@ def huber_center(points, delta=2.0, max_iter=64, tol=1e-5):
     return guess
 
 
-class CenteringMode(Enum):
-    CRLB_WEIGHTED_MEAN = 'crlb_weighted_mean'
-    MEAN = 'mean'
-    GEOMETRIC_MEDIAN = 'geometric_median'
-    HUBER_CENTER = 'huber_center'
+def scale_data(x, y, z, sigma_xy=10.0, sigma_z=10.0):
+    '''
+    Scales the input coordinates for clustering algorithms
+     that require isotropic distances.
+    '''
+    if z is None:
+        return np.column_stack((x, y)), 1.0
+    else:
+        scale = sigma_xy / sigma_z
+        return np.column_stack((x, y, z * scale)), scale
 
 
 def get_center(
@@ -178,13 +167,14 @@ def get_center(
     '''
     Computes the center of clusters based on the specified centering mode.
 
-    *Methods*
+    **Methods**
 
-    - CRLB_WEIGHTED_MEAN: Computes the center using a weighted mean based on the
+    - **_CRLB_WEIGHTED_MEAN_**: Computes the center using a weighted mean based on the
     Cramer-Rao Lower Bound (CRLB) variances for x and y coordinates.
-    - GEOMETRIC_MEDIAN: Computes the center as the geometric median of the points.
-    - HUBER_CENTER: Computes the center using M-estimation with a Huber loss function.
-    - MEAN: Computes the center as the arithmetic mean of the points.
+    - **_GEOMETRIC_MEDIAN_**: Computes the center as the geometric median of the points.
+    - **_HUBER_CENTER_**: Computes the center using
+       M-estimation with a Huber loss function.
+    - **_MEAN_**: Computes the center as the arithmetic mean of the points.
 
     Parameters
     -----------
@@ -261,24 +251,6 @@ def get_center(
     return mu_x, mu_y, mu_z, sigma_com
 
 
-@dataclass
-class ClusterCenterResult:
-    x: np.ndarray
-    y: np.ndarray
-    z: np.ndarray | None
-    labels: np.ndarray
-    intensity: np.ndarray | None
-    crlb_x: np.ndarray | None
-    crlb_y: np.ndarray | None
-    cx: np.ndarray
-    cy: np.ndarray
-    cz: np.ndarray | None
-    c_sigma: np.ndarray | None
-    c_label: np.ndarray
-    n_points: np.ndarray
-    rejected: int
-
-
 def get_centers(
     x: np.ndarray,
     y: np.ndarray,
@@ -287,14 +259,19 @@ def get_centers(
     intensity: np.ndarray | None = None,
     crlb_x: np.ndarray | None = None,
     crlb_y: np.ndarray | None = None,
-    center_mode: CenteringMode = CenteringMode.CRLB_WEIGHTED_MEAN,
-    eps: float = 1e-12,
-    rejection_threshold: float | None = None,
-    min_points: int | None = None,
-    max_points: int | None = None,
-    subtract_com: bool = False,
-    **kwargs,
+    options: CenteringOptions | None = None,
 ) -> ClusterCenterResult | None:
+    if options is None:
+        options = CenteringOptions()
+
+    rejection_threshold = options.rejection_threshold or None
+    min_points = (
+        options.min_points
+        or (options.min_points is not None and options.min_points > 1)
+        or None
+    )
+    max_points = options.max_points or None
+
     try:
         # Filter out noise (label < 0) safely
         valid_mask = labels >= 0
@@ -353,10 +330,10 @@ def get_centers(
                 x_cluster,
                 y_cluster,
                 z_cluster,
-                center_mode=center_mode,
+                center_mode=options.center_mode,
                 crlb_x=crlb_x[s] if crlb_x is not None else None,
                 crlb_y=crlb_y[s] if crlb_y is not None else None,
-                eps=eps,
+                eps=options.eps,
             )
 
             # Reject clusters with large uncertainty
@@ -376,7 +353,7 @@ def get_centers(
             c_labels.append(i)
             n_points.append(len(x_cluster))
 
-            if subtract_com:
+            if options.subtract_com:
                 x[s] -= mu_x
                 y[s] -= mu_y
                 if z is not None:
@@ -419,14 +396,6 @@ def get_centers(
         return None
 
 
-def scale_data(x, y, z, sigma_xy=10.0, sigma_z=10.0):
-    if z is None:
-        return np.column_stack((x, y)), 1.0
-    else:
-        scale = sigma_xy / sigma_z
-        return np.column_stack((x, y, z * scale)), scale
-
-
 def perform_dbscan_clustering(X, Y, Z, eps=50, min_samples=2, **kwargs):
     '''
     Performs DBSCAN clustering on 3D localization data.
@@ -456,7 +425,10 @@ def perform_dbscan_clustering(X, Y, Z, eps=50, min_samples=2, **kwargs):
         else:
             logger.warning('Standard deviation of data is zero. Skipping scaling.')
 
-    dbscan_model = DBSCAN(eps=eps, min_samples=min_samples, **kwargs)
+    # remove any not need kwargs that are not relevant to DBSCAN
+    relevant_kwargs = {k: v for k, v in kwargs.items() if k in DBSCAN().get_params()}
+
+    dbscan_model = DBSCAN(eps=eps, min_samples=min_samples, **relevant_kwargs)
     dbscan_model.fit(VECTORS)
 
     labels = dbscan_model.labels_
@@ -483,6 +455,10 @@ def perform_hdbscan_clustering(X, Y, Z, **kwargs):
     '''
     sigma_xy = kwargs.pop('sigma_xy', 10.0)
     sigma_z = kwargs.pop('sigma_z', 10.0)
+    min_samples = kwargs.pop('min_samples', None)
+    min_samples = min_samples or (min_samples is not None and min_samples > 0) or None
+    if min_samples:
+        kwargs['min_samples'] = min_samples
 
     VECTORS, scale = scale_data(X, Y, Z, sigma_xy, sigma_z)
 
@@ -544,6 +520,9 @@ def perform_optics_clustering(X, Y, Z, min_samples=10, xi=0.05, **kwargs):
     '''
     sigma_xy = kwargs.pop('sigma_xy', 10.0)
     sigma_z = kwargs.pop('sigma_z', 10.0)
+    max_eps = kwargs.pop('max_eps', np.inf)
+    max_eps = max_eps or (max_eps is not None and max_eps > 0) or np.inf
+    kwargs['max_eps'] = max_eps
 
     VECTORS, scale = scale_data(X, Y, Z, sigma_xy, sigma_z)
 

microeye-2.4.63/src/microEye/analysis/clustering/dataclasses.py

@@ -0,0 +1,212 @@
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+
+import numpy as np
+import pyqtgraph as pg
+
+from microEye.analysis.rendering.base import RenderModes
+
+
+class CenteringMode(StrEnum):
+    CRLB_WEIGHTED_MEAN = 'crlb_weighted_mean'
+    MEAN = 'mean'
+    GEOMETRIC_MEDIAN = 'geometric_median'
+    HUBER_CENTER = 'huber_center'
+
+
+@dataclass
+class CenteringOptions:
+    center_mode: CenteringMode = CenteringMode.CRLB_WEIGHTED_MEAN
+    eps: float = 1e-12
+    rejection_threshold: float | None = None
+    min_points: int | None = None
+    max_points: int | None = None
+    subtract_com: bool = False
+
+    def __post_init__(self):
+        if isinstance(self.center_mode, str):
+            self.center_mode = CenteringMode(self.center_mode)
+
+
+@dataclass
+class ClusterCenterResult:
+    x: np.ndarray
+    y: np.ndarray
+    z: np.ndarray | None
+    labels: np.ndarray
+    intensity: np.ndarray | None
+    crlb_x: np.ndarray | None
+    crlb_y: np.ndarray | None
+    cx: np.ndarray
+    cy: np.ndarray
+    cz: np.ndarray | None
+    c_sigma: np.ndarray | None
+    c_label: np.ndarray
+    n_points: np.ndarray
+    rejected: int
+
+
+@dataclass
+class ClusteringOptions:
+    grouping_method: str = 'dbscan'
+    distance_threshold: float | None = None
+    sigma_xy: float = 15.0
+    sigma_z: float = 45.0
+    scale_data: bool = False
+    xi : float = 0.05
+
+
+@dataclass
+class RenderOptions:
+    mode: str = 'superimposed'
+    rasterized: bool = True
+    render_mode: RenderModes = RenderModes.HISTOGRAM
+    pixel_size: float = 1.0
+    extent: float = 200.0
+    scalebar_length: float = 80.0
+
+    def __post_init__(self):
+        if isinstance(self.render_mode, int):
+            self.render_mode = RenderModes(self.render_mode)
+
+
+@dataclass
+class RunOptions:
+    clustering: ClusteringOptions
+    rendering: RenderOptions
+    model: dict
+    export: dict
+
+    def __post_init__(self):
+        if isinstance(self.clustering, dict):
+            self.clustering = ClusteringOptions(**self.clustering)
+        if isinstance(self.rendering, dict):
+            self.rendering = RenderOptions(**self.rendering)
+
+
+@dataclass
+class FitResult:
+    '''Generic outcome of fitting ANY geometric model to a candidate site set.'''
+
+    R: np.ndarray
+    '''
+    The rotation matrix that transforms the raw coordinates into the canonical frame.
+    '''
+    origin: np.ndarray
+    '''
+    The origin of the canonical frame, expressed in raw coordinates.
+    '''
+    inlier_mask: np.ndarray
+    '''
+    A boolean array (K,) indicating which input sites were used in the fit.
+    '''
+    indices: np.ndarray
+    '''
+    The integer indices (n_inliers, d) of the canonical positions
+    corresponding to each inlier site.
+
+    Examples:
+    - For a ruler, d=1 and the indices are the slot numbers.
+    - For a grid, d=2 and the indices are (row, col) pairs
+    - For a ring, d=1 and the indices are the angular slot numbers.
+    '''
+    n_matched: int
+    '''
+    The number of distinct canonical positions that were explained by the inlier sites.
+    '''
+    residual: float
+    '''
+    The fit residual.
+    '''
+    meta: dict = field(default_factory=dict)
+    '''
+    Model-specific metadata for logging and debugging purposes.
+    '''
+
+
+@dataclass
+class InstanceStats:
+    n_localizations: int
+    '''All input localizations, including noise.'''
+    n_input_clusters: int
+    '''Distinct non-negative labels in the original localization table.'''
+    n_input_cluster_localizations: int
+    '''Localizations belonging to those original clusters.'''
+
+    n_cluster_centers: int
+    '''Centers created by get_centers() after filtering.'''
+    n_rejected_centers: int
+    '''Centers rejected by center-level QC.'''
+
+    n_candidates: int
+    '''Candidate geometric groups produced by DBSCAN/HDBSCAN/OPTICS.'''
+    n_candidate_centers: int
+    '''Total site centers across all candidates.'''
+    n_rejected_candidates: int
+    '''Candidates where model.fit() returned None or residual QC failed.'''
+
+    n_passed_instances: int
+    '''Candidates that passed the geometric model.'''
+    n_passed_centers: int
+    '''Centers belonging to passed instances.'''
+    n_passed_localizations: int
+    '''Raw localizations belonging to passed instances.'''
+
+    candidate_log: list[dict] = field(default_factory=list)
+
+
+@dataclass
+class PlotResult:
+    '''
+    Unified return type for all ClustersScatter render methods.
+
+    raster      : pg.ImageItem or None   — 2D rasterized render
+    scatter     : list[pg.ScatterPlotItem] — raw scatter layers (when not rasterized)
+    histogram_x : list[pg.GraphicsObject] — X-projection histogram + KDE items
+    histogram_y : list[pg.GraphicsObject] — Y-projection histogram + KDE items
+    title       : str                     — plot title
+    pixel_size  : float                   — nm per pixel (carried from rasterized_2d)
+    '''
+
+    raster: pg.ImageItem | None = None
+    scatter: list[pg.ScatterPlotItem | pg.PlotCurveItem] = field(default_factory=list)
+    histogram_x: list[pg.GraphicsObject] = field(default_factory=list)
+    histogram_y: list[pg.GraphicsObject] = field(default_factory=list)
+    title: str = ''
+    pixel_size: float = 1.0
+
+    histogram_angle: list[pg.GraphicsObject] = field(default_factory=list)
+    histogram_intensity: list[pg.GraphicsObject] = field(default_factory=list)
+    histogram_n_matched: list[pg.GraphicsObject] = field(default_factory=list)
+
+    @property
+    def is_rasterized(self) -> bool:
+        return self.raster is not None
+
+    @property
+    def has_histograms(self) -> bool:
+        return bool(self.histogram_x or self.histogram_y or self.histogram_angle)
+
+@dataclass
+class LabeledLocalizations:
+    x: np.ndarray
+    y: np.ndarray
+    z: np.ndarray | None
+    labels: np.ndarray
+    intensity: np.ndarray | None
+    crlb_x: np.ndarray | None
+    crlb_y: np.ndarray | None
+    crlb_z: np.ndarray | None
+
+@dataclass
+class ClusterRenderData:
+    tables: list[LabeledLocalizations]
+    run_meta: dict = field(default_factory=dict)
+
+@dataclass
+class PipelineResult:
+    stats: list[InstanceStats]
+    instances: list[dict]
+    model_meta: dict
+    run_meta: dict
+