nanoobjectdetection 2.0.0__py3-none-any.whl

nanoobjectdetection/auto_parameters.py

@@ -0,0 +1,177 @@
+"""Automatic detection parameters ported from 1.0 (PSF width, trackpy diameter, minmass)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy import ndimage
+from scipy.signal import fftconvolve
+from scipy.spatial import cKDTree
+
+
+def sigma_psf_um(numerical_aperture: float, wavelength_nm: float) -> float:
+    """Gaussian approximation of the PSF width in µm (Zhang et al. 2007, as in 1.0)."""
+    return 0.21 * wavelength_nm / numerical_aperture / 1000.0
+
+
+def sigma_psf_px(
+    numerical_aperture: float, wavelength_nm: float, pixel_size_um: float
+) -> float:
+    return sigma_psf_um(numerical_aperture, wavelength_nm) / pixel_size_um
+
+
+def trackpy_diameter(
+    numerical_aperture: float,
+    wavelength_nm: float,
+    pixel_size_um: float,
+    enhance_snr: bool,
+) -> int:
+    """Odd trackpy feature diameter covering the 2-sigma interval of the PSF."""
+    diameter_px = 4.0 * sigma_psf_px(numerical_aperture, wavelength_nm, pixel_size_um)
+    if enhance_snr:
+        # Convolving the PSF with a Gaussian of equal width widens it by sqrt(2)
+        diameter_px *= np.sqrt(2.0)
+    diameter = int(np.ceil(diameter_px))
+    return diameter + 1 if diameter % 2 == 0 else diameter
+
+
+def red_x_from_theory(
+    exposure_time_s: float,
+    lagtime_s: float,
+    numerical_aperture: float,
+    wavelength_nm: float,
+    diffusion_um2_s: float = 1.0,
+    photons: float = 1.0,
+) -> float:
+    """Reduced squared localization error from theory (Michalet & Berglund 2012).
+
+    Mirrors 1.0, which evaluates it with D = 1 µm²/s and one photon.
+    """
+    blur = exposure_time_s / lagtime_s / 6.0
+    s0 = sigma_psf_um(numerical_aperture, wavelength_nm)
+    sigma0 = s0 / np.sqrt(photons)
+    sigma = sigma0 * np.sqrt(1.0 + diffusion_um2_s * exposure_time_s / s0**2)
+    return float(sigma**2 / (diffusion_um2_s * lagtime_s) - 2.0 * blur)
+
+
+def gaussian_kernel(sigma: float, factor: float = 6.0) -> np.ndarray:
+    size = int(np.ceil(factor * 2 * sigma))
+    size += 1 - size % 2
+    radius = (size - 1) // 2
+    y, x = np.mgrid[-radius : radius + 1, -radius : radius + 1]
+    kernel = np.exp(-(x**2 + y**2) / (2.0 * sigma**2))
+    return kernel / kernel.sum()
+
+
+def zncc_image(frame: np.ndarray, kernel: np.ndarray) -> np.ndarray:
+    """Zero-normalised cross-correlation of a frame with a kernel for every pixel.
+
+    Uses the identity zncc = sum(p * (k - mean k)) / (N * std(p) * std(k)), so the
+    whole image is handled by one FFT correlation and two box filters. Pixels whose
+    window leaves the image are 0, as in 1.0.
+    """
+    frame = np.asarray(frame, dtype=np.float64)
+    size = kernel.shape[0]
+    count = float(size * size)
+    centered = kernel - kernel.mean()
+    kernel_std = np.sqrt(np.mean(centered**2))
+    numerator = fftconvolve(frame, centered[::-1, ::-1], mode="same") / count
+    local_mean = ndimage.uniform_filter(frame, size, mode="constant")
+    local_square = ndimage.uniform_filter(frame**2, size, mode="constant")
+    local_std = np.sqrt(np.maximum(local_square - local_mean**2, 0.0))
+    denominator = local_std * kernel_std
+    result = np.divide(
+        numerator, denominator, out=np.zeros_like(frame), where=denominator > 1e-9
+    )
+    margin = (size - 1) // 2
+    result[:margin] = 0
+    result[-margin:] = 0
+    result[:, :margin] = 0
+    result[:, -margin:] = 0
+    return result
+
+
+def zncc_particles(
+    frames: np.ndarray,
+    sigma_px: float,
+    enhance_snr: bool,
+    minimum_correlation: float,
+) -> pd.DataFrame:
+    """Locate particles by ZNCC with the PSF; returns y, x, frame (local index)."""
+    if enhance_snr:
+        kernel = gaussian_kernel(sigma_px * np.sqrt(2.0), factor=10.0)
+    else:
+        kernel = gaussian_kernel(sigma_px)
+    structure = ndimage.generate_binary_structure(2, 2)
+    rows = []
+    for index, frame in enumerate(frames):
+        frame = np.maximum(np.asarray(frame, dtype=np.float64), 0.0)
+        if enhance_snr:
+            frame = ndimage.gaussian_filter(frame, sigma_px)
+        labels, count = ndimage.label(
+            zncc_image(frame, kernel) > minimum_correlation, structure=structure
+        )
+        if count:
+            centers = ndimage.center_of_mass(np.ones_like(labels), labels, range(1, count + 1))
+            rows.extend((int(y), int(x), index) for y, x in centers)
+    return pd.DataFrame(rows, columns=["y", "x", "frame"])
+
+
+def optimize_minmass(
+    candidates: pd.DataFrame,
+    reference: pd.DataFrame,
+    max_distance: float,
+    max_iterations: int = 100000,
+) -> tuple[float, pd.DataFrame]:
+    """Raise minmass until trackpy detections match the ZNCC reference best (1.0 algorithm).
+
+    ``candidates`` are trackpy detections found with minmass=1; raising the threshold
+    is then a simple mass filter. Returns the optimum (before the 0.9 safety factor)
+    and the history of the search.
+    """
+    reference_points = {
+        frame: group[["y", "x"]].to_numpy(float) for frame, group in reference.groupby("frame")
+    }
+    by_frame = {frame: group for frame, group in candidates.groupby("frame")}
+    n_reference = len(reference)
+    minmass = 1
+    history = []
+    first = True
+    for _ in range(max_iterations):
+        trees = {}
+        n_found = 0
+        for frame, group in by_frame.items():
+            kept = group[group["mass"] > minmass]
+            n_found += len(kept)
+            if len(kept):
+                trees[frame] = cKDTree(kept[["y", "x"]].to_numpy(float))
+        if first and n_found < n_reference:
+            raise RuntimeError(
+                "Trackpy finds fewer particles than the ZNCC reference even at minmass=1. "
+                "The sample may be too dense, or tp_percentile too aggressive."
+            )
+        first = False
+        if n_found > 5 * n_reference:
+            minmass = int(minmass * 1.2) + 10
+            continue
+        if n_found > 2 * n_reference:
+            minmass = int(minmass * 1.1) + 10
+            continue
+        right = 0
+        wrong = max(n_found - n_reference, 0)
+        for frame, points in reference_points.items():
+            tree = trees.get(frame)
+            if tree is None:
+                wrong += len(points)
+                continue
+            distance, _ = tree.query(points)
+            hits = int(np.sum(distance <= max_distance))
+            right += hits
+            wrong += len(points) - hits
+        ratio = wrong / right if right else np.inf
+        history.append((minmass, right, wrong, ratio))
+        if wrong == 0 or n_found < 0.8 * n_reference:
+            break
+        minmass = int(minmass * 1.02) + 1
+    table = pd.DataFrame(history, columns=["minmass", "right_found", "wrong_found", "wrong_to_right"])
+    return float(table.loc[table["wrong_to_right"].idxmin(), "minmass"]), table

nanoobjectdetection/calibration.py

@@ -0,0 +1,64 @@
+"""Automatic geometric calibration from the image stack."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from .storage import read_frames
+
+
+def estimate_channel_center_y(
+    frames: np.ndarray,
+    intensity_percentile: float = 99.5,
+) -> float:
+    """Estimate the transverse channel center from a robust intensity profile.
+
+    The high spatial percentile preserves the illuminated channel while the
+    median over time suppresses moving particles. The center is the weighted
+    centroid of the contiguous signal region above a conservative threshold.
+    """
+    data = np.asarray(frames, dtype=np.float32)
+    if data.ndim != 3 or data.shape[1] < 3:
+        raise ValueError("frames must have shape (frames, y, x)")
+    if not 90.0 <= intensity_percentile < 100.0:
+        raise ValueError("intensity_percentile must be in [90, 100)")
+
+    profile = np.median(
+        np.percentile(data, intensity_percentile, axis=2), axis=0
+    )
+    baseline = float(np.percentile(profile, 20))
+    peak = float(np.max(profile))
+    excess = profile - baseline
+    if peak <= baseline or not np.isfinite(peak):
+        raise ValueError("No channel signal found in transverse profile")
+
+    threshold = baseline + 0.30 * (peak - baseline)
+    active = profile >= threshold
+    peak_index = int(np.argmax(profile))
+    left = peak_index
+    right = peak_index
+    while left > 0 and active[left - 1]:
+        left -= 1
+    while right + 1 < len(active) and active[right + 1]:
+        right += 1
+    weights = np.maximum(excess[left : right + 1], 0)
+    positions = np.arange(left, right + 1, dtype=float)
+    # The midpoint is less sensitive to a few bright particles than a
+    # brightness-weighted centroid when the illumination is asymmetric.
+    return float((left + right) / 2.0)
+
+
+def estimate_channel_center_from_tiff(
+    path: str | Path,
+    frame_start: int = 0,
+    frame_stop: int | None = 300,
+    intensity_percentile: float = 99.5,
+) -> float:
+    """Estimate the channel center from a bounded TIFF sample."""
+    stop = frame_start + 300 if frame_stop is None else frame_stop
+    return estimate_channel_center_y(
+        read_frames(Path(path), frame_start, stop),
+        intensity_percentile=intensity_percentile,
+    )

nanoobjectdetection/config.py

@@ -0,0 +1,202 @@
+"""Configuration for the independent analysis pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .auto_parameters import sigma_psf_px
+
+
+@dataclass(frozen=True)
+class Roi:
+    x_min: int = 0
+    x_max: int | None = None
+    y_min: int = 0
+    y_max: int | None = None
+
+    @property
+    def x_slice(self) -> slice:
+        return slice(self.x_min, self.x_max)
+
+    @property
+    def y_slice(self) -> slice:
+        return slice(self.y_min, self.y_max)
+
+
+@dataclass(frozen=True)
+class AnalysisConfig:
+    input_file: Path
+    output_dir: Path
+    frame_start: int = 0
+    frame_stop: int | None = None
+    chunk_frames: int = 512
+    chunk_overlap_frames: int = 0
+    processing_mode: str = "chunked"
+    gpu_enabled: bool = False
+    gpu_memory_fraction: float = 0.7
+    locate_workers: int = 1
+    roi: Roi = Roi()
+    fps: float = 300.0
+    pixel_size_um: float = 1.0
+    wavelength_nm: float = 532.0
+    numerical_aperture: float = 0.25
+    exposure_time_s: float = 0.0007
+    temperature_k: float = 295.15
+    viscosity_pa_s: float = 0.00095
+    channel_diameter_nm: float | None = None
+    channel_center_y_px: float | None = None
+    auto_channel_center: bool = True
+    hindrance_mode: str = "none"
+    remove_camera_offset: bool = True
+    remove_laser_fluctuation: bool = False
+    remove_static_background: bool = True
+    enhance_snr: bool = False
+    snr_kernel_sigma_px: float | None = None
+    auto_diameter: bool = False
+    auto_minmass: bool = False
+    zncc_min: float = 0.7
+    minmass_try_frames: int = 30
+    red_x_mode: str = "exp"
+    single_particle: bool = False
+    single_particle_keep: str = "longest"
+    stitch_max_gap_frames: int = 300
+    stitch_max_distance_px: float = 15.0
+    stitch_distance_growth_px: float = 0.5
+    stitch_max_mass_ratio: float = 3.0
+    stitch_min_fragment_frames: int = 3
+    background_stack_storage: str = "memory"
+    processing_bit_depth: int = 16
+    background_method: str = "legacy_trimmed_mean"
+    intensity_normalization: str = "global"
+    particle_diameter: int = 7
+    particle_minmass: float = 100000.0
+    particle_separation: int = 15
+    particle_percentile: float = 20.0
+    minimum_trajectory_frames: int = 100
+    minimum_trajectory_frames_before_drift: int = 10
+    drift_enabled: bool = True
+    msd_max_lag_frames: int = 20
+    msd_lag_auto: bool = False
+    analyze_stationary_particles: bool = True
+    stationary_search_range: float = 0.3
+    stationary_minimum_frames: int = 100
+    no_go_distance: float = 20.0
+    split_intensity_jumps: bool = False
+    max_relative_intensity_step: float = 0.906
+    maximum_trajectory_frames: int | None = None
+    keep_short_trajectory_tail: bool = False
+    apply_quality_filter: bool = True
+    minimum_msd_pairs_at_max_lag: int = 5
+    minimum_ks_significance: float = 0.01
+    ks_method: str = "exact"
+    saturated_pixel_value: float | None = None
+    maximum_diameter_nm: float | None = None
+    force_ultra_uniform: bool = False
+    ultra_uniform_z_max: float = 2.576
+
+    def validate(self) -> None:
+        if not self.input_file.is_file():
+            raise FileNotFoundError(f"Input TIFF does not exist: {self.input_file}")
+        if self.frame_start < 0:
+            raise ValueError("frame_start must be non-negative")
+        if self.frame_stop is not None and self.frame_stop <= self.frame_start:
+            raise ValueError("frame_stop must be greater than frame_start")
+        if self.chunk_frames <= 0:
+            raise ValueError("chunk_frames must be positive")
+        if self.chunk_overlap_frames < 0 or self.chunk_overlap_frames >= self.chunk_frames:
+            raise ValueError("chunk_overlap_frames must be in [0, chunk_frames)")
+        if self.processing_mode not in {"chunked", "single_stack"}:
+            raise ValueError("processing_mode must be 'chunked' or 'single_stack'")
+        if self.background_stack_storage not in {"memory", "disk"}:
+            raise ValueError(
+                "background_stack_storage must be 'memory' or 'disk'"
+            )
+        if self.processing_bit_depth not in {8, 16}:
+            raise ValueError("processing_bit_depth must be 8 or 16")
+        if self.background_method not in {"median", "legacy_trimmed_mean"}:
+            raise ValueError("background_method must be 'median' or 'legacy_trimmed_mean'")
+        if self.intensity_normalization not in {"global", "block"}:
+            raise ValueError("intensity_normalization must be 'global' or 'block'")
+        if self.hindrance_mode not in {"none", "legacy", "position"}:
+            raise ValueError(
+                "hindrance_mode must be 'none', 'legacy', or 'position'"
+            )
+        if self.hindrance_mode in {"legacy", "position"}:
+            if self.channel_diameter_nm is None or self.channel_diameter_nm <= 0:
+                raise ValueError(
+                    "channel_diameter_nm is required for hindrance correction"
+                )
+        if self.hindrance_mode == "position" and (
+            self.channel_center_y_px is None and not self.auto_channel_center
+        ):
+            raise ValueError(
+                "position hindrance correction requires channel_center_y_px "
+                "or auto_channel_center=True"
+            )
+        if not 0 < self.gpu_memory_fraction < 1:
+            raise ValueError("gpu_memory_fraction must be between 0 and 1")
+        if self.fps <= 0:
+            raise ValueError("fps must be positive")
+        if self.pixel_size_um <= 0:
+            raise ValueError("pixel_size_um must be positive")
+        if self.wavelength_nm <= 0:
+            raise ValueError("wavelength_nm must be positive")
+        if self.numerical_aperture <= 0:
+            raise ValueError("numerical_aperture must be positive")
+        if self.red_x_mode not in {"exp", "theory"}:
+            raise ValueError("red_x_mode must be 'exp' or 'theory'")
+        if self.single_particle_keep not in {"longest", "brightest", "all"}:
+            raise ValueError("single_particle_keep must be 'longest', 'brightest' or 'all'")
+        if (
+            self.stitch_max_gap_frames < 1
+            or self.stitch_max_distance_px <= 0
+            or self.stitch_distance_growth_px < 0
+            or self.stitch_max_mass_ratio < 1
+            or self.stitch_min_fragment_frames < 1
+        ):
+            raise ValueError("Invalid stitching parameters")
+        if not 0 < self.zncc_min < 1:
+            raise ValueError("zncc_min must be between 0 and 1")
+        if self.minmass_try_frames < 1:
+            raise ValueError("minmass_try_frames must be at least 1")
+        if self.snr_kernel_sigma_px is not None and self.snr_kernel_sigma_px <= 0:
+            raise ValueError("snr_kernel_sigma_px must be positive")
+        if self.exposure_time_s <= 0:
+            raise ValueError("exposure_time_s must be positive")
+        if self.minimum_trajectory_frames < 2 or self.minimum_trajectory_frames_before_drift < 2:
+            raise ValueError("minimum trajectory lengths must be at least 2")
+        if self.msd_max_lag_frames < 2:
+            raise ValueError("msd_max_lag_frames must be at least 2")
+        if self.particle_diameter < 3 or self.particle_diameter % 2 == 0:
+            raise ValueError("particle_diameter must be an odd integer >= 3")
+        if self.stationary_search_range <= 0 or self.stationary_minimum_frames < 2:
+            raise ValueError("Stationary-particle parameters must be positive")
+        if self.no_go_distance < 0:
+            raise ValueError("no_go_distance must be non-negative")
+        if self.max_relative_intensity_step <= 0:
+            raise ValueError("max_relative_intensity_step must be positive")
+        if self.minimum_msd_pairs_at_max_lag < 2:
+            raise ValueError("minimum_msd_pairs_at_max_lag must be at least 2")
+        if self.ks_method not in {"exact", "legacy"}:
+            raise ValueError("ks_method must be 'exact' or 'legacy'")
+        if not 0 < self.minimum_ks_significance < 1:
+            raise ValueError("minimum_ks_significance must be between 0 and 1")
+        if self.ultra_uniform_z_max <= 0:
+            raise ValueError("ultra_uniform_z_max must be positive")
+        if self.maximum_diameter_nm is not None and self.maximum_diameter_nm <= 0:
+            raise ValueError("maximum_diameter_nm must be positive")
+        if (
+            self.maximum_trajectory_frames is not None
+            and self.maximum_trajectory_frames < self.minimum_trajectory_frames_before_drift
+        ):
+            raise ValueError("maximum_trajectory_frames is too short")
+
+    @property
+    def effective_snr_sigma_px(self) -> float:
+        """Gaussian sigma of the SNR filter; the PSF width when KernelSize is "auto"."""
+        if self.snr_kernel_sigma_px is not None:
+            return self.snr_kernel_sigma_px
+        return sigma_psf_px(
+            self.numerical_aperture, self.wavelength_nm, self.pixel_size_um
+        )

nanoobjectdetection/drift.py

@@ -0,0 +1,47 @@
+"""Drift estimation from linked trajectories."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import trackpy as tp
+
+
+def correct_global(
+    trajectories: pd.DataFrame,
+    window: int = 20,
+    min_particles: int = 2,
+    minimum_frames: int = 1,
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """Estimate frame-to-frame common motion and subtract its cumulative sum."""
+    required = {"frame", "x", "y"}
+    missing = required.difference(trajectories.columns)
+    if missing:
+        raise ValueError(f"Trajectories are missing columns: {sorted(missing)}")
+    result = trajectories.copy().sort_values(["frame", "particle"])
+    # Saturated positions are poorly localized and, as in 1.0, excluded from the estimate
+    estimation = result
+    if "saturated" in result:
+        estimation = result[~result["saturated"].astype(bool)]
+    if minimum_frames > 1:
+        lengths = estimation.groupby("particle")["frame"].transform("size")
+        estimation = estimation[lengths >= minimum_frames]
+    drift = tp.compute_drift(
+        estimation[["particle", "frame", "x", "y"]],
+        smoothing=window,
+    )
+    full_index = result["frame"].sort_values().unique()
+    # trackpy starts at the second frame; the first frame is the zero-drift reference (as in 1.0)
+    drift = drift.reindex(full_index).interpolate(method="linear").ffill().fillna(0.0)
+    drift.index.name = "frame"
+    drift = drift.rename(columns={"x": "drift_x", "y": "drift_y"}).reset_index()
+    if drift.empty:
+        result["x_corrected"] = result["x"]
+        result["y_corrected"] = result["y"]
+        return result, drift
+    correction = drift.set_index("frame")[["drift_x", "drift_y"]]
+    result = result.join(correction, on="frame")
+    result[["drift_x", "drift_y"]] = result[["drift_x", "drift_y"]].fillna(0.0)
+    result["x_corrected"] = result["x"] - result["drift_x"]
+    result["y_corrected"] = result["y"] - result["drift_y"]
+    return result.reset_index(drop=True), drift.reset_index(drop=True)

nanoobjectdetection/gpu.py

@@ -0,0 +1,126 @@
+"""Optional CuPy acceleration and GPU-memory-aware chunk sizing."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def get_cupy():
+    """Return CuPy or ``None`` when the optional GPU backend is unavailable."""
+    try:
+        import cupy
+    except ImportError:
+        return None
+    return cupy
+
+
+def gpu_available() -> bool:
+    """Return whether a CUDA device is available to CuPy."""
+    cupy = get_cupy()
+    if cupy is None:
+        return False
+    try:
+        return int(cupy.cuda.runtime.getDeviceCount()) > 0
+    except (RuntimeError, OSError):
+        return False
+
+
+def device_memory_bytes() -> int:
+    """Return free memory on the active CUDA device."""
+    cupy = get_cupy()
+    if cupy is None:
+        raise RuntimeError("CuPy is not installed")
+    try:
+        free, _ = cupy.cuda.Device().mem_info
+    except (RuntimeError, OSError) as exc:
+        raise RuntimeError("Could not query CUDA device memory") from exc
+    return int(free)
+
+
+def choose_chunk_frames(
+    requested_frames: int,
+    height: int,
+    width: int,
+    memory_fraction: float,
+    bytes_per_pixel: int = 4,
+) -> int:
+    """Limit a chunk to a safe fraction of currently free GPU memory."""
+    if not 0 < memory_fraction < 1:
+        raise ValueError("gpu_memory_fraction must be between 0 and 1")
+    free = device_memory_bytes()
+    # Input, float32 working copy, background median, and output need headroom.
+    bytes_per_frame = height * width * bytes_per_pixel
+    safe_frames = int(free * memory_fraction / max(bytes_per_frame * 4, 1))
+    return max(1, min(requested_frames, safe_frames))
+
+
+def preprocess_gpu(
+    frames: np.ndarray,
+    remove_camera_offset: bool,
+    remove_laser_fluctuation: bool = False,
+    remove_static_background: bool = True,
+    background_method: str = "legacy_trimmed_mean",
+    enhance_snr: bool = False,
+    background: np.ndarray | None = None,
+    offset: float | None = None,
+    snr_sigma_px: float = 1.0,
+) -> np.ndarray:
+    """Run preprocessing on CUDA and return a NumPy array for Trackpy."""
+    cupy = get_cupy()
+    if cupy is None or not gpu_available():
+        raise RuntimeError("GPU preprocessing requested but no CUDA/CuPy device is available")
+    device_frames = cupy.asarray(frames, dtype=cupy.float32)
+    if remove_camera_offset:
+        device_frames -= cupy.min(device_frames) if offset is None else offset
+    if remove_laser_fluctuation:
+        frame_intensity = cupy.mean(device_frames, axis=(1, 2))
+        reference = cupy.median(frame_intensity)
+        device_frames /= cupy.maximum(
+            frame_intensity[:, None, None] / cupy.maximum(reference, 1e-12),
+            1e-12,
+        )
+    if remove_static_background:
+        if background is not None:
+            device_frames -= cupy.asarray(background, dtype=cupy.float32)
+        elif background_method == "median":
+            background = cupy.median(device_frames, axis=0, keepdims=True)
+        elif background_method == "legacy_trimmed_mean":
+            ordered = cupy.sort(device_frames, axis=0)
+            first = int(0.3 * len(ordered))
+            last = max(first + 1, int(0.7 * len(ordered)))
+            background = cupy.mean(ordered[first:last], axis=0, keepdims=True)
+        else:
+            raise ValueError(
+                "background_method must be 'median' or 'legacy_trimmed_mean'"
+            )
+        device_frames -= background
+    result = cupy.asnumpy(device_frames)
+    if enhance_snr:
+        from scipy.ndimage import gaussian_filter
+
+        result = gaussian_filter(result, sigma=(0, snr_sigma_px, snr_sigma_px))
+    del device_frames
+    cupy.get_default_memory_pool().free_all_blocks()
+    return result
+
+
+def to_uint16_gpu(frames: np.ndarray, scale_max: float | None = None) -> np.ndarray:
+    """Convert processed frames to uint16 on CUDA."""
+    cupy = get_cupy()
+    if cupy is None or not gpu_available():
+        raise RuntimeError("GPU conversion requested but no CUDA/CuPy device is available")
+    device_frames = cupy.maximum(cupy.asarray(frames, dtype=cupy.float32), 0)
+    maximum = (
+        float(cupy.asnumpy(cupy.max(device_frames)))
+        if scale_max is None
+        else scale_max
+    )
+    if maximum == 0:
+        result = np.zeros(frames.shape, dtype=np.uint16)
+    else:
+        result = cupy.asnumpy(cupy.rint(device_frames * (65535.0 / maximum))).astype(
+            np.uint16
+        )
+    del device_frames
+    cupy.get_default_memory_pool().free_all_blocks()
+    return result

nanoobjectdetection/hindrance.py

@@ -0,0 +1,56 @@
+"""Hydrodynamic diameter and position-aware channel correction."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.constants import Boltzmann
+
+
+def local_channel_diameter_nm(
+    y_px: np.ndarray,
+    center_y_px: float,
+    channel_diameter_nm: float,
+    pixel_size_um: float,
+) -> float:
+    """Estimate the mean available diameter in a circular channel."""
+    if channel_diameter_nm <= 0 or pixel_size_um <= 0:
+        raise ValueError("Channel diameter and pixel size must be positive")
+    radius_px = channel_diameter_nm / 1000.0 / pixel_size_um / 2.0
+    available = np.maximum(radius_px - np.abs(np.asarray(y_px) - center_y_px), 0.0)
+    return float(np.mean(2.0 * available * pixel_size_um * 1000.0))
+
+
+def hindrance_factor(channel_diameter_nm: float, particle_diameter_nm: float) -> float:
+    """Return the Dechadilok-Deen diffusive hindrance factor Kd."""
+    ratio = particle_diameter_nm / channel_diameter_nm
+    if not 0 < ratio < 1:
+        raise ValueError("Particle must be smaller than the local channel")
+    h = (
+        1 + 9 / 8 * ratio * np.log(ratio) - 1.56034 * ratio
+        + 0.528155 * ratio**2 + 1.915210 * ratio**3
+        - 2.819030 * ratio**4 + 0.270788 * ratio**5
+        + 1.101150 * ratio**6 - 0.435933 * ratio**7
+    )
+    return float(h / (1 - ratio) ** 2)
+
+
+def corrected_diameter_nm(
+    diffusion_um2_s: float,
+    temperature_k: float,
+    viscosity_pa_s: float,
+    channel_diameter_nm: float | None = None,
+) -> float:
+    """Convert diffusion to diameter and optionally invert channel hindrance."""
+    if diffusion_um2_s <= 0 or temperature_k <= 0 or viscosity_pa_s <= 0:
+        raise ValueError("Diffusion, temperature, and viscosity must be positive")
+    diameter = 2 * Boltzmann * temperature_k / (6 * np.pi * viscosity_pa_s) * 1e9 / (diffusion_um2_s * 1e-12)
+    if channel_diameter_nm is None or diameter >= channel_diameter_nm:
+        return float(diameter)
+    # Same damped fixed-point iteration as 1.0 (geometric mean of new and old estimate)
+    corrected, previous = diameter, 0.0
+    for _ in range(100):
+        if abs(corrected - previous) <= 0.1:
+            return float(corrected)
+        previous = corrected
+        corrected = np.sqrt(diameter * hindrance_factor(channel_diameter_nm, previous) * previous)
+    return float(previous)