Package sc.fiji.snt.tracing.auto

Class AbstractAutoTracer

java.lang.Object
sc.fiji.snt.tracing.auto.AbstractAutoTracer
All Implemented Interfaces:
AutoTracer
Direct Known Subclasses:
AbstractGWDTTracer
public abstract class AbstractAutoTracer extends Object implements AutoTracer
Abstract base class for grayscale-based automatic neuron tracers.

Provides common functionality for soma ROI handling, graph utilities, and tree construction. Subclasses implement specific tracing algorithms that operate directly on grayscale images without binarization.

Author:
Tiago Ferreira
See Also:

  • Field Details

    • somaRoi

      protected ij.gui.Roi somaRoi

    • somaRoiZPosition

      protected int somaRoiZPosition

    • rootStrategy

      protected int rootStrategy

    • logger

      protected Logger logger

    • verbose

      protected boolean verbose

  • Constructor Details

    • AbstractAutoTracer

      protected AbstractAutoTracer()
      Creates a new AbstractAutoTracer instance.

  • Method Details

    • findThickestPoint

      public static long[] findThickestPoint(net.imglib2.RandomAccessibleInterval<? extends net.imglib2.type.numeric.RealType<?>> source, double threshold, double[] spacing)
      Finds the thickest point in a foreground structure using the Euclidean Distance Transform (EDT). This is more robust than simply finding the brightest pixel because:
      • Hot pixels/artifacts are typically 1 voxel thick → small EDT value
      • The soma, being the thickest structure, has the largest EDT value
      • Less sensitive to intensity variations and uneven illumination
      Parameters:
      source - the input image
      threshold - pixels above this value are considered foreground
      spacing - voxel spacing [x, y, z] for proper distance calculation
      Returns:
      the position of the thickest point in voxel coordinates, or null if no foreground pixels exist

    • findThickestPointPhysical

      public static double[] findThickestPointPhysical(net.imglib2.RandomAccessibleInterval<? extends net.imglib2.type.numeric.RealType<?>> source, double threshold, double[] spacing)
      Finds the thickest point and converts to physical coordinates.
      Parameters:
      source - the input image
      threshold - pixels above this value are considered foreground
      spacing - voxel spacing [x, y, z]
      Returns:
      the position in physical coordinates, or null if no foreground

    • findRoot

      public static long[] findRoot(net.imglib2.RandomAccessibleInterval<? extends net.imglib2.type.numeric.RealType<?>> source, double threshold, double[] spacing)
      Automatically detects the most likely root point (soma center) in a neuronal image. This method uses a combined thickness-intensity approach that is robust to common imaging artifacts and variations in signal distribution. The algorithm:
      1. Computes a binary mask using the specified threshold
      2. Calculates the Euclidean Distance Transform (EDT) to find distance to background
      3. Scores each foreground pixel as: EDT_value × normalized_intensity
      4. Returns the position with the maximum score
      This combined scoring naturally favors the soma because:
      • Soma is typically the thickest structure → high EDT value
      • Soma usually has reasonable intensity → contributes to score
      • Hot pixels/artifacts are tiny → low EDT despite high intensity
      • Thin neurites have low EDT → low score even if bright
      Parameters:
      source - the input image (grayscale)
      threshold - pixels above this value are considered foreground. If NaN, the mean intensity is used. If negative, Otsu's method is applied.
      spacing - voxel spacing [x, y, z] for proper distance calculation. If null, isotropic spacing of 1.0 is assumed.
      Returns:
      the detected root position in voxel coordinates, or null if detection fails (e.g., no foreground pixels, empty image)
      See Also:

    • estimateBackgroundThreshold

      protected static double estimateBackgroundThreshold(net.imglib2.RandomAccessibleInterval<? extends net.imglib2.type.numeric.RealType<?>> source)
      Estimates background threshold using combined range and percentile heuristics.

      Averages two estimates:

      • 5% into intensity range (robust to camera offset)
      • 90th percentile (robust to signal density)
      Parameters:
      source - the input image
      Returns:
      estimated background threshold

    • findRootPhysical

      public static double[] findRootPhysical(net.imglib2.RandomAccessibleInterval<? extends net.imglib2.type.numeric.RealType<?>> source, double threshold, double[] spacing)
      Automatically detects the root point and returns physical coordinates.
      Parameters:
      source - the input image (grayscale)
      threshold - pixels above this value are considered foreground. If NaN, the mean intensity is used. If negative, Otsu's method is applied.
      spacing - voxel spacing [x, y, z] for proper distance calculation
      Returns:
      the detected root position in physical coordinates, or null if detection fails
      See Also:

    • findRoot

      public static long[] findRoot(net.imglib2.RandomAccessibleInterval<? extends net.imglib2.type.numeric.RealType<?>> source, double[] spacing)
      Automatically detects the root point using automatic thresholding (Otsu's method).

      Convenience method equivalent to findRoot(source, -1, spacing).

      Parameters:
      source - the input image (grayscale)
      spacing - voxel spacing [x, y, z]
      Returns:
      the detected root position in voxel coordinates, or null if detection fails
      See Also:

    • findRootPhysical

      public static double[] findRootPhysical(net.imglib2.RandomAccessibleInterval<? extends net.imglib2.type.numeric.RealType<?>> source, double[] spacing)
      Automatically detects the root point using automatic thresholding and returns physical coordinates.

      Convenience method equivalent to findRootPhysical(source, -1, spacing).

      Parameters:
      source - the input image (grayscale)
      spacing - voxel spacing [x, y, z]
      Returns:
      the detected root position in physical coordinates, or null if detection fails
      See Also:

    • traceToGraph

      public abstract DirectedWeightedGraph traceToGraph()
      Traces the structure and returns a DirectedWeightedGraph.
      Returns:
      the traced graph

    • getSpacing

      protected abstract double[] getSpacing()
      Gets the voxel spacing used by this tracer.
      Returns:
      array of [x, y, z] spacing values

    • getDimensions

      protected abstract long[] getDimensions()
      Gets the image dimensions.
      Returns:
      array of dimension sizes

    • setSomaRoi

      public void setSomaRoi(ij.gui.Roi roi, int strategy)
      Sets the soma ROI and rooting strategy.
      Parameters:
      roi - area ROI delineating the soma (null to disable)
      strategy - one of AutoTracer.ROI_UNSET, AutoTracer.ROI_EDGE (assumed area ROI), AutoTracer.ROI_CENTROID, or AutoTracer.ROI_CENTROID_WEIGHTED

    • setSomaRoiZPosition

      public void setSomaRoiZPosition(int z)
      Overrides the Z-position used to constrain the soma ROI. Set to a valid 0-indexed slice to restrict the ROI to that plane, or -1 to apply the ROI to all Z-slices.
      Parameters:
      z - the 0-indexed Z-slice, or -1 for all slices

    • getSomaRoi

      public ij.gui.Roi getSomaRoi()
      Gets the current soma ROI.
      Returns:
      the soma ROI, or null if not set

    • setSomaRoi

      public void setSomaRoi(ij.gui.Roi roi)
      Sets the soma ROI using the default strategy (ROI_CENTROID).
      Parameters:
      roi - area ROI delineating the soma

    • getRootStrategy

      public int getRootStrategy()
      Gets the current root strategy.
      Returns:
      the root strategy constant

    • isVerbose

      public boolean isVerbose()
      Checks if verbose logging is enabled.
      Returns:
      true if verbose

    • setVerbose

      public void setVerbose(boolean verbose)
      Sets verbose logging mode.
      Parameters:
      verbose - true to enable verbose logging

    • isInsideSomaRoi

      protected boolean isInsideSomaRoi(SWCPoint point)
      Checks if a point is inside the soma ROI.
      Parameters:
      point - the point to check (physical coordinates)
      Returns:
      true if inside the ROI

    • splitAtSomaBoundary

      protected List<Tree> splitAtSomaBoundary(DirectedWeightedGraph graph)
      Splits a graph at the soma boundary, creating separate trees for each neurite.
      Parameters:
      graph - the traced graph
      Returns:
      list of trees, one per neurite exiting the soma

    • collapseSomaToRoiCentroid

      protected void collapseSomaToRoiCentroid(DirectedWeightedGraph graph)
      Collapses all soma nodes to the geometric ROI centroid.
      Parameters:
      graph - the graph to modify

    • collapseSomaToWeightedCentroid

      protected void collapseSomaToWeightedCentroid(DirectedWeightedGraph graph)
      Collapses all soma nodes to their weighted centroid.
      Parameters:
      graph - the graph to modify

    • collapseSomaNodes

      protected void collapseSomaNodes(DirectedWeightedGraph graph, double cx, double cy, double cz)
      Core method to collapse soma nodes to a centroid.

    • findGraphRoot

      protected SWCPoint findGraphRoot(DirectedWeightedGraph graph)
      Finds the root node of a graph.
      Parameters:
      graph - the graph
      Returns:
      the root node, or null if graph is empty

    • removeDisconnectedComponents

      protected void removeDisconnectedComponents(DirectedWeightedGraph graph)
      Removes all vertices not connected to the root.
      Parameters:
      graph - the graph to clean

    • computeAverageRadius

      protected double computeAverageRadius(Set<SWCPoint> nodes)
      Computes average radius of a set of nodes.

    • setStatusListener

      public void setStatusListener(Consumer<String> listener)
      Sets a listener that receives short status messages at each major phase of the tracing pipeline (e.g. "Computing distance transform..."). Useful for updating UI labels or progress indicators.
      Parameters:
      listener - the status consumer, or null to clear

    • status

      protected void status(String message)
      Sends a status message to the registered listener, if any.
      Parameters:
      message - the status message

    • log

      protected void log(String message)
      Logs a message if verbose mode is enabled.