sc.fiji.snt.viewer

Class Viewer3D

java.lang.Object

sc.fiji.snt.viewer.Viewer3D

public class Viewer3D
extends java.lang.Object

Implements SNT's Reconstruction Viewer. Relies heavily on the org.jzy3d package.

Author:

Tiago Ferreira

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Viewer3D.ViewMode Presets of a scene's view point.

Constructor Summary

Constructors

Constructor and Description
Viewer3D() Instantiates Viewer3D without the 'Controls' dialog ('kiosk mode').
Viewer3D(org.scijava.Context context) Instantiates an interactive Viewer3D with GUI Controls to import, manage and customize the Viewer's scene.

Method Summary

Modifier and Type	Method and Description
void	add(java.lang.Object object) Script friendly method to add a supported object (Tree, OBJMesh, AbstractDrawable, etc.) to this viewer.
void	addColorBarLegend(net.imglib2.display.ColorTable colorTable, double min, double max) Adds a color bar legend (LUT ramp) using default settings.
void	addColorBarLegend(net.imglib2.display.ColorTable colorTable, double min, double max, java.awt.Font font, int steps, int precision) Adds a color bar legend (LUT ramp).
void	addLabel(java.lang.String label) Adds an annotation label to the scene.
boolean	addMesh(OBJMesh objMesh) Loads a Wavefront .OBJ file.
void	addTree(Tree tree) Adds a tree to this viewer.
Annotation3D	annotateLine(java.util.Collection<? extends SNTPoint> points, java.lang.String label) Adds a line annotation to this viewer.
Annotation3D	annotatePoint(SNTPoint point, java.lang.String label) Adds an highlighting point annotation to this viewer.
Annotation3D	annotatePoints(java.util.Collection<? extends SNTPoint> points, java.lang.String label) Adds a scatter (point cloud) annotation to this viewer.
Annotation3D	annotateSurface(java.util.Collection<? extends SNTPoint> points, java.lang.String label) Computes a Delaunay surface from a collection of points and adds it to the scene as an annotation.
double[]	colorCode(java.util.Collection<java.lang.String> treeLabels, java.lang.String measurement, net.imglib2.display.ColorTable colorTable) Runs MultiTreeColorMapper on the specified collection of Trees.
double[]	colorCode(java.lang.String treeLabel, java.lang.String measurement, net.imglib2.display.ColorTable colorTable) Runs TreeColorMapper on the specified Tree.
void	dispose() Closes and releases all the resources used by this viewer.
boolean	equals(java.lang.Object o)
int	getID() Returns this Viewer's id.
boolean	isDarkModeOn() Checks if scene is being rendered under dark or light background.
boolean	isSNTInstance() Checks whether this instance is SNT's Reconstruction Viewer.
OBJMesh	loadMesh(java.lang.String filePath, org.scijava.util.ColorRGB color, double transparencyPercent) Loads a Wavefront .OBJ file.
OBJMesh	loadRefBrain(java.lang.String template) Loads the surface mesh of a supported reference brain/neuropil.
void	logSceneControls() Logs API calls controlling the scene (view point, bounds, etc.) to Console.
static void	main(java.lang.String[] args)
Annotation3D	mergeAnnotations(java.util.Collection<Annotation3D> annotations, java.lang.String label) Merges a collection of annotations into a single object.
void	recordRotation(float angle, int frames, java.io.File destinationDirectory) Records an animated rotation of the scene as a sequence of images.
void	remove(java.lang.Object object) Script friendly method to remove an object (Tree, OBJMesh, AbstractDrawable, etc.) from this viewer's scene.
void	removeAllMeshes() Removes all loaded OBJ meshes from current viewer
void	removeAllTrees() Removes all the Trees from current viewer
boolean	removeMesh(OBJMesh mesh) Removes the specified OBJ mesh.
boolean	removeMesh(java.lang.String meshLabel) Removes the specified OBJ mesh.
boolean	removeTree(java.lang.String treeLabel) Removes the specified Tree.
boolean	removeTree(Tree tree) Removes the specified Tree.
void	rotate(float degrees) Rotates the scene.
boolean	saveSnapshot() Saves a snapshot of current scene as a PNG image.
boolean	saveSnapshot(java.lang.String filePath) Saves a snapshot of current scene as a PNG image to the specified path.
void	setAnimationEnabled(boolean enabled) Toggles the Viewer's animation.
void	setBounds(float xMin, float xMax, float yMin, float yMax, float zMin, float zMax) Sets a manual bounding box for the scene.
void	setDefaultColor(org.scijava.util.ColorRGB color) Sets the default color for rendering Trees.
void	setDefaultThickness(float thickness) Sets the line thickness for rendering Trees that have no specified radius.
void	setEnableDarkMode(boolean enable) Enables/disables "Dark Mode" mode
void	setEnableDebugMode(boolean enable) Enables/disables debug mode
void	setFont(java.awt.Font font, float angle, org.scijava.util.ColorRGB color) Sets the font for label annotations
void	setFrameSize(int width, int height) Resizes the viewer to the specified dimensions.
void	setLabelLocation(float x, float y) Sets the location for annotation labels
void	setSceneUpdatesEnabled(boolean enabled) Sets whether the scene should update (refresh) every time a new reconstruction (or mesh) is added/removed from the scene.
void	setSnapshotDir(java.lang.String path) Sets the directory for storing snapshots.
void	setSomasDisplayed(boolean displayed) Toggles the visibility of somas for all trees in the scene.
void	setSomasDisplayed(java.util.Collection<java.lang.String> labels, boolean displayed) Toggles the visibility of somas for subset of trees.
void	setTreesThickness(java.util.Collection<java.lang.String> labels, float thickness) Applies a constant thickness (line width) to a subset of rendered trees.
void	setTreesThickness(float thickness) Applies a constant thickness to all rendered trees.
void	setViewMode(Viewer3D.ViewMode viewMode) Renders the scene from a specified camera angle.
void	setViewPoint(double r, double t) Renders the scene from a specified camera angle using polar coordinates relative to the the center of the scene.
void	setViewPointCC(double x, double y) Calls setViewPoint(double, double) using Cartesian coordinates.
void	setVisible(java.lang.String label, boolean visible) Toggles the visibility of a rendered Tree, a loaded OBJ mesh, or an annotation.
java.awt.Frame	show() Displays the Viewer and returns a reference to its frame.
java.awt.Frame	show(int width, int height) Displays the viewer under specified dimensions.
boolean	syncPathManagerList() (Re)loads the current list of Paths in the Path Manager list.
void	translate(java.util.Collection<java.lang.String> treeLabels, SNTPoint offset) Translates the specified collection of Trees.
void	translate(Tree tree, SNTPoint offset) Translates the specified Tree.
void	updateColorBarLegend(double min, double max) Updates the existing color bar legend to new properties.
void	updateView() Updates the scene bounds to ensure all visible objects are displayed.
void	validate() Checks if all drawables in the 3D scene are being rendered properly, rebuilding the entire scene if not.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

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

Method Detail

getID

public int getID()

Returns this Viewer's id.

Returns:

this 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. Should be set to false when performing bulk operations;

Parameters:

enabled - Whether scene updates should be enabled

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:

updateView()

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

rotate

public void rotate(float degrees)
            throws java.lang.IllegalArgumentException

Rotates the scene.

Parameters:

degrees - the angle, in degrees

Throws:

java.lang.IllegalArgumentException - if current view mode does not allow rotations

recordRotation

public void recordRotation(float angle,
                           int frames,
                           java.io.File destinationDirectory)
                    throws java.lang.IllegalArgumentException,
                           java.lang.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:

java.lang.IllegalArgumentException - if no view exists, or current view is constrained and does not allow 360 degrees rotation

java.lang.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

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:

Tree.getLabel(), removeTree(String), updateView()

annotateSurface

public Annotation3D annotateSurface(java.util.Collection<? extends SNTPoint> points,
                                    java.lang.String label)

Computes a Delaunay surface from a collection of points and adds it to the scene as an annotation.

Parameters:

points - the collection of points defining the triangulated surface

label - the (optional) annotation identifier. If null or empty, a unique label will be generated.

Returns:

the Annotation3D

annotatePoint

public Annotation3D annotatePoint(SNTPoint point,
                                  java.lang.String label)

Adds an 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

annotatePoints

public Annotation3D annotatePoints(java.util.Collection<? extends SNTPoint> points,
                                   java.lang.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(java.util.Collection<? extends SNTPoint> points,
                                 java.lang.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

mergeAnnotations

public Annotation3D mergeAnnotations(java.util.Collection<Annotation3D> annotations,
                                     java.lang.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

updateView

public void updateView()

Updates the scene bounds to ensure all visible objects are displayed.

See Also:

rebuild()

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

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,
                              java.awt.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 java.awt.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.

show

public java.awt.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

height - the height of the frame

Returns:

the frame containing the viewer.

See Also:

show()

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

height - the height of the frame

See Also:

show(int, int)

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:

addTree(Tree)

removeTree

public boolean removeTree(java.lang.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:

addTree(Tree)

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:

loadMesh(String, ColorRGB, double)

removeMesh

public boolean removeMesh(java.lang.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:

loadMesh(String, ColorRGB, double)

removeAllMeshes

public void removeAllMeshes()

Removes all loaded OBJ meshes from current viewer

removeAllTrees

public void removeAllTrees()

Removes all the Trees from current viewer

add

public void add(java.lang.Object object)

Script friendly method to add a supported object (Tree, OBJMesh, AbstractDrawable, etc.) to this viewer.

Parameters:

object - the object to be added

Throws:

java.lang.IllegalArgumentException - if object is not supported

remove

public void remove(java.lang.Object object)

Script friendly method to remove an object (Tree, OBJMesh, AbstractDrawable, etc.) from this viewer's scene.

Parameters:

object - the object to be removed, or the unique String identifying it

Throws:

java.lang.IllegalArgumentException - if object is not supported

syncPathManagerList

public boolean syncPathManagerList()
                            throws java.lang.UnsupportedOperationException

(Re)loads the current list of Paths in the Path Manager list.

Returns:

true, if synchronization was apparently successful, false otherwise

Throws:

java.lang.UnsupportedOperationException - if SNT is not running

setVisible

public void setVisible(java.lang.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(java.util.Collection<java.lang.String> treeLabels,
                          java.lang.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.TOTAL_LENGTH MultiTreeColorMapper.TOTAL_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

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(java.lang.String treeLabel,
                          java.lang.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.BRANCH_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

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.SIDE , etc.

setViewPoint

public void setViewPoint(double r,
                         double t)

Renders the scene from a specified camera angle using polar coordinates relative to the 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(java.lang.String label)

Adds an annotation label to the scene.

Parameters:

label - the annotation text

See Also:

setFont(Font, float, ColorRGB), setLabelLocation(float, float)

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(java.awt.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 an 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(java.lang.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

setSnapshotDir

public void setSnapshotDir(java.lang.String path)

Sets the directory for storing snapshots.

Parameters:

path - the absolute path to the new snapshot directory.

loadMesh

public OBJMesh loadMesh(java.lang.String filePath,
                        org.scijava.util.ColorRGB color,
                        double transparencyPercent)
                 throws java.lang.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:

java.lang.IllegalArgumentException - if filePath is invalid or file does not contain a compilable mesh

addMesh

public boolean addMesh(OBJMesh objMesh)
                throws java.lang.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:

java.lang.IllegalArgumentException - if mesh could not be compiled

loadRefBrain

public OBJMesh loadRefBrain(java.lang.String template)
                     throws java.lang.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" "FCWB" (adult), "L1", "L3", "VNC" (Drosophila)

Returns:

a reference to the loaded mesh

Throws:

java.lang.IllegalArgumentException - if template is not recognized

See Also:

AllenUtils, VFBUtils, ZBAtlasUtils

logSceneControls

public void logSceneControls()

Logs API calls controlling the scene (view point, bounds, etc.) to Console. Useful for programmatic control of animations.

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

setTreesThickness

public void setTreesThickness(java.util.Collection<java.lang.String> labels,
                              float thickness)

Applies a constant thickness (line width) to a subset of rendered trees.

Parameters:

labels - the Collection of keys specifying the subset of trees

thickness - the thickness (line width)

See Also:

setTreesThickness(float)

setTreesThickness

public void setTreesThickness(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:

setTreesThickness(Collection, float)

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(java.util.Collection<java.lang.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(java.util.Collection<java.lang.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

isSNTInstance

public boolean isSNTInstance()

Checks whether this instance is SNT's Reconstruction Viewer.

Returns:

true, if SNT instance, false otherwise

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

main

public static void main(java.lang.String[] args)
                 throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException