Package sc.fiji.snt.tracing.auto

Class AbstractGWDTTracer<T extends net.imglib2.type.numeric.RealType<T>>

java.lang.Object
sc.fiji.snt.tracing.auto.AbstractAutoTracer
sc.fiji.snt.tracing.auto.AbstractGWDTTracer<T>
Type Parameters:
T - pixel type
All Implemented Interfaces:
AutoTracer
Direct Known Subclasses:
DiskBackedGWDTTracer, GWDTTracer, SparseGWDTTracer
public abstract class AbstractGWDTTracer<T extends net.imglib2.type.numeric.RealType<T>> extends AbstractAutoTracer
Abstract base class for GWDT-based tracers: APP2-style neuron tracer using Gray-Weighted Distance Transform and Fast Marching. The tree is built directly on the grayscale image using intensity-weighted paths.

Subclasses specify storage backend via createStorageBackend().

This implementation follows the APP2 algorithm:
  1. GWDT - Gray-weighted distance transform on grayscale (no binarization)
  2. Fast Marching - Build initial tree from seed using geodesic distance on GWDT
  3. Hierarchical Pruning - Long-segment-first with intensity-weighted coverage
Author:
Tiago Ferreira
See Also:

  • Field Details

    • FAR

      public static final byte FAR
      Fast Marching state: voxel has not yet been reached.
      See Also:

    • TRIAL

      public static final byte TRIAL
      Fast Marching state: voxel is in the narrow-band trial set.
      See Also:

    • ALIVE

      public static final byte ALIVE
      Fast Marching state: voxel distance has been finalized.
      See Also:

    • source

      protected final net.imglib2.RandomAccessibleInterval<T extends net.imglib2.type.numeric.RealType<T>> source

    • spacing

      protected final double[] spacing

    • dims

      protected final long[] dims

    • minBounds

      protected final long[] minBounds

    • maxBounds

      protected final long[] maxBounds

    • backgroundThreshold

      protected double backgroundThreshold

    • lengthThreshVoxels

      protected double lengthThreshVoxels

    • srRatio

      protected double srRatio

    • sphereOverlapThreshold

      protected double sphereOverlapThreshold

    • leafPruneOverlap

      protected double leafPruneOverlap

    • leafPruneEnabled

      protected boolean leafPruneEnabled

    • smoothEnabled

      protected boolean smoothEnabled

    • smoothWindowSize

      protected int smoothWindowSize

    • resampleEnabled

      protected boolean resampleEnabled

    • resampleStep

      protected double resampleStep

    • cnnType

      protected int cnnType

    • maxIntensity

      protected double maxIntensity

    • minIntensity

      protected double minIntensity

    • seedVoxel

      protected long[] seedVoxel

    • storage

      protected StorageBackend storage

  • Constructor Details

    • AbstractGWDTTracer

      public AbstractGWDTTracer(net.imglib2.RandomAccessibleInterval<T> source, double[] spacing)
      Creates a new GWDTTracer.
      Parameters:
      source - the grayscale image to trace
      spacing - voxel dimensions [x, y, z] in physical units

  • Method Details

    • createStorageBackend

      protected abstract StorageBackend createStorageBackend()
      Create the storage backend for this tracer. Subclasses override to specify array, sparse, or disk-backed storage.

    • getSpacing

      protected double[] getSpacing()
      Description copied from class: AbstractAutoTracer
      Gets the voxel spacing used by this tracer.
      Specified by:
      getSpacing in class AbstractAutoTracer
      Returns:
      array of [x, y, z] spacing values

    • getDimensions

      protected long[] getDimensions()
      Description copied from class: AbstractAutoTracer
      Gets the image dimensions.
      Specified by:
      getDimensions in class AbstractAutoTracer
      Returns:
      array of dimension sizes

    • createIsotropicSpacing

      protected static double[] createIsotropicSpacing(int nDims)

    • getSpacing

      protected static double[] getSpacing(ij.ImagePlus imp, int nDims)

    • setBackgroundThreshold

      public void setBackgroundThreshold(double threshold)
      Sets the background threshold. Pixels at or below this value are considered background. If negative (default), threshold is auto-computed as the image mean.

    • setSrRatio

      public void setSrRatio(double ratio)
      Sets the SR (Signal-to-Redundant) ratio threshold used in hierarchical pruning. Default: 3/9 = 0.333 Segments with signal/redundant >= this ratio are kept.

    • setMinSegmentLengthVoxels

      public void setMinSegmentLengthVoxels(double lengthInVoxels)
      Sets the minimum segment length in VOXEL units. Default: 2.0 Segments shorter than this are always pruned.

    • setMinSegmentLength

      public void setMinSegmentLength(double lengthInPhysicalUnits)
      Sets the minimum segment length in physical units. Internally converted to voxels using average spacing.

    • setSphereOverlapThreshold

      public void setSphereOverlapThreshold(double threshold)
      Sets the sphere overlap threshold for detecting redundant nodes during hierarchical pruning. When a node's sphere has more than this fraction covered by claimed nodes, it's considered redundant. Default: 0.4. Lower = more aggressive pruning.

    • setLeafPruneOverlap

      public void setLeafPruneOverlap(double threshold)
      Sets the leaf pruning overlap threshold. Leaves with more than this fraction overlapping parent are pruned. Default: 0.9

    • setLeafPruneEnabled

      public void setLeafPruneEnabled(boolean enabled)
      Enables or disables leaf pruning (both leaf and joint leaf). Default: true

    • setSmoothEnabled

      public void setSmoothEnabled(boolean enabled)
      Enables or disables curve smoothing. Default: true

    • setSmoothWindowSize

      public void setSmoothWindowSize(int windowSize)
      Sets the smoothing window size. Default: 5

    • setResampleEnabled

      public void setResampleEnabled(boolean enabled)
      Enables/disables resampling. Default: true

    • setResampleStep

      public void setResampleStep(double step)
      Sets the resampling step size in voxels. Default: 2.0 Points closer than this distance will be merged.

    • setConnectivityType

      public void setConnectivityType(int type)
      Sets the connectivity type for Fast Marching.

      3D images:

      • 1 = 6-connectivity (face neighbors)
      • 2 = 18-connectivity (face + edge neighbors) - default
      • 3 = 26-connectivity (face + edge + corner neighbors)
      2D images:
      • 1 = 4-connectivity (edge neighbors)
      • 2, 3 = 8-connectivity (edge + corner neighbors)
      Parameters:
      type - connectivity type (1, 2, or 3)

    • setAllowGap

      public void setAllowGap(boolean allow)
      Sets whether to allow bridging small intensity gaps.

      When enabled, fast marching can cross a single dark voxel to connect broken neurites. The crossing is only allowed if the current voxel is above threshold (i.e., we can step from bright → dark → bright, but not dark → dark).

      This is useful for images with fragmented signals or small imaging artifacts, but may falsely connect separate structures.

      Parameters:
      allow - true to allow crossing single dark voxels (default: false)

    • isAllowGap

      public boolean isAllowGap()
      Returns whether gap bridging is enabled.
      Returns:
      true if single dark voxels can be crossed during tracing

    • setSeed

      public void setSeed(long[] voxelCoords)
      Sets the seed point (soma location) in voxel coordinates. For 2D images, only x and y are used (z is ignored if provided).

    • setSeedPhysical

      public void setSeedPhysical(double[] physicalCoords)
      Sets the seed point in physical coordinates. For 2D images, only x and y are used (z is ignored if provided).

    • traceToGraph

      public DirectedWeightedGraph traceToGraph()
      Description copied from class: AbstractAutoTracer
      Traces the structure and returns a DirectedWeightedGraph.
      Specified by:
      traceToGraph in class AbstractAutoTracer
      Returns:
      the traced graph

    • runFastMarching

      protected void runFastMarching(double threshold, long seedIndex)
      Run Fast Marching using storage backend.

    • addNeighborsToHeap

      protected void addNeighborsToHeap(long[] pos, net.imglib2.RandomAccess<T> srcRA, PriorityQueue<long[]> heap, double threshold)
      Add neighbors to Fast Marching heap. Uses cached arrays to reduce allocations in hot path.

    • smoothCurve

      protected void smoothCurve(DirectedWeightedGraph graph, int windowSize)
      Smooths the final curve using a moving average filter.
      Parameters:
      graph - the graph to smooth
      windowSize - the smoothing window (default 5: 2 neighbors on each side)

    • recalculateRadiiFromImage

      protected void recalculateRadiiFromImage(DirectedWeightedGraph graph, double effectiveThreshold)
      Recalculates radii for all nodes using image-based method (like APP2). This is critical for accurate coverage detection during pruning.

    • darkNodeAndSegmentPruning

      protected void darkNodeAndSegmentPruning(DirectedWeightedGraph graph, double effectiveThreshold)
      APP2-style dark node and segment pruning.

      Phase 1: Dark Node Pruning (iterative) - For each leaf, if intensity <= background threshold, remove the leaf - Repeat until no more dark leaves found

      Phase 2: Dark Segment Pruning - For each terminal branch (path from leaf to branch point): - Delete if average intensity <= background threshold, OR - Delete if >= 20% of nodes are dark (intensity <= threshold)

    • hierarchicalPrune

      protected void hierarchicalPrune(DirectedWeightedGraph graph, double effectiveThreshold)
      Performs hierarchical pruning using intensity-weighted coverage.

      Algorithm: 1. Decompose tree into segments (paths between branch points) 2. Calculate segment length as SUM OF NORMALIZED INTENSITIES (not Euclidean!) 3. Sort segments by length (longest first) 4. For each segment, compute intensity-weighted coverage ratio using PIXEL MASK 5. If coverage > threshold, prune segment and children

    • computeIntensityWeightedJointCoverage

      protected double[] computeIntensityWeightedJointCoverage(SWCPoint node, net.imglib2.RandomAccess<net.imglib2.type.numeric.integer.UnsignedShortType> countRA, net.imglib2.RandomAccess<? extends net.imglib2.type.numeric.RealType<?>> srcRA)
      Computes INTENSITY-WEIGHTED joint coverage fraction (like APP2). Returns [coveredSig, totalSig] where coverage is weighted by image intensity.

    • computeIntensityRange

      protected void computeIntensityRange()
      Computes intensity range for GI normalization. APP2 uses actual image min/max, not threshold-based.

    • resampleCurve

      protected void resampleCurve(DirectedWeightedGraph graph, double stepSize)
      Resamples the curve to have evenly spaced points. Keeps branch points and endpoints, removes intermediate points that are too close.

    • getEffectiveThreshold

      protected double getEffectiveThreshold()

    • posToIndex

      protected long posToIndex(long[] pos)

    • posToIndex

      public static long posToIndex(long[] pos, long[] dims)
      Converts an N-dimensional position to a flat array index using row-major order.

    • indexToPos

      protected void indexToPos(long idx, long[] pos)
      Convert linear index to position, writing to provided array (avoids allocation).

    • nodeToVoxelPos

      protected void nodeToVoxelPos(SWCPoint node, long[] pos)
      Converts an SWCPoint's physical coordinates to voxel position. Handles both 2D and 3D images.
      Parameters:
      node - The SWCPoint with physical coordinates
      pos - Output array (must be dims.length size)

    • isInBounds

      protected boolean isInBounds(long[] pos)
      Checks if a voxel position is within image bounds. Uses ImgUtils.outOfBounds with cached interval bounds.

    • computeAverageSpacing

      protected double computeAverageSpacing()
      Computes average voxel spacing, handling both 2D and 3D images.

    • iterateNeighbors

      public static void iterateNeighbors(int[] delta, int dim, int nDims, Runnable action)
      Iterates over all neighbor offsets (26-connectivity in 3D).

    • trace

      public Tree trace()
      Traces the neuron and returns a Tree.
      Returns:
      the traced neuron morphology, or null if tracing fails

    • traceTrees

      public List<Tree> traceTrees()
      Traces the neuron and returns a list of Trees.

      With AutoTracer.ROI_EDGE strategy, returns separate trees for each neurite exiting the soma ROI. With other strategies, returns a single tree.

      Returns:
      list of traced trees, or empty list if tracing fails