Package sc.fiji.snt.tracing.auto

Class BinaryTracer

java.lang.Object
sc.fiji.snt.tracing.auto.BinaryTracer
All Implemented Interfaces:
AutoTracer
public class BinaryTracer extends Object implements AutoTracer
Class for generation of Trees from a skeletonized image.
Author:
Cameron Arshadi, Tiago Ferreira
See Also:
  • Skeletonize3D_
  • AnalyzeSkeleton_

  • Field Details

    • LOWEST_INTENSITY_BRANCH

      public static final int LOWEST_INTENSITY_BRANCH
      Pruning mode: flag for lowest intensity branch pruning
      See Also:

    • LOWEST_INTENSITY_VOXEL

      public static final int LOWEST_INTENSITY_VOXEL
      Pruning mode: flag for lowest pixel intensity pruning. Requires access to a reference grayscale image for voxel intensities lookup
      See Also:

    • SHORTEST_BRANCH

      public static final int SHORTEST_BRANCH
      Pruning mode: flag for shortest branch pruning
      See Also:

    • SHORTEST_EDGE

      public static final int SHORTEST_EDGE
      Pruning mode: flag for shortest edge pruning (preserves longest paths). In this mode, cycles in the skeleton graph are broken by removing the shortest edges, ensuring that the longest continuous paths are retained in the final structure.
      See Also:

    • PERIPHERAL_SEGMENTS

      public static final int PERIPHERAL_SEGMENTS
      Pruning mode: flag for lowest centrality edge pruning (preserves backbone). In this mode, cycles in the skeleton graph are broken by removing edges with lowest betweenness centrality, so that the most presumable topologically important paths (main "trunks") are retained in the final structure.
      See Also:

    • MOST_DISTAL

      public static final int MOST_DISTAL
      Pruning mode: flag for most distal edge pruning (preserves proximal structure). In this mode, cycles in the skeleton graph are broken by removing edges furthest from the root, ensuring that proximal structures (closer to root) are retained in the final structure. Useful when loops near the root are more likely to be biologically meaningful than distal ones. Note: Requires a root to be defined via setRootRoi(Roi, int).
      See Also:

  • Constructor Details

    • BinaryTracer

      public BinaryTracer(net.imagej.ImgPlus<T> imgPlus)
      Parameters:
      imgPlus - The image to be parsed. Will be converted to a topological skeleton (assuming non-zero foreground)

    • BinaryTracer

      public BinaryTracer(ij.ImagePlus imagePlus)
      Parameters:
      imagePlus - The image to be parsed. Will be converted to a topological skeleton (assuming non-zero foreground)

    • BinaryTracer

      public BinaryTracer(ij.ImagePlus imagePlus, boolean skeletonize) throws IllegalArgumentException
      Parameters:
      imagePlus - The image to be parsed. It is expected to be binary (non-zero foreground).
      skeletonize - If true, image will be skeletonized using Skeletonize3D_ _in place_ prior to the analysis. Conversion will be nonsensical if false and imagePlus is not a topological skeleton
      Throws:
      IllegalArgumentException - if skeletonize is true and imagePlus is not binary.

    • BinaryTracer

      public BinaryTracer(ij.ImagePlus imagePlus, int frame)
      Parameters:
      imagePlus - The (timelapse) image to be parsed. It is expected to be binary (non-zero foreground).
      frame - The frame of the timelapse image to be parsed
      Throws:
      IllegalArgumentException - If image is not binary imagePlus is not binary.

  • Method Details

    • skeletonize

      public static void skeletonize(ij.ImagePlus imp, double lowerThreshold, double upperThreshold, boolean erodeIsolatedPixels)
      Convenience method to skeletonize an image using Skeletonize3D_.
      Parameters:
      imp - The image to be skeletonized. All non-zero values are considered to be foreground.
      lowerThreshold - intensities below this value will be set to zero, and will not contribute to the skeleton. Ignored if > 0
      upperThreshold - intensities above this value will be set to zero, and will not contribute to the skeleton. Ignored if < 0
      erodeIsolatedPixels - If true, any isolated pixels (single point skeletons) that may be formed after skeletonization are eliminated by erosion.

    • skeletonize

      public static void skeletonize(ij.ImagePlus imp, boolean erodeIsolatedPixels)
      Convenience method to skeletonize a thresholded image using Skeletonize3D_.
      Parameters:
      imp - The thresholded image to be skeletonized. If the image is not thresholded all non-zero values are considered to be foreground.
      erodeIsolatedPixels - If true, any isolated pixels (single point skeletons) that may be formed after skeletonization are eliminated by erosion.

    • skeletonizeTimeLapse

      public static void skeletonizeTimeLapse(ij.ImagePlus imp, boolean erodeIsolatedPixels)
      Convenience method to skeletonize a thresholded time-lapse using Skeletonize3D_.
      Parameters:
      imp - The timelapse to be skeletonized. If the image is not thresholded all non-zero values are considered to be foreground.
      erodeIsolatedPixels - If true, any isolated pixels (single point skeletons) that may be formed after skeletonization are eliminated by erosion.

    • getTrees

      public List<Tree> getTrees()
      Generates a list of Trees from the skeleton image. Each Tree corresponds to one connected component of the graph returned by SkeletonResult.getGraph().
      Returns:
      the skeleton tree list

    • getSingleTree

      public Tree getSingleTree()
      Generates a single Tree from getSingleGraph(). If a ROI-based centroid has been set, Root is converted to a single node, root path with radius set to that of a circle with the same area of root-defining soma.
      Returns:
      the single tree
      See Also:

    • getGraphs

      public List<DirectedWeightedGraph> getGraphs()
      Generates a list of DirectedWeightedGraphs from the skeleton image. Each graph corresponds to one connected component of the graph returned by SkeletonResult.getGraph().
      Returns:
      the list of skeletonized graphs

    • getSingleGraph

      public DirectedWeightedGraph getSingleGraph() throws IllegalArgumentException
      Generates a single DirectedWeightedGraphs by combining getGraphs()'s list into a single, combined graph. Typically, this method assumes that the skeletonization handles a known single component (e.g., an image of a single cell). If multiple graphs() do exist, this method requires that setRootRoi(Roi, int) has been called using AutoTracer.ROI_CENTROID or AutoTracer.ROI_CENTROID_WEIGHTED.
      Returns:
      the single graph
      Throws:
      IllegalArgumentException

    • setRootRoi

      public void setRootRoi(ij.gui.Roi roi, int strategy)
      Sets the Roi enclosing the nodes to be set as root(s) in the final graphs. Must be called before retrieval of any converted data.
      Parameters:
      roi - The area enclosing the components defining the root(s) of the skeletonized structures. Typically, this will correspond to an area ROI delineating the soma. Note that by default ImageJ ROIs do not carry depth information, so if you would like to restrain the delineation to a single plane, be sure to call Roi.setPosition(int, int, int) beforehand.
      strategy - the strategy for root placement: Either AutoTracer.ROI_CENTROID, AutoTracer.ROI_CENTROID_WEIGHTED, AutoTracer.ROI_CONTAINED, AutoTracer.ROI_EDGE, or AutoTracer.ROI_UNSET

    • honoredSeedRoles

      public EnumSet<AutoTracer.SeedRole> honoredSeedRoles()
      Binary tracers currently consume only the AutoTracer.SeedRole.ROOT role. Future iterations may add AutoTracer.SeedRole.TIP / AutoTracer.SeedRole.WAYPOINT to constrain skeleton traversal.
      Specified by:
      honoredSeedRoles in interface AutoTracer
      Returns:
      the AutoTracer.SeedRoles this tracer actually honors. Callers (e.g. an "Autotrace from Seeds" wrapper command) can use this to gate UI choices and to error early when the user picks a role the tracer ignores. Default: empty set.

    • setRoots

      public void setRoots(Collection<SeedPoint> seeds)
      Sets the run's root from a collection of seeds. v1 takes the first seed and bridges to the existing setRootRoi(Roi, int) API by synthesizing an oval ROI around the seed (diameter derived from SeedPoint.radius, with a minimum of one voxel when radius is unset) and using AutoTracer.ROI_CENTROID placement. Any additional seeds are ignored; the wrapper command is expected to iterate one tracer run per seed.
      Specified by:
      setRoots in interface AutoTracer
      Parameters:
      seeds - candidate roots; null/empty is a silent no-op

    • setOrigIP

      public void setOrigIP(ij.ImagePlus origIP)
      Sets the original ImagePlus to be used during voxel-based loop pruning. See AnalyzeSkeleton documentation

      Specifies the original (non-skeletonized) image to be used during skeleton analysis for additional processing options.

      Parameters:
      origIP - the original ImagePlus
      See Also:
      • AnalyzeSkeleton_.run(int, boolean, boolean, ImagePlus, boolean, boolean)

    • getRootRoiStrategy

      public int getRootRoiStrategy()
      Gets the current root ROI strategy.

      Returns the strategy used for handling root ROIs during skeleton conversion. If no root ROI is set, returns ROI_UNSET.

      Returns:
      the root ROI strategy constant
      See Also:

    • getPruneMode

      public int getPruneMode()
      Gets the loop pruning strategy.
      See Also:

    • setPruneMode

      public void setPruneMode(int pruneMode)
      Sets the loop pruning strategy.
      Parameters:
      pruneMode - the loop prune strategy, e.g., SHORTEST_BRANCH, LOWEST_INTENSITY_BRANCH, LOWEST_INTENSITY_VOXEL, PERIPHERAL_SEGMENTS, MOST_DISTAL, or SHORTEST_EDGE
      See Also:
      • AnalyzeSkeleton_.run(int, boolean, boolean, ImagePlus, boolean, boolean)

    • setPruneEnds

      public void setPruneEnds(boolean pruneEnds)
      Sets whether to prune end branches during skeleton analysis.

      Controls whether terminal branches should be pruned during the skeleton analysis process.

      Parameters:
      pruneEnds - true to prune end branches, false otherwise
      See Also:
      • AnalyzeSkeleton_.run(int, boolean, boolean, ImagePlus, boolean, boolean)

    • setShortestPath

      public void setShortestPath(boolean shortestPath)
      Sets whether to calculate the longest shortest-path in the skeleton result.
      Parameters:
      shortestPath - true to calculate shortest paths, false otherwise
      See Also:
      • AnalyzeSkeleton_.run(int, boolean, boolean, ImagePlus, boolean, boolean)

    • setSilent

      public void setSilent(boolean silent)
      Sets whether to run skeleton analysis in silent mode.

      Setting this to false will display both the tagged skeleton image and the shortest path image (if the shortest path calculation is enabled).

      Parameters:
      silent - true for silent operation, false for debug output
      See Also:
      • AnalyzeSkeleton_.run(int, boolean, boolean, ImagePlus, boolean, boolean)

    • setVerbose

      public void setVerbose(boolean verbose)
      Sets whether to run skeleton analysis in verbose mode.

      Controls whether the skeleton analysis should provide detailed output messages during processing.

      Parameters:
      verbose - true for verbose output, false for normal output
      See Also:
      • AnalyzeSkeleton_.run(int, boolean, boolean, ImagePlus, boolean, boolean)

    • setPruneByLength

      public void setPruneByLength(boolean pruneByLength)
      Sets whether to prune components below a threshold length from the result.

    • setLengthThreshold

      public void setLengthThreshold(double lengthThreshold)
      Sets the minimum component length necessary to avoid pruning. This value is only used if pruneByLength is true.

      Specifies the minimum length below which skeleton components will be pruned from the result. Negative values are set to 0.

      Parameters:
      lengthThreshold - the minimum length threshold
      See Also:

    • setConnectComponents

      public void setConnectComponents(boolean connectComponents)
      Sets whether to connect nearby skeleton components.

      Controls whether disconnected skeleton components should be connected if they are within the maximum connection distance.

      Parameters:
      connectComponents - true to connect components, false otherwise
      See Also:

    • setMaxConnectDist

      public void setMaxConnectDist(double maxConnectDist)
      Sets the maximum distance for connecting skeleton components.

      Specifies the maximum distance within which disconnected skeleton components will be connected. Values ≤ 0 are set to Double.MIN_VALUE.

      Parameters:
      maxConnectDist - the maximum connection distance
      See Also:

    • traceTrees

      public List<Tree> traceTrees()
      Description copied from interface: AutoTracer
      Traces the neuronal structure and returns a list of Trees.
      Specified by:
      traceTrees in interface AutoTracer
      Returns:
      list of traced trees, or empty list if tracing fails

    • main

      public static void main(String[] args)