Package sc.fiji.snt

Class Path

java.lang.Object
sc.fiji.snt.Path
All Implemented Interfaces:
Cloneable, Comparable<Path>
public class Path extends Object implements Comparable<Path>, Cloneable
This class represents a traced segment (i.e., a Path) in a reconstruction. It has methods to manipulate its points (nodes) with sup-pixel accuracy, including drawing them onto threePane-style canvases, etc.

Paths are non-branching sequences of adjacent points (including diagonals) in the image. Branches and joins are supported by attributes of paths that specify that they begin on (or end on) other paths.

In SNT, a Path can exist in two versions or flavors: itself and a fitted version generated by PathFitter. Because fitting may fail around certain nodes, the fitted version may have a different number of nodes relatively to its non-fitted version

  • Field Details

  • Constructor Details

    • Path

      public Path()
      Instantiates a new path under default settings (isotropic 1um pixel spacing)

    • Path

      public Path(double x_spacing, double y_spacing, double z_spacing, String spacing_units)
      Instantiates a new path.
      Parameters:
      x_spacing - Pixel width in spacing_units
      y_spacing - Pixel height in spacing_units
      z_spacing - Pixel depth in spacing_units
      spacing_units - the length unit in physical world units (typically "um").

  • Method Details

    • compareTo

      public int compareTo(Path o)
      Specified by:
      compareTo in interface Comparable<Path>

    • getID

      public int getID()
      Gets the identifier of this Path
      Returns:
      the identifier

    • getTreeID

      public int getTreeID()
      Gets the identifier of the Tree associated to this Path (if any).
      Returns:
      the Tree identifier

    • setIDs

      protected void setIDs(int pathID, int treeID)

    • setTreeLabel

      protected void setTreeLabel(String treeLabel)

    • getTreeLabel

      public String getTreeLabel()

    • setCanvasOffset

      public void setCanvasOffset(PointInCanvas canvasOffset)
      Specifies a translation offset when rendering this Path in a TracerCanvas. Path coordinates remain unaltered.
      Parameters:
      canvasOffset - the x,y,z coordinates (pixel-based) specifying the translation offset

    • getCanvasOffset

      public PointInCanvas getCanvasOffset()
      Returns the translation offset used to render this Path in a TracerCanvas.
      Returns:
      the rendering offset (in pixel coordinates)

    • getParentPath

      public Path getParentPath()
      Gets the parent path that this path branches from.

      Returns the path from which this path originates as a branch. For primary (root) paths, this method returns null since they don't branch from any other path. The parent-child relationship is established when a path is created as a branch using setBranchFrom(Path, PointInImage).

      Returns:
      the parent path, or null if this is a primary (root) path
      See Also:

    • getStartJoins

      @Deprecated public Path getStartJoins()
      Deprecated.
      use getParentPath() instead

    • getBranchPoint

      public PointInImage getBranchPoint()
      Gets the branch point (junction) where this path starts, i.e., connects to its parent path.
      Returns:
      the start junction point, or null if this is a primary path
      See Also:

    • getBranchPointDisplay

      protected PointInImage getBranchPointDisplay()
      Returns the branch point as it should be rendered on screen. When the parent path is displayed as its fitted version, returns the fitted node so the connection line matches the visual representation. Otherwise identical to getBranchPoint().
      Returns:
      the display branch point, or null if this is a primary path

    • getBranchPointIndex

      public int getBranchPointIndex()
      Gets the index of the branch point in the parent path.
      Returns:
      the branch point index, or -1 if this is a primary path

    • getStartJoinsPoint

      @Deprecated public PointInImage getStartJoinsPoint()
      Deprecated.
      Use getBranchPoint() instead.

      NB: Earlier versions of Simple Neurite Tracer allowed paths to connect at either the start point (getStartJoinsPoint()) or end-point (getStartJoinsPoint()). Useful for some applications but a huge headache to handle.

    • setName

      public void setName(String newName)
      Sets this Path's name. Set it to null or "", to reset it to the default.
      Parameters:
      newName - the new name.
      See Also:

    • getName

      public String getName()
      Gets this Path's name.
      Returns:
      the name. If no name as been set, the default name is returned.
      See Also:

    • pathsToIDListString

      protected static String pathsToIDListString(ArrayList<Path> a)

    • somehowJoinsAsString

      protected String somehowJoinsAsString()

    • childrenAsString

      protected String childrenAsString()

    • setChildren

      protected void setChildren(Set<Path> pathsLeft)

    • getContraction

      public double getContraction()
      Returns the ratio between the "Euclidean distance" of this path and its length. The Euclidean distance of this path is defined as the distance between this Path's start and end point.
      Returns:
      the Contraction of this Path, or NaN if this Path has no length

    • getFractalDimension

      public double getFractalDimension()
      Gets the fractal dimension of this path.
      Returns:
      the fractal dimension of this path or Double.NaN if this path has less than 5 nodes

    • getLength

      public double getLength()
      Gets the length of this Path
      Returns:
      the length of this Path

    • getAngle

      public double getAngle(int nodeIndex)
      Computes the angle between the specified node and its two flanking neighbors.

      With B being the specified node, A its previous neighbor, and C is next neighbor, computes the angle between the vectors AB, and BC.

      Returns:
      the angle in degrees (0-360 range) or Double.NaN if specified node does not have sufficient neighbors

    • getExtensionAngleXY

      public double getExtensionAngleXY()
      Returns the overall extension angle of this path in the XY plane. The angle is obtained from the slope of a linear regression across all the path nodes.
      Returns:
      the overall 'extension' angle in degrees [0-360[ of this path in the XY plane.

    • getExtensionAngleXZ

      public double getExtensionAngleXZ()
      Returns the overall extension angle of this path in the XZ plane. The angle is obtained from the slope of a linear regression across all the path nodes.
      Returns:
      the overall 'extension' angle in degrees [0-360[ in the XZ plane or NaN if path is 2D.

    • getExtensionAngleZY

      public double getExtensionAngleZY()
      Returns the overall extension angle of this path in the ZY plane. The angle is obtained from the slope of a linear regression across all the path nodes.
      Returns:
      the overall 'extension' angle in degrees [0-360[ in the ZY plane or NaN if path is 2D.

    • getInitialDirection

      public double[] getInitialDirection(int maxNodes)
      Returns a (non-normalized) direction vector from the first node to the node at index min(maxNodes, size()-1). This is useful for measuring the initial heading of a child path near a fork point.
      Parameters:
      maxNodes - the maximum node index to use as the end point
      Returns:
      a 3-element array [dx, dy, dz], or null if the path has fewer than 2 nodes or the resulting vector is zero-length

    • getExtensionDirection3D

      public org.jogamp.vecmath.Vector3d getExtensionDirection3D()
      Returns the 3D extension direction vector of this path using linear regression. The vector represents the overall direction from start to end of the path, fitted through all its nodes.
      Returns:
      the normalized Vector3d (length of 1) representing the extension direction, or null if path has only one point

    • getExtensionAngle3D

      public double getExtensionAngle3D(boolean relative)
      Returns either the compass bearing or the relative branching angle of this path's 3D extension direction.
      Parameters:
      relative - determines the calculation mode: - false: returns compass bearing in XY plane (absolute angle) - true: returns angle relative to parent path (relative angle)
      Returns:
      when relative=false: compass bearing in degrees (0-360°) using navigation convention: 0° = North (negative Y direction in image coordinates), 90° = East (positive X direction), 180° = South (positive Y direction in image coordinates), 270° = West (negative X direction). The 3D direction vector is projected onto the XY plane for compass calculation.

      When relative=true: acute angle in degrees (0-180°) between this path's 3D direction vector and its parent path's 3D direction vector. This measures the true 3D branching angle, not just the XY projection.

      Returns Double.NaN if: - Path has only one point (cannot determine direction) - relative=true and path has no parent (startJoins is null) - relative=true and parent path has no direction (single point parent)

      See Also:

    • getExtensionAngles3D

      public double[] getExtensionAngles3D()
      Returns the complete 3D orientation of this path's extension direction as spherical coordinates using navigation/compass convention.

      This method provides both horizontal direction (azimuth) and vertical inclination (elevation) of the path's overall extension direction.

      Returns:
      double array containing [azimuth, elevation] in degrees, where:

      azimuth (index 0): Compass bearing in XY plane (0-360°) following navigation convention:

      • 0° = North (negative Y direction in image coordinates)
      • 90° = East (positive X direction)
      • 180° = South (positive Y direction in image coordinates)
      • 270° = West (negative X direction)

      elevation (index 1): Vertical angle from XY plane (-90° to +90°):

      • 0° = horizontal (parallel to XY plane)
      • +90° = pointing straight up (positive Z direction)
      • -90° = pointing straight down (negative Z direction)

      Returns null if path has only one point or extension direction cannot be determined

      See Also:

    • getExtensionAngle3D

      public double getExtensionAngle3D(org.jogamp.vecmath.Vector3d referenceVector)
      Returns a single angle representing the 3D extension direction. This is the angle between the path's direction vector and a reference vector.
      Parameters:
      referenceVector - the reference vector to measure angle from (e.g., new Vector3d(0, 0, 1) for vertical reference, or new Vector3d(1, 0, 0) for horizontal)
      Returns:
      the acute angle in degrees (0-180°), or Double.NaN if path has only one point

    • getExtensionAngleFromVertical

      public double getExtensionAngleFromVertical()
      Returns the angle between the path's 3D direction and the vertical axis.
      Returns:
      angle from vertical in degrees (0° = vertical, 90° = horizontal), or Double.NaN if path has only one point, or 90° if path is 2D

    • getExtensionAngleFromHorizontal

      public double getExtensionAngleFromHorizontal()
      Returns the angle between the path's 3D direction and the horizontal axis.
      Returns:
      angle from horizontal in degrees (09° = vertical, 0° = horizontal), or Double.NaN if path has only one point.

    • getRealLengthString

      protected String getRealLengthString()

    • createCircles

      @Deprecated public void createCircles()
      Deprecated.
      No longer needed - radii and tangents are now stored per-node

    • setIsPrimary

      protected void setIsPrimary(boolean primary)

    • isPrimary

      public boolean isPrimary()
      Checks if this Path is root.
      Returns:
      true, if is primary (root)

    • disconnectFromAll

      protected void disconnectFromAll()

    • setBranchFrom

      public void setBranchFrom(Path parentPath, PointInImage branchPoint)
      Establishes this path as a child path originating from the specified parent path.

      In detail:

      • Sets the parent path that this path branches from
      • Records the exact point where branching occurs
      • Adds this path to the parent's children collection
      • Updates this path's order to be parent order + 1
      • Maintains bidirectional references for tree traversal
      Parameters:
      parentPath - the parent path that this path branches from. Must not be null. Some operations may expect it to be an existing path in the same tree structure
      branchPoint - the exact 3D coordinate where this path branches from the parent. Must not be null and should correspond to a location on or near the parent path
      Throws:
      IllegalArgumentException - if parentPath is null
      IllegalArgumentException - if this path already has a parent (use detachFromParent() first to detach)
      See Also:

    • setStartJoin

      @Deprecated public void setStartJoin(Path parentPath, PointInImage branchPoint)
      Deprecated.
      use setBranchFrom(Path, PointInImage) instead

    • replaceNodesWithFittedVersion

      protected void replaceNodesWithFittedVersion()

    • rebuildConnectionsOfFittedVersion

      protected void rebuildConnectionsOfFittedVersion()

    • unsetStartJoin

      @Deprecated public void unsetStartJoin()
      Deprecated.

    • detachFromParent

      public void detachFromParent()
      Detaches this path from its parent, converting it into an independent primary path.

      Removes the parent-child relationship established by setBranchFrom(Path, PointInImage) In

      • Clears the parent path reference and branch point
      • Removes this path from the parent's children collection
      • Updates bidirectional references for tree traversal
      • Resets the path order to -1 (no hierarchical position)
      • Converts this path from a branch to a primary path
      Throws:
      IllegalArgumentException - if this path has no parent (i.e., is already a primary path). Use getParentPath() to check before calling this method.
      See Also:

    • getMinimumSeparation

      public double getMinimumSeparation()

    • size

      public int size()
      Returns the number of nodes of this path
      Returns:
      the size, i.e., number of nodes

    • getNodes

      public List<PointInImage> getNodes()
      Gets all nodes as a list.
      Returns:
      a new list containing all nodes

    • getPointDouble

      protected void getPointDouble(int i, double[] p)

    • getNode

      public Path.PathNode getNode(int pos) throws IndexOutOfBoundsException
      Gets the node at the specified position.
      Parameters:
      pos - the position index (0-based). NB: You can use -1 to retrieve the last node in the Path
      Returns:
      the node
      Throws:
      IndexOutOfBoundsException - if position is out-of-range

    • getNode

      protected Path.PathNode getNode(String filter)

    • getNodeWithoutChecks

      protected Path.PathNode getNodeWithoutChecks(int pos)
      Gets the internal PathNode at the specified position (for advanced operations).

    • getNodeWithChecks

      protected Path.PathNode getNodeWithChecks(int pos)
      Gets the internal PathNode at the specified position (for advanced operations).

    • getPointInCanvas

      public PointInCanvas getPointInCanvas(int node)

    • getPointInCanvas2D

      protected PointInCanvas getPointInCanvas2D(int node, TracerCanvas canvas)

    • getUnscaledNodesInViewPort

      protected List<PointInCanvas> getUnscaledNodesInViewPort(TracerCanvas canvas)

    • containsUnscaledNodesInViewPort

      protected boolean containsUnscaledNodesInViewPort(TracerCanvas canvas)

    • contains

      public boolean contains(PointInImage pim)
      Check whether this Path contains the specified point
      Parameters:
      pim - the PointInImage node
      Returns:
      true, if successful

    • insertNode

      public void insertNode(int index, PointInImage point)
      Inserts a node at a specified position.
      Parameters:
      index - the (zero-based) index of the position of the new node
      point - the node to be inserted
      Throws:
      IllegalArgumentException - if index is out-of-range

    • insertNode

      public void insertNode(int index, SNTPoint point)
      Inserts a node at the specified position.
      Parameters:
      index - the position at which the node is to be inserted
      point - the node to be inserted
      Throws:
      IllegalArgumentException - if index is out-of-range

    • removeNode

      public void removeNode(int index)
      Removes the specified node if this path has at least two nodes. Does nothing if this is a single point path.
      Parameters:
      index - the zero-based index of the node to be removed
      Throws:
      IllegalArgumentException - if index is out-of-range

    • moveNode

      public void moveNode(int index, PointInImage destination)
      Assigns a new location to the specified node.
      Parameters:
      index - the zero-based index of the node to be modified
      destination - the new node location
      Throws:
      IllegalArgumentException - if index is out-of-range

    • moveNode

      public void moveNode(int index, double x, double y, double z)
      Assigns a new location to the specified node using raw coordinates. This is a performance-optimized version of moveNode(int, PointInImage) that avoids object allocation.
      Parameters:
      index - the index of the node to move
      x - the new x coordinate
      y - the new y coordinate
      z - the new z coordinate
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • brushMove

      protected void brushMove(int center, int radius, double dx, double dy, double dz)
      Applies a cosine-squared-weighted displacement to nodes around a center index. Used by paint-mode brush editing for efficient batch node movement.
      Parameters:
      center - the index of the node under the cursor
      radius - how many flanking nodes on each side to affect
      dx - displacement in x (calibrated units)
      dy - displacement in y
      dz - displacement in z

    • brushBlendRadii

      protected void brushBlendRadii(int center, int radius)
      Smears the center node's radius to flanking nodes using cosine^2-weighted interpolation. Each affected node's radius is pulled toward the center node's radius proportionally to the brush weight.
      Parameters:
      center - the index of the center node (source radius)
      radius - the brush radius in node indices

    • getNodeIndex

      public int getNodeIndex(PointInImage pim)
      Gets the first node index associated with the specified image coordinates. Returns -1 if no such node was found.
      Parameters:
      pim - the image position (calibrated coordinates)
      Returns:
      the index of the first node occurrence or -1 if there is no such occurrence

    • nearestNodeTo

      public PointInImage nearestNodeTo(PointInImage node, double within)
      Gets the closest node associated with the specified node.
      Parameters:
      node - location to be searched for
      within - sets the search sensitivity. E.g., Setting it to Double.MAX_VALUE (or the image's largest dimension) will always return a valid node.
      Returns:
      the closest node to the specified one or null if no such node was found.

    • indexNearestTo

      public int indexNearestTo(double x, double y, double z, double within)
      Gets the index of the closest node associated with the specified world coordinates.
      Parameters:
      x - the x-coordinates (spatially calibrated image units)
      y - the y-coordinates (spatially calibrated image units)
      z - the z-coordinates (spatially calibrated image units)
      within - sets the search sensitivity. E.g., Setting it to Double.MAX_VALUE (or the image's largest dimension) will always return a valid index.
      Returns:
      the index of the closest node to the specified coordinates. Returns -1 if no such node was found.

    • indexNearestToCanvasPosition2D

      protected int indexNearestToCanvasPosition2D(double xInCanvas, double yInCanvas, double withinPixels)

    • indexNearestTo

      protected int indexNearestTo(double x, double y, double z)

    • indexNearestToUnscaled

      public int indexNearestToUnscaled(double x, double y, double z, double within)
      Returns the index of the node nearest to the specified position in pixel (unscaled) coordinates. This is useful when matching ROI positions (which are always in pixel coordinates) to path nodes. Canvas offsets are handled automatically.
      Parameters:
      x - the x-coordinate in pixel units
      y - the y-coordinate in pixel units
      z - the z-coordinate in pixel units (0-based slice index)
      within - the search radius in pixel units. Only nodes within this distance are considered. Use Double.MAX_VALUE to always return the closest node regardless of distance.
      Returns:
      the index of the closest node, or -1 if no node was found within the specified radius
      See Also:

    • indexNearestToUnscaled

      public int indexNearestToUnscaled(double x, double y, double z)
      Returns the index of the node nearest to the specified position in pixel (unscaled) coordinates, searching across all nodes regardless of distance.
      Parameters:
      x - the x-coordinate in pixel units
      y - the y-coordinate in pixel units
      z - the z-coordinate in pixel units (0-based slice index)
      Returns:
      the index of the closest node
      See Also:

    • getEditableNodeIndex

      public int getEditableNodeIndex()
      Gets the position of the node tagged as 'editable', if any.
      Returns:
      the index of the point currently tagged as editable, or -1 if no such point exists

    • setEditableNode

      public void setEditableNode(int index)
      Tags the specified point position as 'editable'.
      Parameters:
      index - the index of the point to be tagged. Set it to -1 to for no tagging

    • isBeingEdited

      protected boolean isBeingEdited()

    • isEditableNodeLocked

      protected boolean isEditableNodeLocked()

    • setEditableNodeLocked

      protected void setEditableNodeLocked(boolean editableNodeLocked)

    • getXUnscaled

      public int getXUnscaled(int i)
      Returns the unscaled X position of a node.
      Parameters:
      i - the index of the path node
      Returns:
      the 0-based index of the X-position of the node.

    • getYUnscaled

      public int getYUnscaled(int i)
      Returns the unscaled Y position of a node.
      Parameters:
      i - the index of the path node
      Returns:
      the 0-based index of the Y-position of the node.

    • getZUnscaled

      public int getZUnscaled(int i)
      Returns the unscaled Z position of a node.
      Parameters:
      i - the index of the path node
      Returns:
      the 0-based index of the Z-position of the node. Note that Z-indices in ImagePlus are 1-based, i.e., outside SNT the proper Z-slice for this position in an ImagePlus is getZUnscaled(i) + 1

    • getXUnscaledDouble

      public double getXUnscaledDouble(int i)

    • getYUnscaledDouble

      public double getYUnscaledDouble(int i)

    • getZUnscaledDouble

      public double getZUnscaledDouble(int i)

    • getUnscaledNodes

      public List<PointInCanvas> getUnscaledNodes()
      Returns:
      the list of nodes in image space (pixel coordinates). This takes already takes into account getCanvasOffset().

    • getSection

      public Path getSection(int startIndex, int endIndex)
      Gets a section between two nodes of this Path.
      Parameters:
      startIndex - the node index defining the first node of the section
      endIndex - the node index defining the last node of the section
      Returns:
      the section. Note that the sectioned Path will share of all of this Path's properties but will not contain any information on junction points or connectivity to other Paths.

    • createPath

      public Path createPath()
      Returns a new Path with this Path's attributes (e.g. spatial scale), but no nodes.
      Returns:
      the empty path

    • replaceNodes

      public void replaceNodes(Path replacementPath)
      Replaces all nodes of this path with those from the replacement path, preserving hierarchical relationships (parent, children, connections).

      This method is useful for refining path geometry (e.g., from A* tracing) while maintaining the tree structure.

      Parameters:
      replacementPath - the path providing the new node geometry
      Throws:
      IllegalArgumentException - if replacementPath is null or empty

    • setSpacing

      protected void setSpacing(ij.measure.Calibration cal)

    • setSpacing

      public void setSpacing(double xSpacing, double ySpacing, double zSpacing, String unit)

    • clone

      public Path clone()
      Creates a deep copy of this Path.

      This method creates a complete copy of the path including all nodes, properties, and calibration settings. The cloned path will have the same spatial coordinates, node properties (radius, color, tangent), and metadata as the original, but will be completely independent. Parent-child relationships are not preserved in the clone to avoid infinite recursion and should be established separately if needed.

      Fitted paths and legacy 3D viewer content are not cloned - the new path will need to be re-fitted and re-added to viewers if needed.

      Overrides:
      clone in class Object
      Returns:
      a new Path that is a deep copy of this path
      See Also:

    • clone

      public Path clone(boolean includeImmediateChildren)
      Creates a copy of this Path with optional inclusion of immediate children.

      This method creates a clone of this path and optionally includes clones of its immediate child paths. When children are included, they are properly reconnected to the cloned parent path, maintaining the parent-child relationships. Note that only immediate children are cloned - grandchildren and deeper descendants are not included.

      Limitations: This method only clones the immediate children and does not recursively clone the entire subtree. For complex tree structures, consider using Tree.clone() instead.

      Parameters:
      includeImmediateChildren - if true, includes clones of immediate child paths; if false, returns a clone without children
      Returns:
      a new Path that is a copy of this path, optionally including children

    • getChildren

      public List<Path> getChildren()
      Gets the list of child paths that branch from this path.

      Returns the collection of paths that have this path as their parent. The returned list is the actual internal list, so modifications to it will affect the path's structure.

      Returns:
      the List of child paths. May be empty if this path has no children, but never null.
      See Also:

    • getCalibration

      public ij.measure.Calibration getCalibration()
      Gets the spatial calibration of this Path.
      Returns:
      the calibration details associated with this Path

    • add

      public void add(Path other)

    • reverse

      public void reverse()
      Reverses this path so that its starting node becomes the last and vice versa.

    • reversed

      public Path reversed()
      Returns:
      a reversed version of this path in which node coordinates are reversed. Note that for legacy reasons only the node coordinates are reversed. Other properties (node colors, etc.) are not included in the returned path

    • addNode

      public void addNode(PointInImage point)
      Appends a node to this Path.
      Parameters:
      point - the node to be inserted

    • addPointDouble

      public void addPointDouble(double x, double y, double z)

    • drawPathAsPoints

      public void drawPathAsPoints(TracerCanvas canvas, Graphics2D g, Color c, int plane, boolean highContrast, boolean drawDiameter)

    • drawPathAsPoints

      protected void drawPathAsPoints(TracerCanvas canvas, Graphics2D g, Color c, int plane, boolean drawDiameter, int slice, int either_side)

    • drawPathAsPoints

      protected void drawPathAsPoints(Graphics2D g2, TracerCanvas canvas, SNT snt)

    • drawPathAsPoints

      public void drawPathAsPoints(TracerCanvas canvas, Graphics2D g2, Color c, boolean highContrast, boolean drawDiameter, int slice, int either_side)

    • setNodeColors

      public void setNodeColors(Color[] colors)
      Sets the node colors.
      Parameters:
      colors - the colors used to render the nodes of this. If null (the default) all nodes are rendered using the Path color.

    • getNodeColors

      public Color[] getNodeColors()
      Gets the node colors.
      Returns:
      the colors used to render the nodes of this path, or null if nodes are rendered using the Path color

    • getNodeColor

      public Color getNodeColor(int pos)
      Gets the node color.
      Parameters:
      pos - the node position
      Returns:
      the node color, or null if no color nodes have been assigned to this path

    • setNodeColor

      public void setNodeColor(Color color, int pos)
      Sets the node color.
      Parameters:
      color - the node color
      pos - the node position

    • setNodeColor

      public void setNodeColor(org.scijava.util.ColorRGB color, int pos)
      Sets the node color.
      Parameters:
      color - the node color
      pos - the node position

    • setNodeValue

      public void setNodeValue(double value, int pos)
      Assigns the "value" property to this node.
      Parameters:
      value - the node value
      pos - the node position
      See Also:

    • setNodeAnnotation

      public void setNodeAnnotation(BrainAnnotation annotation, int pos)
      Assigns an annotation to an existing node.
      Parameters:
      annotation - the node annotation
      pos - the node position

    • setNodeHemisphere

      public void setNodeHemisphere(char hemisphereFlag, int pos)
      Assigns a hemisphere to an existing node.
      Parameters:
      hemisphereFlag - the node hemisphere flag.
      pos - the node position

    • getNodeValue

      public double getNodeValue(int pos)
      Returns the "value" property of this node.
      Parameters:
      pos - the node position
      Returns:
      the value property of this node
      See Also:

    • getNodeAnnotation

      public BrainAnnotation getNodeAnnotation(int pos)
      Returns the neuropil annotation associated with this node.
      Parameters:
      pos - the node position
      Returns:
      the annotation of this node,
      See Also:

    • getNodeHemisphereFlag

      public char getNodeHemisphereFlag(int pos)
      Returns the hemisphere flag associated with this node.
      Parameters:
      pos - the node position
      Returns:
      the flag associated with this node, either BrainAnnotation.LEFT_HEMISPHERE, BrainAnnotation.RIGHT_HEMISPHERE, or BrainAnnotation.ANY_HEMISPHERE
      See Also:

    • setNodeValues

      public void setNodeValues(double[] values)
      Sets the path "values", the array containing the numeric property assigned to path nodes, typically voxel intensities.
      Parameters:
      values - the new node values
      See Also:

    • hasNodeValues

      public boolean hasNodeValues()
      Assesses whether the nodes of this path have been assigned an array of values
      Returns:
      true, if successful
      See Also:

    • hasNodeAnnotations

      public boolean hasNodeAnnotations()
      Assesses whether the nodes of this path have been assigned BrainAnnotations.
      Returns:
      true, if successful
      See Also:

    • hasNodeHemisphereFlags

      public boolean hasNodeHemisphereFlags()
      Assesses whether the nodes of this path have been assigned hemisphere flags.
      Returns:
      true, if successful
      See Also:

    • getColor

      public Color getColor()
      Gets the color of this Path
      Returns:
      the color, or null if no color has been assigned to this Path
      See Also:

    • getColorRGB

      public org.scijava.util.ColorRGB getColorRGB()
      Gets the color of this Path
      Returns:
      the color, or null if no color has been assigned to this Path
      See Also:

    • setColor

      public void setColor(Color color)
      Sets this path color.
      Parameters:
      color - the path color. Set it to null, to have SNT render this Path using default settings. You may need to cast the null reference to Color to avoid ambiguous method overload

    • setColor

      public void setColor(org.scijava.util.ColorRGB color)
      Sets this path color.
      Parameters:
      color - the path color. Set it to null, to have SNT render this Path using default settings. You may need to cast the null reference to ColorRGB to avoid ambiguous method overload

    • resetColor

      public void resetColor()
      Resets this path color, forcing SNT to render it under default settings.

    • hasCustomColor

      public boolean hasCustomColor()
      Assesses whether a custom color has been assigned to this Path.
      Returns:
      true, if successful
      See Also:

    • getSWCcolor

      public static Color getSWCcolor(int swcType)
      Gets the default SWC colors used by SNT.
      Parameters:
      swcType - the SEC type (e.g., SWC_AXON, SWC_DENDRITE, etc.)
      Returns:
      the SWC color

    • isFittedVersionOfAnotherPath

      public boolean isFittedVersionOfAnotherPath()
      Checks if this Path is a fitted version of another path.
      Returns:
      true, if it is a fitted version of another path

    • getUnfitted

      public Path getUnfitted()
      Gets the original (unfitted) path that this path is a fitted version of.
      Returns:
      the unfitted original, or null if this is not a fitted path
      See Also:

    • setFitted

      protected void setFitted(Path p)

    • setUseFitted

      public void setUseFitted(boolean useFitted) throws IllegalArgumentException
      Sets whether the fitted flavor of this Path should be used.
      Parameters:
      useFitted - the new use fitted
      Throws:
      IllegalArgumentException - if this Path has not been fitted

    • discardFit

      protected void discardFit()

    • getUseFitted

      public boolean getUseFitted()
      Gets whether the fitted 'flavor' of this Path is in use.
      Returns:
      true, if the fitted version of this Path is in use, otherwise false

    • getSpineOrVaricosityCount

      public int getSpineOrVaricosityCount()
      Gets the number of spines or varicosities associated with this path.
      Returns:
      the number of spines or varicosities. Returns 0 if no features have been annotated.
      See Also:

    • setSpineOrVaricosityCount

      public void setSpineOrVaricosityCount(int newCount)
      Sets the number of spines or varicosities associated with this path.
      Parameters:
      newCount - the new count of spines or varicosities. Should be non-negative.
      See Also:

    • getChannel

      public int getChannel()
      Gets the hyperstack channel associated with this Path.
      Returns:
      the channel position of this path (1-based index). Note that if the channel associated with a path is not known, it is assumed to be 1;

    • getFrame

      public int getFrame()
      Gets the hyperstack frame position associated with this Path.
      Returns:
      the frame position of this path (1-based index). Note that if the frame associated with a path is not known, it is assumed to be 1;

    • setCTposition

      public void setCTposition(int channel, int frame)
      Sets the hyperstack position of this Path
      Parameters:
      channel - the channel (one-based index)
      frame - the frame (one-based index)

    • getFitted

      public Path getFitted()
      Gets the fitted version ('flavor') of this Path.
      Returns:
      the fitted version, or null if this Path has not been fitted

    • setGuessedTangents

      public void setGuessedTangents(int pointsEitherSide)

    • getTangent

      public void getTangent(int i, int pointsEitherSide, double[] result)

    • getSWCtypeNames

      public static List<String> getSWCtypeNames()
      Gets the list of string representations of SWC types
      Returns:
      the list of SWC type names

    • getSWCtypes

      public static List<Integer> getSWCtypes()
      Gets the list of SWC types.
      Returns:
      the list of SWC type flags

    • getSWCtypeName

      public static String getSWCtypeName(int type, boolean capitalized)
      Gets the SWC type label associated with the specified type flag. SNT follows the specification detailed at swc-specification.readthedocs.io
      Parameters:
      type - the SWC type flag
      capitalized - whether output String should be capitalized
      Returns:
      the respective label, or SWC_UNDEFINED_LABEL if flag was not recognized

    • getMeanRadius

      public double getMeanRadius()
      Gets the path mean radius.
      Returns:
      the average radius of the path, or zero if path has no defined thickness
      See Also:

    • getNodeRadius

      public double getNodeRadius(int pos)
      Gets the radius of the specified node.
      Parameters:
      pos - the node position
      Returns:
      the radius at the specified position, or zero if path has no defined thickness

    • setNodeRadius

      public void setNodeRadius(double radius, int pos)
      Sets the radius of a specific node.
      Parameters:
      radius - the radius value
      pos - the node position

    • hasRadii

      public boolean hasRadii()
      Checks whether the nodes of this path have been assigned defined thickness.
      Returns:
      true, if the points defining with this path are associated with a list of radii

    • hasNodeColors

      public boolean hasNodeColors()
      Checks whether any nodes have custom colors assigned.
      Returns:
      true if any nodes have custom colors
      See Also:

    • getNodeTangent

      public double[] getNodeTangent(int pos)
      Gets the tangent vector of a specific node.
      Parameters:
      pos - the node position
      Returns:
      the tangent vector [x, y, z] or null if not defined

    • setNodeTangent

      public void setNodeTangent(double[] tangent, int pos)
      Sets the tangent vector of a specific node.
      Parameters:
      tangent - the tangent vector [x, y, z]
      pos - the node position

    • setNodeTangent

      public void setNodeTangent(double tx, double ty, double tz, int pos)
      Sets the tangent vector of a specific node.
      Parameters:
      tx - the X component of the tangent
      ty - the Y component of the tangent
      tz - the Z component of the tangent
      pos - the node position

    • hasTangents

      public boolean hasTangents()
      Checks whether any nodes have tangent vectors defined.
      Returns:
      true if any nodes have tangents

    • firstNode

      public PointInImage firstNode()
      Returns the first node of this path.
      Returns:
      the root node, or null if path is empty

    • lastNode

      public PointInImage lastNode()
      Returns the last node of this path.
      Returns:
      the terminal node, or null if path is empty

    • contains

      public boolean contains(PointInImage point, double tolerance)
      Checks if this path contains the specified point within the given tolerance.
      Parameters:
      point - the point to check
      tolerance - the distance tolerance
      Returns:
      true if the path contains the point within tolerance

    • getInterpolatedPath

      public Path getInterpolatedPath(double maxDistance)
      Returns a new Path in which nodes have been interpolated to ensure that the distance between consecutive nodes does not exceed the specified threshold.
      Parameters:
      maxDistance - the maximum distance allowed between consecutive nodes
      Returns:
      the interpolated path

    • getResampledPath

      public Path getResampledPath(double targetSpacing)
      Returns a new Path in which nodes have been resampled to ensure uniform spacing along the path.
      Parameters:
      targetSpacing - the desired spacing between consecutive nodes
      Returns:
      the resampled path

    • getSmoothedPath

      public Path getSmoothedPath(int windowSize)
      Returns a smoothed version of this path using a simple moving average filter.
      Parameters:
      windowSize - the size of the smoothing window (must be odd and >= 3)
      Returns:
      the smoothed path

    • interpolateMissingRadii

      @Deprecated public Map<Integer,Double> interpolateMissingRadii(DoublePredicate predicate, boolean apply)
      Deprecated.
      Use sanitizeRadii(DoublePredicate, boolean) instead

    • sanitizeRadii

      public Map<Integer,Double> sanitizeRadii(boolean apply)
      Sanitizes node radii by interpolating invalid values (zero, NaN, or negative).

      Convenience method equivalent to calling sanitizeRadii((r) -> r <= 0 || Double.isNaN(r), apply).

      Parameters:
      apply - if true, corrected values are immediately applied
      Returns:
      map of corrected (node index, radius) pairs, or null if path has no radii or fewer than 2 nodes
      See Also:

    • sanitizeRadii

      public Map<Integer,Double> sanitizeRadii(DoublePredicate predicate, boolean apply)
      Sanitizes node radii by interpolating values that match the given predicate.

      Collects nodes with invalid radii (as defined by predicate) and assigns new values using linear interpolation based on remaining valid nodes. Interpolated values are clamped to the observed range of valid radii to prevent extrapolation artifacts.

      If fewer than two valid radii exist, interpolation is not possible and an empty map is returned. For automatic fallback handling, use sanitizeRadii(double, double, boolean) instead.

      Parameters:
      predicate - function returning true for invalid radii
      apply - if true, corrected values are immediately applied
      Returns:
      map of corrected (node index, radius) pairs, or null if path has no radii or fewer than 2 nodes. Empty map if no invalid radii found or interpolation not possible.
      See Also:

    • sanitizeRadii

      public Map<Integer,Double> sanitizeRadii(double minRadius, double maxRadius, boolean apply)
      Sanitizes node radii by enforcing bounds and interpolating outliers.

      Identifies nodes with radii outside [minRadius, maxRadius] and assigns new values using linear interpolation based on remaining valid nodes. Interpolated values are clamped to the specified range to prevent extrapolation artifacts.

      If fewer than two nodes have valid radii, a context-appropriate fallback is used:
      • All radii above range → maxRadius
      • All radii below range → minRadius
      • Mixed or NaN values → midpoint of range
      Parameters:
      minRadius - minimum valid radius (inclusive)
      maxRadius - maximum valid radius (inclusive)
      apply - if true, corrected values are immediately applied
      Returns:
      map of corrected (node index, radius) pairs, or null if path has no radii or fewer than 2 nodes. Empty map if all radii are already within range.
      Throws:
      IllegalArgumentException - if bounds are negative or minRadius > maxRadius
      See Also:

    • setFittedCircles

      protected void setFittedCircles(int nPoints, double[] tangents_x, double[] tangents_y, double[] tangents_z, double[] radii, double[] optimized_x, double[] optimized_y, double[] optimized_z)

    • toString

      public String toString()
      This toString() method shows details of the path which is actually being displayed, not necessarily this path object.
      Overrides:
      toString in class Object
      Returns:
      the string

    • setSWCType

      public void setSWCType(int newSWCType)
      Sets the SWC type.
      Parameters:
      newSWCType - the new SWC type

    • setSWCType

      protected void setSWCType(int newSWCType, boolean alsoSetInFittedVersion)

    • getSWCType

      public int getSWCType()
      Gets the SWC type.
      Returns:
      the SWC type

    • getOrder

      public int getOrder()
      Gets the "bifurcation" (branching) order of this Path. If registered in the GUI, this would correspond to the level of this Path in PathManagerUI's JTree: E.g., a Path connected to a primary Path (order 1) will be assigned order 2, etc. N.B.: Albeit related to reverse Horton-Strahler classification, Path ordering is formally distinct, as it classifies Paths instead of branches.
      Returns:
      the order of this path. A primary path is always of order 1.
      See Also:

    • setOrder

      public void setOrder(int order)

    • removeFrom3DViewer

      @Deprecated public void removeFrom3DViewer(ij3d.Image3DUniverse univ)
      Deprecated.
      This method is deprecated. Use newer 3D visualization methods instead.
      Removes this path from the specified 3D viewer universe.
      Parameters:
      univ - the Image3DUniverse from which to remove this path's 3D representation. Must not be null.

    • getPoint3fList

      @Deprecated public List<org.jogamp.vecmath.Point3f> getPoint3fList()
      Deprecated.

    • addAsLinesTo3DViewer

      @Deprecated public ij3d.Content addAsLinesTo3DViewer(ij3d.Image3DUniverse univ, Color c, ij.ImagePlus colorImage)
      Deprecated.

    • addAsLinesTo3DViewer

      @Deprecated protected ij3d.Content addAsLinesTo3DViewer(ij3d.Image3DUniverse univ, org.jogamp.vecmath.Color3f c, ij.ImagePlus colorImage)
      Deprecated.

    • addDiscsTo3DViewer

      @Deprecated public ij3d.Content addDiscsTo3DViewer(ij3d.Image3DUniverse univ, Color c, ij.ImagePlus colorImage)
      Deprecated.

    • addDiscsTo3DViewer

      @Deprecated public ij3d.Content addDiscsTo3DViewer(ij3d.Image3DUniverse univ, org.jogamp.vecmath.Color3f c, ij.ImagePlus colorImage)
      Deprecated.

    • addTo3DViewer

      @Deprecated public void addTo3DViewer(ij3d.Image3DUniverse univ, Color c, ij.ImagePlus colorImage)
      Deprecated.
      This method is deprecated. Use newer 3D visualization methods instead.
      Adds this path to the specified 3D viewer universe with the given color.
      Parameters:
      univ - the Image3DUniverse to add this path to
      c - the color to use for rendering this path
      colorImage - the color image for texture mapping (can be null)

    • addTo3DViewer

      @Deprecated public void addTo3DViewer(ij3d.Image3DUniverse univ, org.jogamp.vecmath.Color3f c, ij.ImagePlus colorImage)
      Deprecated.
      This method is deprecated. Use newer 3D visualization methods instead.
      Adds this path to the specified 3D viewer universe with the given Color3f.
      Parameters:
      univ - the Image3DUniverse to add this path to
      c - the Color3f to use for rendering this path. Must not be null.
      colorImage - the color image for texture mapping (can be null)

    • setSelected

      public void setSelected(boolean newSelectedStatus)

    • isSelected

      public boolean isSelected()

    • isActiveVersion

      public boolean isActiveVersion()
      Checks if this version of the path is currently being used for display/analysis.
      Returns:
      true if this version is active, false otherwise

    • versionInUse

      @Deprecated public boolean versionInUse()
      Deprecated.
      Use isActiveVersion() instead

    • getApproximatedVolume

      public double getApproximatedVolume()
      Returns an estimated volume of this path.

      The most accurate volume of each path segment would be the volume of a convex hull of two arbitrarily oriented and sized circles in space. This is tough to work out analytically, and this precision isn't really warranted given the errors introduced in the fitting process, the tracing in the first place, etc. So, this method produces an approximate volume assuming that the volume of each of these parts is that of a truncated cone (Frustum) , with circles of the same size (i.e., as if the circles had simply been reoriented to be parallel and have a common normal vector)

      For more accurate measurements of the volumes of a neuron, you should use the filling interface.

      Returns:
      the approximate fitted volume (in physical units), or NaN if this Path has no radii
      See Also:

    • getApproximatedSurface

      public double getApproximatedSurface()
      Returns an estimated surface area of this path, treating each inter-node segment as a frustum.
      Returns:
      the approximate surface area (in physical units), or 0 if this Path has no radii
      See Also:

    • transform

      public Path transform(PathTransformer transformation, ij.ImagePlus template, ij.ImagePlus model)

    • findJunctions

      public List<PointInImage> findJunctions()
      Returns the nodes which are indicated to be a join (junction/branch point), either in this Path object, or any other that starts or ends on it.
      Returns:
      the list of nodes as PointInImage objects
      See Also:

    • getBranchPoints

      public Set<PointInImage> getBranchPoints()
      This is a version of findJunctions() ensuring that a junction node is only retrieved once even if multiple child paths are associated with it.
      Returns:
      the junction nodes
      See Also:

    • getJunctionNodes

      @Deprecated public Set<PointInImage> getJunctionNodes()
      Deprecated.
      use getBranchPoints() instead

    • findJunctionIndices

      public TreeSet<Integer> findJunctionIndices()
      Returns the indices of nodes which are indicated to be a join, either in this Path object, or any other that starts or ends on it.
      Returns:
      the indices of junction nodes, naturally sorted
      See Also:

    • downsample

      public void downsample(double internodeSpacing)
      Downsamples this path (in-place) by reducing the number of nodes while preserving its overall shape.

      This method reduces the density of nodes in the path by removing redundant points expected to not significantly contribute to the path's shape. The downsampling is performed using the Douglas-Peucker algorithm, which preserves fidelity within the specified tolerance.

      The method operates on the segments flanked by anchor points (junctions, start, and end points). Each segment is downsampled independently, and the results are combined to form the final downsampled path. Node radii are averaged appropriately for retained points

      Thread Safety: This method is synchronized to prevent concurrent modification of the path structure during the downsampling operation.

      Parameters:
      internodeSpacing - the target spacing between nodes after downsampling. This parameter controls the aggressiveness of the downsampling - smaller values preserve more detail, larger values result in more aggressive simplification. Must be greater than zero.
      Throws:
      IllegalArgumentException - if internodeSpacing is less than or equal to zero
      See Also:

    • upsample

      public void upsample(double internodeSpacing)
      Upsamples this path by spacing nodes at a specified distance.

      The original nodes are preserved and additional interpolated nodes are placed at regular intervals between them. The spacing between adjacent nodes will thus be approximately equal to the specified distance. If the distance between two adjacent original nodes is less than the specified pacing, no additional nodes are added between them.

      NB:Some assigned properties (node colors, node values, etc.) will be lost.

      Thread Safety: This method is synchronized to prevent concurrent modification of the path structure during the upsampling operation.

      Parameters:
      internodeSpacing - the desired distance between adjacent nodes
      Throws:
      IllegalArgumentException - if spacing is less than or equal to zero

    • setRadius

      public void setRadius(double r)
      Assigns a fixed radius to all the nodes of this Path
      Parameters:
      r - the radius to be assigned. Setting it to 0 or Double.NaN removes the radius attribute from the Path

    • setRadius

      public void setRadius(double r, int index)
      Assigns a radius to a specific node of this Path.

      Sets the radius for the node at the specified index. If this is the first radius being set for the path and no tangents exist, this method will also compute guessed tangents to support proper 3D rendering.

      Parameters:
      r - the radius to be assigned to the node. NaN values are ignored.
      index - the 0-based index of the node to modify
      Throws:
      IndexOutOfBoundsException - if index is out of range
      See Also:

    • setRadii

      public void setRadii(double[] radii)
      Assigns radii to this Path
      Parameters:
      radii - the radii array. Setting it null removes the radius attribute from the Path
      See Also:

    • fitRadii

      public boolean fitRadii(ij.ImagePlus imp)
      Fits radii to this Path by fitting circular cross-sections to the image signal. This is the scripting equivalent of the UI's "Fit Path" action. Node positions are not modified; only radii and tangent vectors are computed.
      Parameters:
      imp - the image containing the signal to fit against
      Returns:
      true if the fit succeeded
      Throws:
      IllegalArgumentException - if this path is already a fitted version of another path, or if the image is null
      See Also:

    • isConnectedTo

      public boolean isConnectedTo(Path other)

    • addChangeListener

      protected void addChangeListener(sc.fiji.snt.PathChangeListener listener)

    • removeChangeListener

      protected boolean removeChangeListener(sc.fiji.snt.PathChangeListener listener)