nanoobjectdetection 2.0.0__py3-none-any.whl

nanoobjectdetection/storage.py

@@ -0,0 +1,187 @@
+"""Chunked TIFF storage for the independent pipeline."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from .progress import progress
+
+
+def _tifffile():
+    try:
+        import tifffile
+    except ImportError as exc:
+        raise RuntimeError("Install 'tifffile' to use TIFF storage.") from exc
+    return tifffile
+
+
+def tiff_info(path: Path) -> dict[str, Any]:
+    tifffile = _tifffile()
+    with tifffile.TiffFile(path) as tif:
+        series = tif.series[0]
+        return {
+            "path": str(path.resolve()),
+            "shape": tuple(series.shape),
+            "axes": series.axes,
+            "dtype": str(series.dtype),
+            "pages": len(tif.pages),
+        }
+
+
+def to_processing_bit_depth(
+    frames: np.ndarray, processing_bit_depth: int
+) -> np.ndarray:
+    """Convert unsigned TIFF frames to the selected processing bit depth."""
+    if processing_bit_depth == 16:
+        return frames
+    if processing_bit_depth != 8:
+        raise ValueError("processing_bit_depth must be 8 or 16")
+
+    data = np.asarray(frames)
+    if data.dtype.kind != "u":
+        raise ValueError(
+            "8-bit processing requires an unsigned 8-bit or 16-bit TIFF stack"
+        )
+    if data.dtype.itemsize == 1:
+        return data
+    if data.dtype.itemsize == 2:
+        return np.right_shift(data, 8).astype(np.uint8)
+    raise ValueError(
+        "8-bit processing requires an unsigned 8-bit or 16-bit TIFF stack"
+    )
+
+
+def read_frames(path: Path, first: int, stop: int) -> np.ndarray:
+    tifffile = _tifffile()
+    try:
+        mapped = tifffile.memmap(path, mode="r")
+        result = np.array(mapped[first:stop], copy=True)
+        del mapped
+        return result
+    except (OSError, ValueError, RuntimeError):
+        return np.asarray(tifffile.imread(path, key=slice(first, stop)))
+
+
+def iter_tiff_frames(
+    path: Path, frame_start: int, frame_stop: int | None
+) -> Iterator[tuple[int, np.ndarray]]:
+    """Yield source TIFF frames sequentially without creating a chunk store."""
+    tifffile = _tifffile()
+    with tifffile.TiffFile(path) as tif:
+        series = tif.series[0]
+        total = int(series.shape[0]) if len(series.shape) > 2 else len(tif.pages)
+        stop = total if frame_stop is None else min(frame_stop, total)
+        if frame_start < 0 or frame_start >= stop:
+            raise ValueError("Configured frame range is outside the source TIFF")
+        if len(tif.pages) >= total:
+            for frame_number in range(frame_start, stop):
+                yield frame_number, tif.pages[frame_number].asarray()
+            return
+    # ImageJ stacks store all frames behind a single page header; map them directly
+    mapped = tifffile.memmap(path, mode="r")
+    try:
+        for frame_number in range(frame_start, stop):
+            yield frame_number, np.array(mapped[frame_number])
+    finally:
+        del mapped
+
+
+def create_store(
+    source: Path,
+    target: Path,
+    frame_start: int,
+    frame_stop: int | None,
+    chunk_frames: int,
+    chunk_overlap_frames: int,
+    y_slice: slice,
+    x_slice: slice,
+    processing_bit_depth: int = 16,
+) -> dict[str, Any]:
+    """Create a reproducible chunk store without changing the source."""
+    info = tiff_info(source)
+    total = int(info["shape"][0])
+    stop = total if frame_stop is None else min(frame_stop, total)
+    if frame_start >= stop:
+        raise ValueError("Configured frame range is outside the source TIFF")
+
+    chunks_dir = target / "chunks"
+    chunks_dir.mkdir(parents=True, exist_ok=True)
+    tifffile = _tifffile()
+    manifest: dict[str, Any] = {
+        "format": "nanoobjectdetection-2.0-chunks-v1",
+        "source": str(source.resolve()),
+        "axes": info["axes"],
+        "source_dtype": info["dtype"],
+        "dtype": (
+            "uint8"
+            if processing_bit_depth == 8 and np.dtype(info["dtype"]).itemsize == 2
+            else info["dtype"]
+        ),
+        "frame_start": frame_start,
+        "frame_stop": stop,
+        "chunk_frames": chunk_frames,
+        "chunk_overlap_frames": chunk_overlap_frames,
+        "shape": None,
+        "chunks": [],
+    }
+    step = chunk_frames - chunk_overlap_frames
+    chunk_starts = range(frame_start, stop, step)
+    total_chunks = (stop - frame_start + step - 1) // step
+    for chunk_number, first in enumerate(
+        progress(
+            chunk_starts,
+            desc="Writing TIFF chunks",
+            total=total_chunks,
+            unit="chunk",
+        )
+    ):
+        last = min(first + chunk_frames, stop)
+        data = read_frames(source, first, last)
+        data = data[:, y_slice, x_slice]
+        data = to_processing_bit_depth(data, processing_bit_depth)
+        if manifest["shape"] is None:
+            manifest["shape"] = [stop - frame_start, data.shape[1], data.shape[2]]
+        name = f"chunk_{chunk_number:06d}.tif"
+        tifffile.imwrite(
+            chunks_dir / name,
+            data,
+            compression="deflate",
+            predictor=True,
+            metadata={"axes": "ZYX"},
+        )
+        manifest["chunks"].append(
+            {
+                "file": f"chunks/{name}",
+                "frame_start": first,
+                "frame_stop": last,
+                "shape": list(data.shape),
+            }
+        )
+        del data
+
+    (target / "manifest.json").write_text(
+        json.dumps(manifest, indent=2), encoding="utf-8"
+    )
+    return manifest
+
+
+def iter_blocks(store: Path) -> Iterator[tuple[int, np.ndarray]]:
+    manifest_path = store / "manifest.json"
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if manifest.get("format") != "nanoobjectdetection-2.0-chunks-v1":
+        raise ValueError(f"Unsupported image store: {store}")
+    for chunk in progress(
+        manifest["chunks"],
+        desc="Reading image chunks",
+        total=len(manifest["chunks"]),
+        unit="chunk",
+    ):
+        yield (
+            int(chunk["frame_start"]),
+            read_frames(store / chunk["file"], 0, int(chunk["shape"][0])),
+        )

nanoobjectdetection/synthetic.py

@@ -0,0 +1,28 @@
+"""Deterministic synthetic trajectories for numerical pipeline tests."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def brownian_trajectories(
+    particles: int = 3,
+    frames: int = 200,
+    diffusion_um2_s: float = 1.0,
+    fps: float = 300.0,
+    seed: int = 42,
+    drift_per_frame: tuple[float, float] = (0.0, 0.0),
+) -> pd.DataFrame:
+    """Generate linked trajectories in pixel coordinates."""
+    rng = np.random.default_rng(seed)
+    rows = []
+    step = np.sqrt(2 * diffusion_um2_s / fps)
+    for particle in range(particles):
+        positions = np.zeros((frames, 2))
+        positions[0] = rng.normal(0, 1, 2)
+        positions[1:] = positions[0] + np.cumsum(rng.normal(0, step, (frames - 1, 2)), axis=0)
+        positions += np.arange(frames)[:, None] * drift_per_frame
+        for frame, (x, y) in enumerate(positions):
+            rows.append({"particle": particle, "frame": frame, "x": x, "y": y})
+    return pd.DataFrame(rows)

nanoobjectdetection/tracking.py

@@ -0,0 +1,75 @@
+"""Trajectory linking for the independent pipeline."""
+
+from __future__ import annotations
+
+import pandas as pd
+import sys
+import numpy as np
+
+
+def link(
+    detections: pd.DataFrame,
+    search_range: float,
+    memory: int = 1,
+    minimum_frames: int = 100,
+    adaptive_stop: float | None = None,
+    adaptive_step: float = 0.9,
+) -> pd.DataFrame:
+    """Link detections without importing any historical project module."""
+    try:
+        import trackpy as tp
+        from trackpy.linking.utils import SubnetOversizeException
+    except ImportError as exc:
+        raise RuntimeError(
+            "Trajectory linking requires 'trackpy', but it is not "
+            f"installed in the active interpreter ({sys.executable}). "
+            "Install it with: python -m pip install trackpy"
+        ) from exc
+    tp.quiet()
+    required = {"frame", "x", "y"}
+    missing = required.difference(detections.columns)
+    if missing:
+        raise ValueError(f"Detections are missing columns: {sorted(missing)}")
+    if search_range <= 0:
+        raise ValueError("search_range must be positive")
+    if not 0 < adaptive_step < 1:
+        raise ValueError("adaptive_step must be between 0 and 1")
+    if adaptive_stop is None:
+        adaptive_stop = min(0.5, search_range * 0.25)
+    if not 0 < adaptive_stop < search_range:
+        raise ValueError("adaptive_stop must be positive and smaller than search_range")
+    try:
+        linked = tp.link_df(
+            detections.sort_values("frame"),
+            search_range=search_range,
+            memory=memory,
+            adaptive_stop=adaptive_stop,
+            adaptive_step=adaptive_step,
+        )
+    except SubnetOversizeException as exc:
+        raise RuntimeError(
+            "Trackpy could not resolve a dense linking subnetwork even after "
+            f"adaptive search-range reduction to {adaptive_stop:g} pixels. "
+            "Reduce search_range, increase particle_minmass, or inspect "
+            "overlapping detections."
+        ) from exc
+    lengths = linked.groupby("particle")["frame"].transform("size")
+    return linked[lengths >= minimum_frames].reset_index(drop=True)
+
+
+def remove_near_stationary(
+    detections: pd.DataFrame,
+    stationary: pd.DataFrame,
+    distance: float,
+) -> pd.DataFrame:
+    """Remove detections inside the 1.0 stationary-particle no-go areas."""
+    if distance < 0:
+        raise ValueError("distance must be non-negative")
+    if stationary.empty or detections.empty:
+        return detections.copy()
+    centers = stationary.groupby("particle")[["x", "y"]].mean().to_numpy()
+    points = detections[["x", "y"]].to_numpy()
+    keep = np.ones(len(points), dtype=bool)
+    for center in centers:
+        keep &= np.hypot(points[:, 0] - center[0], points[:, 1] - center[1]) > distance
+    return detections.loc[keep].reset_index(drop=True)

nanoobjectdetection/trajectory_processing.py

@@ -0,0 +1,81 @@
+"""Trajectory filtering and splitting compatible with the 1.0 workflow."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def filter_minimum_frames(
+    trajectories: pd.DataFrame, minimum_frames: int
+) -> pd.DataFrame:
+    """Keep trajectories with at least ``minimum_frames`` measured positions."""
+    if minimum_frames < 1:
+        raise ValueError("minimum_frames must be positive")
+    if trajectories.empty:
+        return trajectories.copy()
+    lengths = trajectories.groupby("particle")["frame"].transform("size")
+    return trajectories.loc[lengths >= minimum_frames].reset_index(drop=True)
+
+
+def _interpolated_mass(group: pd.DataFrame) -> pd.Series:
+    indexed = group.sort_values("frame").set_index("frame")["mass"].astype(float)
+    full = indexed.reindex(range(int(indexed.index.min()), int(indexed.index.max()) + 1))
+    return full.interpolate(method="nearest").bfill().ffill()
+
+
+def split_intensity_jumps(
+    trajectories: pd.DataFrame,
+    relative_step: float,
+    minimum_frames: int,
+) -> pd.DataFrame:
+    """Split tracks at large relative mass jumps and discard short fragments."""
+    if relative_step <= 0:
+        raise ValueError("relative_step must be positive")
+    required = {"particle", "frame", "mass"}
+    missing = required.difference(trajectories.columns)
+    if missing:
+        raise ValueError(f"Trajectories are missing columns: {sorted(missing)}")
+
+    result = trajectories.copy().sort_values(["particle", "frame"])
+    next_particle = int(result["particle"].max()) + 1 if not result.empty else 0
+    for particle, group in list(result.groupby("particle", sort=False)):
+        mass = _interpolated_mass(group)
+        smooth = mass.rolling(3, center=True, min_periods=1).median()
+        previous = smooth.shift(1)
+        relative = (smooth - previous).abs() / ((smooth + previous.abs()) / 2.0)
+        split_frames = relative.index[relative > relative_step].tolist()
+        for frame in split_frames:
+            mask = (result["particle"] == particle) & (result["frame"] >= frame)
+            result.loc[mask, "particle"] = next_particle
+            next_particle += 1
+            particle = next_particle - 1
+    return filter_minimum_frames(result, minimum_frames)
+
+
+def split_long_trajectories(
+    trajectories: pd.DataFrame,
+    maximum_frames: int | None,
+    minimum_frames: int,
+    keep_tail: bool = False,
+) -> pd.DataFrame:
+    """Split long tracks into bounded contiguous frame segments."""
+    if maximum_frames is None:
+        return trajectories.copy()
+    if maximum_frames < minimum_frames:
+        raise ValueError("maximum_frames must be at least minimum_frames")
+    result_parts: list[pd.DataFrame] = []
+    next_particle = int(trajectories["particle"].max()) + 1 if not trajectories.empty else 0
+    for _, group in trajectories.sort_values(["particle", "frame"]).groupby("particle"):
+        group = group.copy()
+        for start in range(0, len(group), maximum_frames):
+            part = group.iloc[start : start + maximum_frames].copy()
+            if len(part) < minimum_frames and not keep_tail:
+                continue
+            if start:
+                part["particle"] = next_particle
+                next_particle += 1
+            result_parts.append(part)
+    if not result_parts:
+        return trajectories.iloc[0:0].copy()
+    return pd.concat(result_parts, ignore_index=True)

nanoobjectdetection/ultra_uniform.py

@@ -0,0 +1,52 @@
+"""Ultra-uniform particle hypothesis filter (z-score based, as in 1.0 PostProcessing)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+# 99 % two-sided confidence level
+DEFAULT_Z_MAX = 2.576
+
+
+def _spread(values: np.ndarray) -> float:
+    return float(np.sqrt(np.mean((values - np.median(values)) ** 2)))
+
+
+def _remove_outliers(data: pd.DataFrame, column: str, roll_area: int, z_max: float) -> pd.DataFrame:
+    """Iteratively drop rows whose z-score (median-centred, rolling spread) reaches z_max."""
+    while len(data):
+        spread = data[column].rolling(roll_area, min_periods=1, center=True).apply(_spread, raw=True)
+        z = (data[column] - data[column].median()).abs() / spread
+        if z.max() < z_max:
+            break
+        data = data[z < z_max]
+    return data
+
+
+def ultra_uniform_mask(
+    estimates: pd.DataFrame,
+    z_max: float = DEFAULT_Z_MAX,
+    diameter_column: str = "diameter_nm",
+    diffusion_column: str = "diffusion_um2_s",
+    order_column: str = "valid_frames",
+) -> pd.Series:
+    """Return a boolean mask of particles that fit a single uniform particle species.
+
+    Particles are ordered by trajectory precision, then diameter and diffusion are
+    filtered one after the other (diffusion on the particles that survived the
+    diameter step), exactly like ForceUltraUniformParticle in 1.0.
+    """
+    valid = estimates[estimates[diameter_column].notna() & estimates[diffusion_column].notna()]
+    num_particles = len(valid)
+    if num_particles < 10:
+        return pd.Series(True, index=estimates.index)
+    roll_area = 100 if num_particles >= 100 else num_particles - 2
+    data = valid[[diameter_column, diffusion_column, order_column]].sort_values(order_column)
+    data = _remove_outliers(data, diameter_column, roll_area, z_max)
+    data = _remove_outliers(data, diffusion_column, roll_area, z_max)
+    keep = pd.Series(False, index=estimates.index)
+    keep.loc[data.index] = True
+    # Rows without a valid estimate were already rejected earlier and are left untouched
+    keep.loc[~estimates.index.isin(valid.index)] = True
+    return keep

nanoobjectdetection-2.0.0.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: nanoobjectdetection
+Version: 2.0.0
+Summary: Particle localization and diffusion analysis for TIFF image stacks
+Author: Tim Stechel, Ronny Förster
+License: MIT
+Project-URL: Homepage, https://github.com/knobold/NanoObjectDetection
+Project-URL: Repository, https://github.com/knobold/NanoObjectDetection
+Project-URL: Issues, https://github.com/knobold/NanoObjectDetection/issues
+Keywords: nanoparticles,microscopy,diffusion,tracking,stokes-einstein,trackpy,tiff
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: tifffile
+Requires-Dist: trackpy
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Requires-Dist: numba
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x; extra == "gpu"
+
+# NanoObjectDetection 2.0
+
+This is a new Version of Ronny Foersters Package. The old Package had lots of issues with type safety and RAM usage. This new implementation aims to improve RAM usage and enable us to easily develop new features.
+
+NanoObjectDetection analyzes TIFF image stacks of diffusing particles. It
+localizes particles, links detections into trajectories, estimates diffusion
+and hydrodynamic diameter, and exports analysis tables and plots. Version 2.0
+keeps compatibility with the 1.0 parameter format and adds blockwise
+processing and optional CUDA acceleration.
+
+The source checkout also contains the original 1.0 implementation in
+[`nanoobjectdetection_legacy/`](./nanoobjectdetection_legacy/); the installable
+distribution packages the modern pipeline under the `nanoobjectdetection`
+package. For full parameter descriptions,
+scientific methods, compatibility details, limitations, and output-file
+definitions, see the
+[2.0 documentation](./NANOOBJECTDETECTION_2_0_DOCUMENTATION.md).
+
+## Features
+
+- TIFF stack input with spatial and frame-range ROI selection.
+- Camera-offset, laser-fluctuation, static-background, and optional SNR
+  preprocessing.
+- Trackpy particle localization and trajectory linking, including optional
+  stitching for repeatedly lost single-particle detections.
+- Fixed-particle filtering, trajectory quality checks, and global drift
+  correction.
+- Mean-squared displacement analysis, diffusion estimation, and
+  Stokes-Einstein hydrodynamic diameter calculations.
+- Optional channel hindrance correction, including position-aware correction.
+- Single Particle Tracking using stitched Trajectories
+- RAM saving options: Single-stack and chunked execution modes, plus optional CUDA preprocessing, Optional Conversion of pixels to 8bit depth, 16bit is probably overkill.
+- CSV tables, compatibility output names, run configuration, and plots.
+
+## New Features
+
+- Try to implement them on your own! AI is powerful and easy too use. You can then try to submit a merge request here.
+
+## Issues
+
+- 1st Try to solve the issue yourself with AI
+-> if its a bug caused by this repo, not your local installation open an Issue or write me a detailed  Bug report on Slack. Paste console logs or anything that helps me solve your issue.
+
+## Installation
+
+### From PyPI (Recommended)
+
+Install the latest release directly via pip:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install nanoobjectdetection
+```
+
+For GPU acceleration with CUDA 12.x:
+
+```bash
+python -m pip install "nanoobjectdetection[gpu]"
+```
+
+### From Source Checkout
+
+Download this repo as a `.zip` file and unpack it, or clone via Git.
+From the repository folder, activate your environment and install:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+To install an editable development copy instead, use `python -m pip install -e .` from the repository folder.
+
+The installation adds the `nanoobjectdetection` CLI command. It can be run from
+any working directory:
+
+```bash
+nanoobjectdetection --input-file "path/to/stack.tif" --output-dir "path/to/output"
+```
+
+### Python Example & Scripting
+
+The recommended way to use the package is to adjust analysis parameters in an example script. Run the included [`example/example.py`](./example/example.py) from any directory:
+
+```powershell
+python "example/example.py" `
+  --input-file "path/to/my_stack.tif" `
+  --output-dir "path/to/my_analysis" `
+  --background-stack-storage disk `
+  --processing-bit-depth 8 `
+  --dimension all
+```
+
+The script imports `run` directly from the installed package:
+```python
+from nanoobjectdetection import run
+```
+Its `PARAMETERS` dictionary and processing settings near the top of
+`example/example.py` expose the full analysis configuration for editing. Omit
+`--parameter-file` to use those settings; optionally add
+`--parameter-file "path/to/parameter.json"` to use a legacy JSON instead.
+Input/output paths can be configured directly inside the script or passed as CLI options.
+Run `python example/example.py --help` for all options.
+
+### Optional GPU preprocessing
+
+GPU mode requires a supported NVIDIA GPU, a compatible CUDA runtime, and the
+matching CuPy package. For CUDA 12.x, install the package's GPU extra:
+
+```bash
+python -m pip install ".[gpu]"
+```
+
+If your CUDA version differs, install the CuPy package matching your CUDA
+runtime instead. The pipeline reports an error if GPU mode is requested but a
+usable CUDA device is unavailable. Trackpy localization, linking, and MSD
+fitting remain CPU operations.
+
+## Run from an IDE
+
+The source `main.py` defaults to the included example TIFF and can be run
+directly from VS Code, PyCharm, or another Python IDE:
+
+1. Open the repository folder in your IDE.
+2. Select the Python interpreter from the `.venv` environment created above.
+   In VS Code, use **Python: Select Interpreter**; in PyCharm, select the
+   project interpreter in the Python interpreter settings.
+3. Run `main.py` with the IDE's **Run Python File** or **Run** action to
+   analyze the included example.
+
+For your own data, use the installed command with a parameter JSON rather than
+editing `main.py`. Review camera calibration, acquisition rate, temperature,
+viscosity, channel dimensions, ROI, and Trackpy settings in that JSON.
+
+## Run from a terminal
+
+Run an installed analysis from any folder in PowerShell:
+
+```powershell
+nanoobjectdetection `
+  --parameter-file "C:\data\parameter.json" `
+  --input-file "C:\data\my_stack.tif" `
+  --output-dir "C:\data\my_analysis" `
+  --processing-mode single_stack `
+  --background-stack-storage disk `
+  --processing-bit-depth 8
+```
+
+To install the package from another folder or drive, use its repository path:
+
+```powershell
+python -m pip install "D:\Python\NanoObjectDetection"
+```
+
+The source script can also be run with options from the repository folder:
+
+```powershell
+python .\main.py `
+  --input-file "C:\data\my_stack.tif" `
+  --output-dir "C:\data\my_analysis" `
+  --processing-mode single_stack `
+  --dimension 2d `
+  --background-stack-storage disk
+```
+
+To use a legacy-format parameter file:
+
+```powershell
+python .\main.py `
+  --parameter-file ".\example\parameter.json" `
+  --input-file ".\example\20_6µmKap_50Au_20_7C_100fps_5000fr_700us_V1j.tif" `
+  --output-dir ".\example\my_analysis" `
+  --processing-mode chunked
+```
+
+The input and output command-line paths override the corresponding paths in
+the parameter JSON. If `--parameter-file` is omitted, the analysis settings
+defined in `main.py` are used.
+
+Available command-line options:
+
+| Option | Purpose |
+|---|---|
+| `--processing-mode single_stack` | Read frames directly from the TIFF; this is the default. |
+| `--processing-mode chunked` | Store/process the selected stack in blocks, useful for large inputs. |
+| `--background-stack-storage memory` | Keep the background stack used for subtraction in RAM (default). |
+| `--background-stack-storage disk` | Use a temporary disk-backed stack; needs free space approximately equal to the selected-depth ROI stack. |
+| `--processing-bit-depth 16` | Preserve the input pixel values (default). |
+| `--processing-bit-depth 8` | For uint16 input, keep the high 8 bits (`value >> 8`) for stored/raw processing data; halves raw/background stack storage but discards low-bit precision. |
+| `--dimension all` | Analyze x, y, and 2d trajectories; this is the default. |
+| `--dimension x`, `--dimension y`, `--dimension 2d` | Calculate only the selected trajectory dimension. |
+| `--gpu` | Enable GPU preprocessing; requires compatible CuPy/CUDA installation. |
+| `--input-file PATH` | Select the TIFF stack to analyze. |
+| `--output-dir PATH` | Select where results are written. |
+| `--parameter-file PATH` | Load analysis settings from a legacy-format JSON file. |
+
+Disk-backed background storage preserves the same calculation as memory
+storage at the selected bit depth and removes its temporary stack file after
+localization. It can use more disk I/O and run more slowly than keeping the
+stack in RAM.
+
+8-bit processing is opt-in and quantizes uint16 values by shifting right eight
+bits; it is not equivalent to the default 16-bit analysis and can change
+background subtraction and particle detections. It reduces raw and background
+stack storage by about half, but not total process memory because processing
+also uses float32 working arrays. For uint8 TIFF input, this option leaves the
+pixel values unchanged.
+
+Chunking reduces localization working-block size, but does not make the exact
+stack-wide static-background calculation bounded-memory. When that
+preprocessing option is enabled, the selected ROI stack must fit in RAM even
+in chunked mode. Reduce the ROI or frame range if memory is insufficient.
+
+
+
+See the [2.0 documentation](./NANOOBJECTDETECTION_2_0_DOCUMENTATION.md) for
+the complete list of supported settings, generated files, assumptions, and
+known limitations.