Package sc.fiji.snt.viewer

Class Viewer3D

java.lang.Object
sc.fiji.snt.viewer.Viewer3D
public class Viewer3D extends Object
Implements SNT's Reconstruction Viewer. Relies heavily on the org.jzy3d package.
Author:
Tiago Ferreira

  • Field Details

  • Constructor Details

    • Viewer3D

      public Viewer3D()
      Instantiates Viewer3D without the 'Controls' dialog ('kiosk mode'). Such a viewer is more suitable for large datasets and allows for Trees to be added concurrently.

    • Viewer3D

      public Viewer3D(org.scijava.Context context)
      Instantiates an interactive Viewer3D with GUI Controls to import, manage and customize the Viewer's scene.
      Parameters:
      context - the SciJava application context providing the services required by the class

    • Viewer3D

      public Viewer3D(boolean interactive)
      Script-friendly constructor.
      Parameters:
      interactive - if true, the viewer is displayed with GUI Controls to import, manage and customize the Viewer's scene.

    • Viewer3D

      public Viewer3D(boolean interactive, String engine)
      Script-friendly constructor.
      Parameters:
      interactive - if true, the viewer is displayed with GUI Controls to import, manage and customize the Viewer's scene.
      engine - the rendering engine. Either "gpu" (JOGL), "cpu" (EmulGL), or "offscreen" (headless). "cpu" and "offscreen" are highly experimental.

    • Viewer3D

      protected Viewer3D(SNT snt)

  • Method Details

    • show

      public static Viewer3D show(Object object)
      Convenience factory that creates a viewer, adds the given object, and displays it. Equivalent to: 
      
 Viewer3D viewer = new Viewer3D();
 viewer.add(object);
 viewer.show();
      Parameters:
      object - the object to display (Tree, Path, OBJMesh, Collection, etc., anything accepted by add(Object))
      Returns:
      the viewer instance
      See Also:

    • getID

      public int getID()
      Returns this Viewer's id.
      Returns:
      this Viewer's unique numeric ID.

    • setSceneUpdatesEnabled

      public void setSceneUpdatesEnabled(boolean enabled)
      Sets whether the scene should update (refresh) every time a new reconstruction (or mesh) is added/removed from the scene.
      Parameters:
      enabled - Whether scene updates should be enabled. Should be set to false when performing bulk operations. Scene will update if set to true

    • setAnatomicalMapping

      public void setAnatomicalMapping(String template) throws IllegalArgumentException
      Applies the anatomical axis mapping associated with a known reference brain. This is a convenience method that sets the axis labels and scene orientation (up vector) appropriate for the given atlas space, so that anatomical planes are rendered correctly. It is the script-friendly equivalent of the axis mapping that is applied automatically when using the GUI's Reference Brains menu or Allen CCF Navigator.

      Currently supported templates (case-insensitive): "mouse" / "allen" / "ccf" (Allen CCF); "zebrafish" (Max Planck ZBA); "jfrc2018", "jfrc2", "jfrc3", "fcwb" (Drosophila).

      Parameters:
      template - the reference brain identifier (case-insensitive), e.g., "allen", "mouse", "zebrafish", "jfrc2018"
      Throws:
      IllegalArgumentException - if template is not recognized
      See Also:

    • setAnatomicalMapping

      public void setAnatomicalMapping(String[] axisLabels, String dorsalAxis)
      Applies a custom anatomical axis mapping to the scene, setting axis labels and the scene's up vector (dorsal direction). This is useful for custom atlases or coordinate systems not covered by the predefined templates.
      Parameters:
      axisLabels - a 3-element array of axis labels for {X, Y, Z}, e.g., {"Anterior-Posterior", "Dorsal-Ventral", "Left-Right"}. If null, axes are reset to "X", "Y", "Z".
      dorsalAxis - the axis and direction pointing dorsally, specified as a sign and axis letter: e.g., "-Y" (dorsal is negative Y, as in Allen CCF), "+Z" (dorsal is positive Z, the default), "X" (positive X). If null or empty, the default Z-up is used.
      Throws:
      IllegalArgumentException - if dorsalAxis is not a valid axis descriptor
      See Also:

    • setAxesLabels

      public void setAxesLabels(String... labels)
      Sets custom labels for the 3D coordinate axes.
      Parameters:
      labels - the axis labels in order: X-axis, Y-axis, Z-axis. If null, defaults to "X", "Y", "Z". If fewer than 3 labels are provided, only the available axes are labeled.

    • duplicate

      public Viewer3D duplicate()
      Creates a duplicate of this viewer containing only visible objects.

      This method creates a new Viewer3D instance and copies all currently visible objects (trees, meshes, annotations) from this viewer to the new one. The duplicate viewer maintains the same visual settings and object properties but operates independently from the original.

      Returns:
      a new Viewer3D instance containing copies of all visible objects

    • validate

      public void validate()
      Checks if all drawables in the 3D scene are being rendered properly, rebuilding the entire scene if not. Useful to "hard-reset" the viewer, e.g., to ensure all meshes are redrawn.
      See Also:

    • setEnableDebugMode

      public void setEnableDebugMode(boolean enable)
      Enables/disables debug mode
      Parameters:
      enable - true to enable debug mode, otherwise false

    • setEnableDarkMode

      public void setEnableDarkMode(boolean enable)
      Enables/disables "Dark Mode" mode
      Parameters:
      enable - true to enable "Dark Mode", "Light Mode" otherwise

    • setEnableAxes

      public void setEnableAxes(boolean enable)
      Enables/disables the display of X,Y,Z axis grid.
      Parameters:
      enable - true to enable axes

    • setSplitDendritesFromAxons

      public void setSplitDendritesFromAxons(boolean split)
      Sets whether axons and dendrites should be imported as separated objects.
      Parameters:
      split - true to segregate imported Trees into axonal and dendritic subtrees. This is likely only relevant to allow for subtree customizations using the GUI commands provided by the "RV Controls" dialog. This parameter is ignored if Trees have no annotations.

    • rotate

      public void rotate(float degrees) throws IllegalArgumentException
      Rotates the scene.
      Parameters:
      degrees - the angle, in degrees
      Throws:
      IllegalArgumentException - if current view mode does not allow rotations

    • recordRotation

      public void recordRotation(float angle, int frames, File destinationDirectory) throws IllegalArgumentException, SecurityException
      Records an animated rotation of the scene as a sequence of images.
      Parameters:
      angle - the rotation angle (e.g., 360 for a full rotation)
      frames - the number of frames in the animated sequence
      destinationDirectory - the directory where the image sequence will be stored.
      Throws:
      IllegalArgumentException - if no view exists, or current view is constrained and does not allow 360 degrees rotation
      SecurityException - if it was not possible to save files to destinationDirectory

    • recordRotation

      public void recordRotation(float angle, int frames, File destinationDirectory, Viewer3D.RotationAxis axis) throws IllegalArgumentException, SecurityException
      Records an animated rotation of the scene around the specified axis as a sequence of images.
      Parameters:
      angle - the rotation angle (e.g., 360 for a full rotation)
      frames - the number of frames in the animated sequence
      destinationDirectory - the directory where the image sequence will be stored.
      axis - the axis of rotation (X, Y, or Z)
      Throws:
      IllegalArgumentException - if no view exists, or current view is constrained and does not allow rotation
      SecurityException - if it was not possible to save files to destinationDirectory

    • isDarkModeOn

      public boolean isDarkModeOn()
      Checks if scene is being rendered under dark or light background.
      Returns:
      true, if "Dark Mode" is active

    • isSplitDendritesFromAxons

      public boolean isSplitDendritesFromAxons()
      Checks whether axons and dendrites of imported Trees are set to be imported as separated objects.
      Returns:
      if imported trees are set to be split into axonal and dendritic subtrees.

    • freeze

      public void freeze()
      Does not allow scene to be interactive. Only static orthogonal views allowed.
      See Also:

    • unfreeze

      public void unfreeze()
      Allows scene to be interactive.
      See Also:

    • runCommand

      public void runCommand(String cmd)
      Parameters:
      cmd - the recorded command

    • fromAWTColor

      protected org.jzy3d.colors.Color fromAWTColor(Color color)

    • addTree

      public void addTree(Tree tree)
      Adds a tree to this viewer. Note that calling updateView() may be required to ensure that the current View's bounding box includes the added Tree.
      Parameters:
      tree - the Tree to be added. The Tree's label will be used as identifier. It is expected to be unique when rendering multiple Trees, if not (or no label exists) a unique label will be generated.
      See Also:

    • addTrees

      public void addTrees(Collection<Tree> trees, String color, String... commonTags)
      Adds a collection of trees.
      Parameters:
      trees - the trees to be added
      color - Set it to null, none or "" to ignore this option altogether. Set it to unique to assign unique colors to each tree in the collection.
      commonTags - common tag(s) to be assigned to the group (to be displayed in the control panel list).

    • addTrees

      public void addTrees(Collection<Tree> trees, String color)
      Adds a collection of trees.
      Parameters:
      trees - the trees to be added.
      color - the rendering color. Set it to null, none or "" to ignore this option altogether. Set it to unique to assign unique colors to each tree in the collection.

    • addTrees

      public void addTrees(Collection<Tree> trees, String color, double transparencyPercent)
      Adds a collection of trees.
      Parameters:
      trees - the trees to be added.
      color - the color to be applied, either an HTML color codes starting with hash (#), a color preset ("red", "blue", etc.), or integer triples of the form r,g,b and range [0, 255]
      transparencyPercent - the color transparency (in percentage)

    • addTrees

      @Deprecated public void addTrees(Collection<Tree> trees, boolean assignUniqueColors)
      Deprecated.
      use addTrees(Collection, String) instead

    • add

      public void add(File[] files, String color)
      Adds a collection of trees or meshes from input files.
      Parameters:
      files - the files to be imported
      color - the color to be assigned to imported reconstructions/meshes. If empty, null or unique, objects will be assigned a unique color.
      See Also:

    • getTree

      public Tree getTree(String label)
      Gets the tree associated with the specified label.
      Parameters:
      label - the (unique) label as displayed in Viewer's list
      Returns:
      the Tree or null if no Tree is associated with the specified label

    • getAnnotation

      public Annotation3D getAnnotation(String label)
      Gets the annotation associated with the specified label.
      Parameters:
      label - the (unique) label as displayed in Viewer's list
      Returns:
      the annotation or null if no annotation is associated with the specified label

    • getMesh

      public OBJMesh getMesh(String label)
      Gets the mesh associated with the specified label.
      Parameters:
      label - the (unique) label as displayed in Viewer's list
      Returns:
      the mesh or null if no mesh is associated with the specified label

    • getTrees

      public List<Tree> getTrees()
      Returns all trees added to this viewer.
      Returns:
      the Tree list

    • getTrees

      public List<Tree> getTrees(boolean visibleOnly)
      Returns all trees added to this viewer.
      Parameters:
      visibleOnly - If true, only visible Trees are retrieved.
      Returns:
      the Tree list

    • getMeshes

      public List<OBJMesh> getMeshes()
      Returns all meshes added to this viewer.
      Returns:
      the mesh list

    • getMeshes

      public List<OBJMesh> getMeshes(boolean visibleOnly)
      Returns all meshes added to this viewer.
      Parameters:
      visibleOnly - If true, only visible meshes are retrieved.
      Returns:
      the mesh list

    • getAnnotations

      public List<Annotation3D> getAnnotations()
      Returns all annotations added to this viewer.
      Returns:
      the annotation list

    • annotateSurface

      public Annotation3D annotateSurface(Collection<? extends SNTPoint> points, String label)

    • annotateSurface

      public Annotation3D annotateSurface(Collection<? extends SNTPoint> points, String label, boolean computeVolume)
      Computes a convex hull from a collection of points and adds it to the scene as an annotation.
      Parameters:
      points - the collection of points defining the convex set.
      label - the (optional) annotation identifier. If null or empty, a unique label will be generated.
      computeVolume - whether to compute the volume of the convex hull. If true, the volume is stored in the "volume" field of the returned Annotation3D object.
      Returns:
      the Annotation3D

    • annotatePoint

      public Annotation3D annotatePoint(SNTPoint point, String label)
      Adds a highlighting point annotation to this viewer.
      Parameters:
      point - the point to be highlighted
      label - the (optional) annotation identifier. If null or empty, a unique label will be generated.
      Returns:
      the Annotation3D

    • annotatePoint

      public Annotation3D annotatePoint(SNTPoint node, String label, String color, float size)
      Adds a highlighting point annotation to this viewer.
      Parameters:
      node - the node to be highlighted
      label - the (optional) annotation identifier. If null or empty, a unique label will be generated.
      color - the annotation color
      size - the annotation size
      Returns:
      the Annotation3D

    • annotatePoints

      public Annotation3D annotatePoints(Collection<? extends SNTPoint> points, String label)
      Adds a scatter (point cloud) annotation to this viewer.
      Parameters:
      points - the collection of points in the annotation
      label - the (optional) annotation identifier. If null or empty, a unique label will be generated.
      Returns:
      the Annotation3D

    • annotateLine

      public Annotation3D annotateLine(Collection<? extends SNTPoint> points, String label)
      Adds a line annotation to this viewer.
      Parameters:
      points - the collection of points in the line annotation (at least 2 elements required). Start and end of line are highlighted if 2 points are specified.
      label - the (optional) annotation identifier. If null or empty, a unique label will be generated.
      Returns:
      the Annotation3D or null if collection contains less than 2 elements

    • annotateMidPlane

      public Annotation3D annotateMidPlane(BoundingBox boundingBox, int axis, String label)

    • annotatePlane

      public Annotation3D annotatePlane(SNTPoint origin, SNTPoint originOpposite, String label)

    • mergeAnnotations

      public Annotation3D mergeAnnotations(Collection<Annotation3D> annotations, String label)
      Merges a collection of annotations into a single object.
      Parameters:
      annotations - the collection of annotations.
      label - the (optional) identifier for the merged annotation. If null or empty, a unique label will be generated.
      Returns:
      the merged Annotation3D

    • rebuild

      public void rebuild(Object obj)
      Rebuilds (repaints) a scene object (e.g., a Tree after being modified elsewhere)
      Parameters:
      obj - the object to be re-rendered (or its label)

    • updateView

      public void updateView()
      Updates the scene bounds to ensure all visible objects are displayed.

    • zoomTo

      public void zoomTo(Object... objects)
      Zooms the scene into the bounding box enclosing the specified objects.
      Parameters:
      objects - the objects to be zoomed into. These can be OBJMesh, Tree, Annotation3D, etc., or string(s) defining objects listed in the control panel. Collections of supported objects are also supported. If Null view is reset. If "visible" view is zoomed to visible objects

    • addColorBarLegend

      public <T extends ColorMapper> void addColorBarLegend(T colorMapper)
      Adds a color bar legend (LUT ramp) from a ColorMapper.
      Parameters:
      colorMapper - the class extending ColorMapper (TreeColorMapper, etc.)

    • addColorBarLegend

      public void addColorBarLegend(net.imglib2.display.ColorTable colorTable, double min, double max)
      Adds a color bar legend (LUT ramp) using default settings.
      Parameters:
      colorTable - the color table
      min - the minimum value in the color table
      max - the maximum value in the color table

    • addColorBarLegend

      public void addColorBarLegend(net.imglib2.display.ColorTable colorTable, double min, double max, boolean replaceExisting)
      Adds a color bar legend (LUT ramp) using default settings.
      Parameters:
      colorTable - the color table
      min - the minimum value in the color table
      max - the maximum value in the color table
      replaceExisting - whether this legend should replace the last legend added to the scene, if any

    • updateColorBarLegend

      public void updateColorBarLegend(double min, double max)
      Updates the existing color bar legend to new properties. Does nothing if no legend exists.
      Parameters:
      min - the minimum value in the color table
      max - the maximum value in the color table

    • addColorBarLegend

      public void addColorBarLegend(net.imglib2.display.ColorTable colorTable, double min, double max, Font font, int steps, int precision)
      Adds a color bar legend (LUT ramp).
      Parameters:
      colorTable - the color table
      min - the minimum value in the color table
      max - the maximum value in the color table
      font - the font the legend font.
      steps - the number of ticks in the legend. Tick placement is computed automatically if negative.
      precision - the number of decimal places of tick labels. scientific notation is used if negative.

    • show

      public Frame show()
      Displays the Viewer and returns a reference to its frame. If the frame has been made displayable, this will simply make the frame visible. Typically, it should only be called once all objects have been added to the scene. If this is an interactive viewer, the 'Controls' dialog is also displayed.
      Returns:
      the frame containing the viewer.

    • getFrame

      public Frame getFrame()

    • getFrame

      public Frame getFrame(boolean visible)
      Gets the frame containing this viewer, optionally controlling its visibility.

      Returns the AWT Frame that contains this viewer's 3D canvas and UI components. If no frame exists, one will be created with the specified visibility setting. This method is useful when you need to control whether the viewer window appears immediately or remains hidden for programmatic manipulation.

      Parameters:
      visible - whether the frame should be visible when created
      Returns:
      the frame containing the viewer
      Throws:
      IllegalArgumentException - if using an offscreen rendering engine

    • show

      public Frame show(int width, int height)
      Displays the viewer under specified dimensions. Useful when generating scene animations programmatically.
      Parameters:
      width - the width of the frame. -1 will set width to its maximum.
      height - the height of the frame. -1 will set height to its maximum.
      Returns:
      the frame containing the viewer.
      See Also:

    • setFrameSize

      public void setFrameSize(int width, int height)
      Resizes the viewer to the specified dimensions. Useful when generating scene animations programmatically. Does nothing if viewer's frame does not exist.
      Parameters:
      width - the width of the frame. -1 will set width to its maximum.
      height - the height of the frame. -1 will set height to its maximum.
      See Also:

    • setLookAndFeel

      public void setLookAndFeel(String lookAndFeelName)

    • removeTree

      public boolean removeTree(Tree tree)
      Removes the specified Tree.
      Parameters:
      tree - the tree to be removed.
      Returns:
      true, if tree was successfully removed.
      See Also:

    • removeTree

      public boolean removeTree(String treeLabel)
      Removes the specified Tree.
      Parameters:
      treeLabel - the key defining the tree to be removed.
      Returns:
      true, if tree was successfully removed.
      See Also:

    • removeAnnotation

      public boolean removeAnnotation(String annotLabel)
      Removes the annotation with the specified label from the viewer.
      Parameters:
      annotLabel - the label identifying the annotation to remove
      Returns:
      true if the annotation was successfully removed, false if no annotation with the specified label was found

    • removeAnnotation

      public boolean removeAnnotation(Annotation3D annot)
      Removes the specified annotation from the viewer.
      Parameters:
      annot - the Annotation3D object to remove
      Returns:
      true if the annotation was successfully removed, false if the annotation was not found in this viewer

    • removeMesh

      public boolean removeMesh(OBJMesh mesh)
      Removes the specified OBJ mesh.
      Parameters:
      mesh - the OBJ mesh to be removed.
      Returns:
      true, if mesh was successfully removed.
      See Also:

    • removeMesh

      public boolean removeMesh(String meshLabel)
      Removes the specified OBJ mesh.
      Parameters:
      meshLabel - the key defining the OBJ mesh to be removed.
      Returns:
      true, if mesh was successfully removed.
      See Also:

    • removeAllMeshes

      public void removeAllMeshes()
      Removes all loaded OBJ meshes from current viewer

    • removeAllTrees

      public void removeAllTrees()
      Removes all the Trees from current viewer

    • removeAllAnnotations

      protected void removeAllAnnotations()
      Removes all the Annotations from current viewer

    • resetView

      public void resetView()
      Resets the view to its default position and orientation.

      This method restores the camera to its initial position, orientation, and zoom level, providing a consistent starting point for viewing the scene.

    • add

      public void add(Object object)
      Script friendly method to add a supported object (Tree, OBJMesh, AbstractDrawable, etc.) to this viewer. Note that collections of supported objects are also supported, which is an effective way of adding multiple items since the scene is only rebuilt once all items have been added.
      Parameters:
      object - the object to be added. No exception is triggered if null
      Throws:
      IllegalArgumentException - if object is not supported

    • remove

      public void remove(Object object)
      Script friendly method to remove an object (Tree, OBJMesh, AbstractDrawable, String (object label), etc.) from this viewer's scene.
      Parameters:
      object - the object to be removed, or the unique String identifying it. Collections supported.
      Throws:
      IllegalArgumentException - if object is not supported

    • syncPathManagerList

      public boolean syncPathManagerList() throws UnsupportedOperationException
      (Re)loads the current list of Paths in the Path Manager list.
      Returns:
      true, if synchronization was apparently successful, false otherwise
      Throws:
      UnsupportedOperationException - if SNT is not running

    • setVisible

      public void setVisible(String label, boolean visible)
      Toggles the visibility of a rendered Tree, a loaded OBJ mesh, or an annotation.
      Parameters:
      label - the unique identifier of the Tree (as per addTree(Tree)), the filename/identifier of the loaded OBJ loadMesh(String, ColorRGB, double), or annotation label.
      visible - whether the Object should be displayed

    • colorCode

      public double[] colorCode(Collection<String> treeLabels, String measurement, net.imglib2.display.ColorTable colorTable)
      Runs MultiTreeColorMapper on the specified collection of Trees.
      Parameters:
      treeLabels - the collection of Tree identifiers (as per addTree(Tree)) specifying the Trees to be color mapped
      measurement - the mapping measurement e.g., MultiTreeColorMapper.CABLE_LENGTH MultiTreeColorMapper.N_TIPS, etc.
      colorTable - the mapping color table (LUT), e.g., ColorTables.ICE), or any other known to LutService
      Returns:
      the double[] the limits (min and max) of the mapped values

    • setAnimationEnabled

      public void setAnimationEnabled(boolean enabled)
      Toggles the Viewer's animation.
      Parameters:
      enabled - if true animation starts. Stops if false

    • setAnimationAxis

      public void setAnimationAxis(Viewer3D.RotationAxis axis)
      Sets the rotation axis for the live animation (double-click spin). Calling this method disables automatic axis detection.
      Parameters:
      axis - the axis of rotation (X, Y, or Z). null defaults to Z.
      See Also:

    • getAnimationAxis

      public Viewer3D.RotationAxis getAnimationAxis()
      Gets the current rotation axis for the live animation.
      Returns:
      the current rotation axis, or Z if not set

    • setAutoDetectAnimationAxis

      public void setAutoDetectAnimationAxis(boolean auto)
      Enables or disables automatic detection of the best rotation axis based on the current viewpoint. When enabled (the default), double-clicking to start a live animation will infer the most natural axis by picking the world axis most aligned with the camera's viewing direction. Calling setAnimationAxis(RotationAxis) disables auto-detection.
      Parameters:
      auto - whether to auto-detect the axis before each animation start
      See Also:

    • isAutoDetectAnimationAxis

      public boolean isAutoDetectAnimationAxis()
      Returns whether automatic rotation axis detection is enabled.
      Returns:
      true if auto-detection is active

    • setAnimationMode

      public void setAnimationMode(Viewer3D.AnimationMode mode)
      Sets the animation mode for both live (double-click) and recorded rotations.
      Parameters:
      mode - the animation mode (Viewer3D.AnimationMode.FULL_ROTATION or Viewer3D.AnimationMode.PING_PONG). null defaults to FULL_ROTATION.

    • getAnimationMode

      public Viewer3D.AnimationMode getAnimationMode()
      Gets the current animation mode.
      Returns:
      the current animation mode

    • setBounds

      public void setBounds(float xMin, float xMax, float yMin, float yMax, float zMin, float zMax)
      Sets a manual bounding box for the scene. The bounding box determines the zoom and framing of the scene. Current view point is logged to the Console when interacting with the Reconstruction Viewer in debug mode.
      Parameters:
      xMin - the X coordinate of the box origin
      xMax - the X coordinate of the box origin opposite
      yMin - the Y coordinate of the box origin
      yMax - the Y coordinate of the box origin opposite
      zMin - the Z coordinate of the box origin
      zMax - the X coordinate of the box origin opposite

    • colorCode

      public double[] colorCode(String treeLabel, String measurement, net.imglib2.display.ColorTable colorTable)
      Runs TreeColorMapper on the specified Tree.
      Parameters:
      treeLabel - the identifier of the Tree (as per addTree(Tree))to be color mapped
      measurement - the mapping measurement e.g., TreeColorMapper.PATH_ORDER TreeColorMapper.PATH_DISTANCE, etc.
      colorTable - the mapping color table (LUT), e.g., ColorTables.ICE), or any other known to LutService
      Returns:
      the double[] the limits (min and max) of the mapped values

    • assignUniqueColors

      public void assignUniqueColors(Collection<String> treeLabels)

    • setViewMode

      public void setViewMode(Viewer3D.ViewMode viewMode)
      Renders the scene from a specified camera angle.
      Parameters:
      viewMode - the view mode, e.g., Viewer3D.ViewMode.DEFAULT, Viewer3D.ViewMode.XY , etc.

    • setTitle

      public void setTitle(String title)
      Sets the title of the Viewer's frame.
      Parameters:
      title - the viewer's title. Ignored if Viewer's frame does not exist

    • setViewMode

      public void setViewMode(String viewMode)
      Renders the scene from a specified camera angle (script-friendly).
      Parameters:
      viewMode - the view mode (case-insensitive): "xy"; "xz"; "yz"; "perspective" or "overview"; "default" or "".

    • setViewPoint

      public void setViewPoint(double r, double t)
      Renders the scene from a specified camera angle using polar coordinates relative to the center of the scene. Only X and Y dimensions are required, as the distance to center is automatically computed. Current view point is logged to the Console by calling logSceneControls().
      Parameters:
      r - the radial coordinate
      t - the angle coordinate (in radians)

    • setViewPointCC

      public void setViewPointCC(double x, double y)
      Calls setViewPoint(double, double) using Cartesian coordinates.
      Parameters:
      x - the X coordinate
      y - the Y coordinate

    • addLabel

      public void addLabel(String label)
      Adds an annotation label to the scene.
      Parameters:
      label - the annotation text
      See Also:

    • setLabelLocation

      public void setLabelLocation(float x, float y)
      Sets the location for annotation labels
      Parameters:
      x - the x position of the label
      y - the y position of the label

    • setFont

      public void setFont(Font font, float angle, org.scijava.util.ColorRGB color)
      Sets the font for label annotations
      Parameters:
      font - the font label, e.g., new Font(Font.SANS_SERIF, Font.ITALIC, 20)
      angle - the angle in degrees for rotated labels
      color - the font color, e.g., org.scijava.util.Colors.ORANGE

    • saveSnapshot

      public boolean saveSnapshot()
      Saves a snapshot of current scene as a PNG image. Image is saved using a unique time stamp as a file name in the directory specified in the preferences dialog or through setSnapshotDir(String)
      Returns:
      true, if successful

    • saveSnapshot

      public boolean saveSnapshot(String filePath)
      Saves a snapshot of current scene as a PNG image to the specified path.
      Parameters:
      filePath - the absolute path of the destination file
      Returns:
      true, if file was successfully saved

    • snapshot

      public ij.ImagePlus snapshot()
      Retrieves the current scene as an image
      Returns:
      the bitmap image of the current scene

    • snapshotWYSIWYG

      public ij.ImagePlus snapshotWYSIWYG()
      Retrieves the current scene as an image using a screen capture that matches the on-screen rendering exactly (WYSIWYG). This bypasses the OpenGL framebuffer readback, avoiding color discrepancies from premultiplied alpha and display color management. Falls back to snapshot() when the viewer is not visible (e.g., offscreen rendering or headless environments).
      Returns:
      the bitmap image of the current scene as displayed on screen

    • snapshot

      public ij.ImagePlus snapshot(String viewMode)
      Retrieves the specified scene view as an image.
      Parameters:
      viewMode - the view mode (case-insensitive) ("xy", "yz", etc.). Anatomical axes ("sagittal", "coronal", "transverse/horizontal") are also accepted when a reference brain is loaded.
      Returns:
      the bitmap image of the scene view

    • saveSnapshot

      protected boolean saveSnapshot(File file) throws IllegalArgumentException, IOException
      Throws:
      IllegalArgumentException
      IOException

    • setSnapshotDir

      public void setSnapshotDir(String path)
      Sets the directory for storing snapshots.
      Parameters:
      path - the absolute path to the new snapshot directory.

    • loadMesh

      public OBJMesh loadMesh(String filePath, org.scijava.util.ColorRGB color, double transparencyPercent) throws IllegalArgumentException
      Loads a Wavefront .OBJ file. Files should be loaded _before_ displaying the scene, otherwise, if the scene is already visible, validate() should be called to ensure all meshes are visible.
      Parameters:
      filePath - the absolute file path (or URL) of the file to be imported. The filename is used as unique identifier of the object (see setVisible(String, boolean))
      color - the color to render the imported file
      transparencyPercent - the color transparency (in percentage)
      Returns:
      the loaded OBJ mesh
      Throws:
      IllegalArgumentException - if filePath is invalid or file does not contain a compilable mesh

    • addMesh

      public boolean addMesh(OBJMesh objMesh) throws IllegalArgumentException
      Loads a Wavefront .OBJ file. Should be called before_ displaying the scene, otherwise, if the scene is already visible, validate() should be called to ensure all meshes are visible.
      Parameters:
      objMesh - the mesh to be loaded
      Returns:
      true, if successful
      Throws:
      IllegalArgumentException - if mesh could not be compiled

    • loadRefBrain

      public OBJMesh loadRefBrain(String template) throws IllegalArgumentException
      Loads the surface mesh of a supported reference brain/neuropil. Internet connection may be required.
      Parameters:
      template - the reference brain to be loaded (case-insensitive). E.g., "zebrafish" (MP ZBA); "mouse" (Allen CCF); "JFRC2", "JFRC3" "JFRC2018", "FCWB"(adult), "L1", "L3", "VNC" (Drosophila)
      Returns:
      a reference to the loaded mesh
      Throws:
      IllegalArgumentException - if template is not recognized
      See Also:

    • getDefColor

      protected org.jzy3d.colors.Color getDefColor()

    • logSceneControls

      public void logSceneControls()
      Logs API calls controlling the scene (view point, bounds, etc.) to Script Recorder (or Console if Script Recorder is not running). Useful for programmatic control of animations.

    • getManagerPanel

      public Viewer3D.ManagerPanel getManagerPanel()
      Returns a reference to control panel.
      Returns:
      the ManagerPanel associated with this Viewer, or null if the 'RV Controls' dialog is not being displayed.

    • getRecorder

      public ScriptRecorder getRecorder(boolean createIfNeeded)
      Gets the script recorder for this viewer, optionally creating one if needed.
      Parameters:
      createIfNeeded - if true, creates a new recorder if one doesn't exist; if false, returns null when no recorder exists
      Returns:
      the ScriptRecorder instance, or null if none exists and createIfNeeded is false

    • dispose

      public void dispose()
      Closes and releases all the resources used by this viewer.

    • setDefaultThickness

      public void setDefaultThickness(float thickness)
      Sets the line thickness for rendering Trees that have no specified radius.
      Parameters:
      thickness - the new line thickness. Note that this value only applies to Paths that have no specified radius

    • setDefaultColor

      public void setDefaultColor(org.scijava.util.ColorRGB color)
      Sets the default color for rendering Trees.
      Parameters:
      color - the new color. Note that this value only applies to Paths that have no specified color and no colors assigned to its nodes

    • getDefaultThickness

      protected float getDefaultThickness()
      Returns the default line thickness.
      Returns:
      the default line thickness used to render Paths without radius

    • setTreeThickness

      public void setTreeThickness(Collection<String> labels, float thickness, String compartment)
      Applies a constant thickness (line width) to a subset of rendered trees.
      Parameters:
      labels - the Collection of keys specifying the subset of trees. If null, thickness is applied to all the trees in the viewer.
      thickness - the thickness (line width)
      compartment - a string with at least 2 characters describing the Tree compartment (e.g., 'axon', 'axn', 'dendrite', 'dend', etc.)
      See Also:

    • setTreeThickness

      public void setTreeThickness(float thickness)
      Applies a constant thickness to all rendered trees. Note that by default, trees are rendered using their nodes' diameter.
      Parameters:
      thickness - the thickness (line width)
      See Also:

    • setTreeThickness

      public void setTreeThickness(float thickness, String compartment)
      Applies a constant thickness (line width) to all rendered trees.Note that by default, trees are rendered using their nodes' diameter.
      Parameters:
      thickness - the thickness (line width)
      compartment - a string with at least 2 characters describing the Tree compartment (e.g., 'axon', 'axn', 'dendrite', 'dend', etc.)
      See Also:

    • setSomaRadius

      public void setSomaRadius(float radius)
      Applies a constant radius to all rendered somas being rendered as spheres.
      Parameters:
      radius - the radius (physical units)

    • setSomaRadius

      public void setSomaRadius(Collection<String> labels, float radius)
      Applies a constant radius to the somas of a subset of rendered trees.
      Parameters:
      labels - the Collection of keys specifying the subset of trees.
      radius - the radius (physical units)
      See Also:

    • setTreeColor

      public void setTreeColor(Collection<String> labels, String color, String compartment)
      Recolors a subset of rendered trees.
      Parameters:
      labels - the Collection of keys specifying the subset of trees
      color - the color to be applied, either a 1) HTML color codes starting with hash (#), a color preset ("red", "blue", etc.), or integer triples of the form r,g,b and range [0, 255]
      compartment - a string with at least 2 characters describing the Tree compartment (e.g., 'axon', 'axn', 'dendrite', 'dend', etc.)

    • setTreeColor

      public void setTreeColor(Collection<String> labels, org.scijava.util.ColorRGB color, String compartment)
      Recolors a subset of rendered trees.
      Parameters:
      labels - the Collection of keys specifying the subset of trees
      color - the color to be applied.
      compartment - a string with at least 2 characters describing the Tree compartment (e.g., 'axon', 'axn', 'dendrite', 'dend', etc.)

    • translate

      public void translate(Tree tree, SNTPoint offset)
      Translates the specified Tree. Does nothing if tree is not present in scene.
      Parameters:
      tree - the Tree to be translated
      offset - the translation offset. If null, tree position will be reset to their original location.

    • translate

      public void translate(Collection<String> treeLabels, SNTPoint offset)
      Translates the specified collection of Trees.
      Parameters:
      treeLabels - the collection of Tree identifiers (as per addTree(Tree)) specifying the Trees to be translated
      offset - the translation offset. If null, trees position will be reset to their original location.

    • setSomasDisplayed

      public void setSomasDisplayed(Collection<String> labels, boolean displayed)
      Toggles the visibility of somas for subset of trees.
      Parameters:
      labels - the Collection of keys specifying the subset of trees to be affected
      displayed - whether soma should be displayed

    • setSomasDisplayed

      public void setSomasDisplayed(boolean displayed)
      Toggles the visibility of somas for all trees in the scene.
      Parameters:
      displayed - whether soma should be displayed

    • setTubeMode

      public void setTubeMode(boolean enabled)
      Enables or disables tube rendering for all trees (current and future). The preference is persisted across sessions.
      Parameters:
      enabled - whether to render neurites as 3D tubes

    • setTubeWireframe

      public void setTubeWireframe(boolean enabled)
      Enables or disables the wireframe overlay on tube rendering for all trees. The preference is persisted across sessions.
      Parameters:
      enabled - whether to show wireframe edges on tubes

    • setTubeSides

      public void setTubeSides(int sides)
      Sets the number of sides for tube cross-sections for all trees. Only has a visual effect when tube rendering is active. The preference is persisted across sessions.
      Parameters:
      sides - number of sides (clamped to [3, 16])

    • setMeshShadingMode

      public void setMeshShadingMode(int mode)
      Sets the shading mode for all OBJ meshes (current and future). The preference is persisted across sessions.
      Parameters:
      mode - OBJMesh.SHADING_DEFAULT or OBJMesh.SHADING_SMOOTH

    • getMeshShadingMode

      public int getMeshShadingMode()
      Returns the current mesh shading mode.
      Returns:
      OBJMesh.SHADING_DEFAULT or OBJMesh.SHADING_SMOOTH

    • setMeshBackfaceCull

      public void setMeshBackfaceCull(boolean enabled)
      Enables or disables backface culling for all OBJ meshes (current and future). Backface culling skips rendering of back-facing triangles, improving performance for closed meshes. The preference is persisted across sessions.
      Parameters:
      enabled - whether to enable backface culling

    • isMeshBackfaceCull

      public boolean isMeshBackfaceCull()
      Returns whether backface culling is enabled for OBJ meshes.
      Returns:
      true if backface culling is enabled

    • setRadiusScale

      public void setRadiusScale(float scale)
      Applies a scaling factor to Trees rendered as Viewer3D.ArborVBO.
      Parameters:
      scale - the radius scale

    • setRadiusScale

      public void setRadiusScale(Collection<String> labels, float scale)
      Applies a tube radius scale to a subset of rendered trees.
      Parameters:
      labels - the Collection of keys specifying the subset of trees, or null to apply to all trees
      scale - the radius scale factor

    • setDepthFog

      public void setDepthFog(boolean enabled)
      Enables or disables depth fog for all trees (current and future). The preference is persisted across sessions.
      Parameters:
      enabled - whether to apply depth fog to neurite rendering

    • setFogIntensity

      public void setFogIntensity(float intensity)
      Sets the fog intensity for all trees and persists the preference.
      Parameters:
      intensity - 0 (very subtle) to 1 (fully fogged at far depth)

    • setPseudoLighting

      public void setPseudoLighting(boolean enabled)
      Enables or disables pseudo-lighting for all trees (current and future). Mutually exclusive with depth fog. Enabling this disables fog.
      Parameters:
      enabled - whether to apply tangent-based pseudo-lighting

    • setUpsamplingFactor

      public void setUpsamplingFactor(int factor)
      Sets the Catmull-Rom upsampling factor for all trees and rebuilds them. 1 = no smoothing, higher = smoother paths at vertex joints.
      Parameters:
      factor - upsampling factor (1-10)

    • isSNTInstance

      public boolean isSNTInstance()
      Checks whether this instance is SNT's Reconstruction Viewer.
      Returns:
      true, if SNT instance, false otherwise

    • isActive

      public boolean isActive()
      Checks whether this instance is currently active
      Returns:
      true, if active, false otherwise

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object