Viewer


The orthogonal slice viewer displays the axial, coronal, and sagittal plane intersecting the currently selected coordinate. If a time-series is loaded, the currently displayed volume will be indicated in the viewer title bar.

Mouse Navigation

• Click or drag the mouse cursor in any slice view to change the current coordinate.
• Press [Alt] while dragging up or down in a slice view to change the zoom from 100% to a maximum of 1000%.
• Press [Alt] while double-clicking in a slice view to reset the zoom to 100%.

Keyboard Navigation

• The keyboard can be used to increment the current coordinate:

Press [Page Up] or [Page Down] to increment the current axial slice.
Press [Arrow Up] or [Arrow Down] to increment the current coronal slice.
Press [Arrow Right] or [Arrow Left] to increment the current sagittal slice.
Press [< or ,] or [> or .] to increment the current timepoint.
• Press [Spacebar] to toggle the main slice view among axial, coronal, and sagittal views.
• Press [Esc] to select a specific coordinate or timepoint.
• Press [o] to move to the origin coordinate.
• Press [c] to center the crosshairs.
• Press [Tab] to cycle through multiple viewer windows. If the viewer windows are the same size, tabbing from one to another will also move the cursor to the corresponding location in the newly activated viewer.

ROI Selection and Reshaping

• Double-click inside of a ROI to select or deselect it.
• If a ROI is selected, it can be "grabbed" by clicking inside of it and dragging. A "grabbed" ROI can be moved to a different location in the image.
• If a ROI is selected, it can be reshaped by moving the mouse cursor over one of its handle bars, then clicking and dragging to the desired shape.

ROI Line Selection

• Double-click inside of a closed line or an end-point of an open line to select or deselect it. If multiple end-points are at the selection location, those of the current ROI color will be selected, otherwise all will be selected.
• If an open line is selected, it can be "grabbed" by clicking either end-point and dragging. Closed lines will have a single selection point. A "grabbed" line can be moved to a different location in the image.
• See the Trace Line section for more information on editing lines.

ROI Point Selection

• Double-click a point to select or deselect it. If multiple points are at the selection location, those of the current ROI color will be selected, otherwise all will be selected.
• If a point is selected, it can be "grabbed" by clicking it and dragging. A "grabbed" point can be moved to a different location in the image.


File Menu


This menu handles file operations for a viewer including adding, removing, closing, and saving files.

Add Transform. With this file chooser a transform file can be loaded. This text file should contain a set of 16 white-space delimited numbers (i.e., a 4 x 4 matrix). If it is a world coordinate transform, include the keyword "world" in the file.

Add Overlay. With this file chooser an overlay image can be loaded. Any image can be overlaid onto any other image. If the overlay image is not the same dimensions as the base image, or if it contains an image-to-world coordinate transform (such as NIFTI-style images), it will be overlaid into world space mode.

Overlay Onto. This window can be used to overlay an already opened image onto another already opened image. Options are given to specify the destination viewer, as well as the lookup table. Images overlaid this way are live copies of the image in its original viewer, such that if the image is edited, the overlaid image will be edited in the same way. Another option is provided to close the overlaying viewer automatically after the overlay has been performed.

Load ROI. With this file chooser a ROI file can be loaded. ROI files are created by the application and stored as compressed bitmaps.

Import ROI. This sub-menu provides options to import an ROI from an image or text. An ROI can be imported from an image of matching dimensions, in which case any voxel which is not zero will be included in the ROI area of the current ROI color. An ROI can be imported as ROI points and lines (which can then be converted to an ROI area) using the following text-representation for each ROI on each slice: ROI[ type=(area/line/point) closed=(true/false) slice=(slice number) plane=(axial/coronal/sagittal) color=(0/1/2/3/4/5/6/7) points=(number of points to follow, e.g., 2) (31,41) (59,26) ]

Image Info. This window displays information derived from the image header file. Image Summary displays basic, format-general information about the file. Format Specific is a dump of the original header file. In the case of multi-file DICOM volumes, the format-specific information will correspond to the currently displayed slice.

Close. Closes the file. If any changes have been made to the file which have not been saved, the application will prompt the user for confirmation.

Remove All Overlays. Removes all overlays from this viewer. (Individual overlays can be removed from the toolbox overlay drop-down list.)

Remove All Transforms. Removes all transforms from this viewer. (Individual transforms can be removed from the toolbox transform drop-down list.)

Save. This will commit any changes that have been made to the file and/or ROI file. The original file(s) will be overwritten.

Save As. With this file chooser, the image can be saved in a variety of formats. All options default to the current image parameters.



Header Type. Select the output header type. Any loaded plugins that implement the WritableHeader interface will be selectable here from the drop-down list.

Data Type. Select the byte type, number of bits, and byte order of the data.

Reslice. Image dimensions, voxel dimensions, and time-series dimensions can be edited here. An option is provided to set the image dimensions to the bounds of any existing ROI.

Transform. Existing transforms can be selected here to apply to the saved image. By default the base image is saved, however an option is provided to save an overlay image instead. Options are provided to threshold the overlay (based on its current window minimum) and to mix it with the base image (creating a combination image in which the lower half of the values relate to the base image and upper half to the overlay). Interpolation type can be selected here as well.

Misc Options. Various other options can be selected here: Apply Data Scales (save the image data with the data scale applied and remove the data scale from the header); Fit Precision (if the range of data of the image is outside of the selected byte type, this option calculates a data scale and fits the data to the range); Use Compression (if supported by the header type, GZIP compression will be applied); Data Orientation (change the disk storage data order).

Save ROI. This will commit any changes that have been made to the ROI file. The ROI file is named automatically using the extension .roi.gz.

Export ROI. This sub-menu provides options to export an ROI as image or text data. The union of all ROIs can be exported as a binary image. Image type can be specified by output filename extension. An ROI can also be exported as a list of points and lines in a text file (see Import ROI).

Revert to Saved. This reloads the image from disk, discarding any changes that have been made to the image and header files.


Edit Menu


This menu handles ROI clipboard and image header editing operations.

Undo. This will undo the last ROI operation.

Redo. This will revert the last undo operation.

Cut. This copies the selected ROIs to the clipboard and then deletes them from the viewer. The ROI will be cut in either 2D or 3D depending on the ROI/VOI mode.

Copy. This copies the selected ROIs to the clipboard. The ROI will be copied in either 2D or 3D depending on the ROI/VOI mode.

Paste. This pastes the ROI clipboard contents to the current image.

Delete. This deletes the selected ROIs.

Select All. Selects all ROIs. (Double-click inside of an ROI to select it individually.)

Deselect All. Deselects all ROIs. (Double-click inside of an ROI to deselect it individually.)

Flip Orientation. This menu provides options to flip the data orientation in three dimensions: left/right, anterior/posterior, or superior/inferior. This only changes how the data is read from disk, it does not reorder the raw image data.

Origin. This window can be used to change the viewer's origin. There are two origins which can be edited here. The Image Space origin is the image voxel index which contains the anatomical origin of the image as measured from the left-anterior-superior (LAS) edge of the image. The World Space origin is the viewer voxel index which is designated as coordinate (0, 0, 0) when an image-to-coordinate transform is applied, such as are found in NIFTI image headers.

Voxel. Individual voxel values can be edited here.

Notes. Descriptive information stored in the image header can be edited here.

Update to Image Range. This can be used to re-scan the current volume and update the maximum and minimum range values.

Update to Time-series Range. This can be used to re-scan the time-series and update the maximum and minimum range values.


View Menu


This menu manages the visibility of viewer features.

Orientation. When selected, image orientation information will be displayed in the main slice view. Color-coding is used to indicate orientation confidence. See the Orientation section for more details.

Main Crosshairs. This toggles the main slice view crosshairs. (Pressing [a] can also be used to toggle the main slice crosshairs, see the Keyboard Shortcuts section.)

Lower Crosshairs. This toggles the lower slice views crosshairs.

ROI Shape Edge/Mask. This toggles whether the entire ROI mask or just the boundary is displayed. If both are selected, the mask will be semi-transparent. If neither is selected, ROI data will be not be visible.

ROI Shape Stats. When this option is selected, statistical information about the current ROI slice will be displayed. The total number of voxels occupied by the ROI is displayed in the lower, left-hand corner. (If in coordinate mode, total area instead of number of voxels will be displayed.) The geometric center of the ROI is indicated by a small round mark and the coordinate is displayed in the lower, right-hand corner. Statistical information about the image data within the ROI is displayed in the upper, left-hand corner. The centroid of image data within the ROI is indicated by a small round mark (white center) and the coordinate is displayed in the upper, right-hand corner.

ROI Line Length. This toggles whether ROI line length will be displayed.

ROI Line Angle. This toggles whether ROI line angles will be displayed.

ROI Line Guide. The ROI Lines Guide can be used to facilitate finding ROI lines, which, as two-dimensional objects, can become easily hidden within a large three-dimensional dataset. For each slice in the direction of the main slice view that contains an ROI line, a marker will be displayed in each of the two lower slice views.

Current/All Overlays. This option can be used to toggle between displaying all overlays are only the currently selected overlay in the image stack.

Orthogonal Slices. This option can be used to toggle the display of the lower orthogonal slice views.


Analysis Menu


This menu manages image and ROI statistical analysis.

Image Statistics. This menu provides options to perform analysis on the time-series, all the image volumes separately, the current volume, all the slices of the current volume separately (in the direction of the main slice view), or just the current slice. See Statistics.

ROI Statistics. This menu provides options to perform analysis on the ROI across the time-series, all the image volumes separately, the current volume, all the slices of the current volume separately (in the direction of the main slice view), or just the current slice. See Statistics.



Histogram. This window will graph a calculation of the image histogram data. The drop-down box can used be used to select among a graph of the original data, the rate of change of the data, or the cumulative sum of the data. Options are provided to change the number of bins, set the minimum and maximum range values, only include values within selected ROIs, and to exlude zero values. Contiguous bins of the histogram can be selected in a specified color (via the color drop-down box) by shift-clicking or shift-dragging across the graph. Any voxel within this range is automatically overlaid in the viewer with the same color. An option is provided to generate an ROI based on the histogram overlay. A slider is provided to control the transparency of the histogram overlay. Options to export the histogram data as text are also provided. The histogram can also be navigated using the arrow keys, as well as [Spacebar] and [Shift] for selection. Using the camera button, the histogram image can be captured and saved in PNG format. The file is named automatically and saved in the same folder as that of the image file, unless [Shift] is held down while the button is clicked.




Cross-section. Selected ROI lines will be displayed as cross-section data in this window. Using the drop-down box, data can also be presented as rate of change or cumulative sum. The currently selected ROI line within the Cross-section window is displayed in white. ROI line data can be incremented in voxels or millimeters units. In the case of millimeters, the increment size is determined by a multiplier. Clicking and dragging within the graph will cause the currently selected voxel to be highlighted in the viewer window. Options are provided to navigate through all ROI lines selected within the viewer, as well as to retain previously selected ROI lines so that they can be compared among others (displayed in grey). Clicking the y-axis will open a window allowing the range of values to be changed. The cross-section data can be exported as a text file. Using the camera button, the cross-section image can be captured and saved in PNG format. The file is named automatically and saved in the same folder as that of the image file, unless [Shift] is held down while the button is clicked.




Time-series. If time-series data is loaded, the statistics per volume within selected ROIs (points, line, or volumes) can be displayed here. Two drop-down boxes are provided: one to select the statistic (mean, max, min, standard deviation, and sum) and one to select among the original data, the rate of change, or the cumulative sum. Clicking and dragging within the display area will navigate the time-series to the selected timepoint. (The grey vertical bar represents the current timepoint.) Options are provided to navigate through all ROIs selected within the viewer, as well as to retain previously selected ROIs so that they can be compared among others (displayed in grey). Clicking the y-axis will open a window allowing the range of values to be changed. The data can be exported as a text file. Using the camera button, the time-series image can be captured and saved in PNG format. The file is named automatically and saved in the same folder as that of the image file, unless [Shift] is held down while the button is clicked.




Statistics. The statistics window will open automatically any time an analysis is performed, adding a new row. The columns include the viewer name, a description including any currently applied transforms or overlays, the total size of the image or ROI, the coordinate of the maximum voxel, mean, standard deviation, and sum. Clicking the size header cell will toggle between millimeter size and number of voxels. Clicking the maximum coordinate value header, the coordinate can be toggled to show the minimum value as well as the centroid value. Clicking the button within the coordinate value cell will navigate the viewer to that location.


ROI Menu


This menu manages ROI operations. ROIs can be created and operated on in either 2D or 3D depending on the ROI/VOI mode.

ROI Logic Calculator. This will open the viewer's ROI Logic Calculator.

Threshold to ROI. This can be used to create a new ROI based on thresholding image values. Options are provided for shrink-wrapping and thresholding to a range based on image values or as percent of image max.

Add ROI as Shape. This can be used to construct ROI spheres and cubes of a specified size. The newly created ROI is centered at the current coordinate.

Dilate. Dilates selected ROIs based on filter size.

Erode. Erodes selected ROIs based on filter size.

Close. Dilates and then erodes selected ROIs (closing small holes) based on filter size.

Open. Erodes and then dilates selected ROIs (removing small components) based on filter size.

Shrink Wrap. This can be used to shrink wrap an already existing ROI based on a threshold value or range. Options are

Propagate. This will propagate selected ROIs through a region of slices in the direction of the main slice view.

Reflect About Vertical. This can be used to reflect selected ROIs about the vertical crosshair.

Reflect About Horizontal. This can be used to reflect selected ROIs about the horizontal crosshair.


ROI Logic Calculator. This window can be used to construct a ROI logic operation using letters and operators. The new ROI is based on the logical comparison of existing ROIs.

Each color is a potential operand and is indicated by the first letter of its name (Red=r, Green=g, Blue=b, Magenta=m, Cyan=c, Yellow=y, Orange=o, Slate=s). Shortcut keys are provided to construct a union or intersection of all existing ROIs. The operation string is parsed according to parenthesis grouping and order of operations.

Here are a few examples of operation strings:

r and g   [intersection]

r or g   [union]

(not(r and g xor b)) or (y and c and (not o))   [???]




Image Menu


This menu manages image operations.

Image Calculator. This will open the viewer's Image Calculator.

Make Statistical Image from Time-series. If a time-series is loaded, this option can be used to make an image based on the statistics of each voxel across time. Statistics include mean, max, min, standard deviation, and sum.

Transform. This window provides tools to add, edit, and construct image transforms. See the Transform Tools section.

Filter. Loaded filters will appear in this menu list and can be selected to process the image. See the Add/Edit Filter section. An option to construct a rank filter (min, median, max) can also be accessed from this menu.

Build Surface. This can be used to build a surface from the base image volume. Options are provided to smooth the image, select a surface threshold, and smooth the surface. See the Surface section for more information. See the Surface Rendering Tips section for more information on these parameters.


Image Calculator. This window can be used to construct an image operation using numbers, keywords, and operators. The operation can be performed on every voxel in the volume, only voxels within the current slice, or only voxels inside or outside an ROI. In a time-series, the operation can be performed in the selected region for the current volume or across all volumes.

Within the operation string, the keyword this refers to the value of the current voxel. Values at the same location in other viewers can be accessed using the keyword other (the value is based on the location at the same millimeter distance as the voxel in this image).

The output image can either be this or a new image of the same dimensions and type.

The bottom row of buttons provides several kinds of operations: math (e.g., square root, log, sin), bool (e.g., xor, if/then), stats (e.g., mean within an ROI, standard deviation across time), and misc (e.g., generate a random number, get the column index of the current voxel).

These operations can be combined in many ways to perform simple to very complex operations on the image. The ten most recently used operations are saved and can be accessed via the history button. Here are a few examples:

this + 1   [adds 1 to every value in the image]

round(rand(0, 255))   [sets each voxel to a random whole number between 0 and 255]

this + other(1) + other(2)   [adds three images together]

(this - meanROI(r)) / sdROI(r)   [subtracts the mean of the red ROI from each voxel and divides by the standard deviation]

col * row * slice   [creates a gradient based on the voxel indices]

this >= 100   [thresholds the image at 100]

if(this >= 50, 100, -100)   [binarizes the image at a threshold of 50 using the values 100 and -100]

sqrt(round(if(this>100, rand(-99, 99) else (if(this==50, this else rand(0, 50))))))   [???]



Transform Tools. This section describes tools useful for image transformation.


Add/Edit Transform. This tool can be used to add new or edit existing transforms. The viewer is automatically updated as the transform is dynamically modified.

In the left panel, buttons are provided to select the currently applied transform, add a new transform (depends on the current coordinate mode), and invert the current state of the transform. A series of transformation steps can be saved and buttons are provided to navigate through the steps. The reset button will set the sliders to default values; if the sliders are already set to default values, the current step will be deleted. The middle panel displays the current state of the image transform. Buttons are provided to toggle between displaying the transform or its inverse; the decomposition of the transform into values of translation, rotation, scale, and skew; and a text editor to manually edit the transform values. The right panel contains sliders which can be used to dynamically adjust the transform parameters.

Clicking on a units label will toggle that slider's multiplier state between 1.0 millimeter and 0.1 millimeter steps, for finer manipulation of the transform. Pressing [Shift] before dragging a transform rotation slider will rotate about the center of array space, otherwise rotations are about the crosshairs intersection.


Landmark Registration. With this tool, an image can be put into registration with a set of coordinates associated with anatomical landmarks. The landmarks file is a text file which contains one line per landmark. Each line should contain a text label and a coordinate contained within parentheses [e.g., myLabel (23, -10, 45)]. The image will be aligned such that the landmark coordinate space origin (0, 0, 0) is at the center of the image array space.

The left panel contains a drop-down box which lists all of the loaded landmarks. Options are provided to force the transform to be 6 (rigid body), 9, or 12 parameters. The middle panel displays the current state of the image transform. Buttons are provided to toggle between showing the forward or inverse transform; the decomposition of the transform into values of translation, rotation, scale, and skew; and the RMS of the difference between a set of points and their transformed counterparts. In the top-right panel is a drop-down box which lists all added points. Buttons are provided to add a new point and to remove the currently selected point. Buttons are also provided to save work and load previous sessions.

When a point is added it is associated with the currently selected landmark. A new point is added at the location of the crosshairs intersection in the main slice view, but can be dragged to any new location after addition. Selecting a point from the drop-down box will navigate the viewer to that location.


Point-Matching Coregistration. With this tool, two images can be put into registration using point matching.

The left panel provides a drop-down box that can be used to choose among currently open viewers. Options are provided to force the transform to be 6 (rigid body), 9, or 12 parameters. The middle panel displays the current state of the image transform. Buttons are provided to toggle between displaying the transform (A to B) or inverse (B to A); the decomposition of the transform into values of translation, rotation, scale, and skew; and the RMS of the difference between a set of points and their transformed counterparts. In the top-right panel is a drop-down box which lists all point-pairs. Buttons are provided to add new point pairs and to remove the currently selected point-pair. Buttons are also provided to save work and load previous sessions.

New point pairs are added by default at the location of the crosshairs intersection in the main slice view, but can be dragged to any new location after addition. Selecting a point-pair from the drop-down box will navigate each viewer to that location.


Plugins Menu


Plugins registered with the application will be listed here for operation.

Get More Plugins. This opens the plugins webpage which posts all plugins available for download.


Window Menu


This menu manages the viewer window.

Maximize. This will expand the viewer window to it maximum height (based on screen size) and move it to the top of the screen.

Minimize. This will lower the viewer window into the holding dock or task bar.

Zoom In. This will incrementally expand the size of the window.

Zoom Out. This will incrementally reduce the size of the window.


Surface

The surface window provides a surface rendering of the base image, as well as any added overlays and ROIs. This three-dimensional model of the image volume is interactive and responds to changes in the slice viewer.

Mouse Navigation

• Drag the mouse to rotate the surface about its center.
• Press [Command] and drag the mouse to translate the surface. On a three-button mouse, a right-click can also be used.
• Press [Alt] while dragging up or down in the surface view to change the zoom. On a three-button mouse, the middle button or scroll-wheel can also be used.

Keyboard Navigation

• The surface view interacts with the slice view and mimics many of its keyboard controls. Specifically, when one or more cut planes are used, the keyboard can be used to change the cut plane locations.

Press [Page Up] or [Page Down] to increment the current axial slice.
Press [Arrow Up] or [Arrow Down] to increment the current coronal slice.
Press [Arrow Right] or [Arrow Left] to increment the current sagittal slice.
• Press [Spacebar] to toggle the main slice view among axial, coronal, and sagittal views.
• Press [Esc] to select a specific coordinate.
• Press [o] to move to the origin coordinate.
• Press [c] to center the crosshairs.

Cut-Away Selection

If one or more cut planes are selected, double-clicking a part of the surface will cause it to become cut-away, making visible any previously cut-away sections.

Coordinate Selection

Pressing [Shift] when clicking on a surface or cut plane will update the toolbox with the selected coordinate location. If an atlas is currently selected, the toolbox will also be updated with the atlas labels for that coordinate.


File Menu


This menu handles file and other general operations for the surface.

Load. Saved surfaces can be loaded here.

Get Info. This will display a window with surface-related information, including build stats and parameters.

Abort Processing. A surface build process can be aborted with this option.

Save As. Surface data can be saved here. All surfaces including added overlays and ROIs will be saved.

Export. Surface data can be exported into other formats using this option. Available export formats will depend on loaded plugins implementing the SurfaceFormat interface. See the Plugins section for more information.

View Menu

This menu manages the visibility of surface features.

Orientation. When selected, image orientation information will be displayed in the surface view.

Crosshairs. When selected, the crosshairs representing the currently selected coordinate in the viewer will be displayed.

All Slice Planes. Displays a semi-transparent slice plane corresponding to the currently selected axial, coronal, and sagittal slices in the viewer.

Main Slice Plane. Displays a single semi-transparent slice plane corresponding to the currently selected slice in the slice direction of the main slice view.

Cut Planes. Displays a semi-transparent slice plane corresponding to any currently selected cut-planes.

Shapes. Toggles the view of any added shapes (e.g., overlays and ROIs).

Surface. Toggles the view of the base image surface.

Slices. Toggles the view of the base image cut-planes.

Surface Menu

This menu provides options to change the appearance of the base image surface.

Rebuild Surface. This can be used to rebuild the base image surface (replacing the existing surface). Options are provided to smooth the image, select a surface threshold, and smooth the surface. See the Surface Rendering Tips section for more information on these parameters.

Lighting. This can be used to change the effects of lighting on the surface.

Color. This can be used to change the color of the surface and select shading type.

Axial Cut Plane. This will toggle the use of the axial cut plane.

Coronal Cut Plane. This will toggle the use of the coronal cut plane.

Sagittal Cut Plane. This will toggle the use of the sagittal cut plane.

Go To Saved Angle State. This option will rotate the surface view to the last saved (or the default) angle state.

Save This Angle State. With this option, the current rotation angle state of the surface view can be saved. See Go To Saved Angle State.

Shapes Menu

This menu provides options to build and change the appearance of added surfaces. Added surfaces may be built from overlays or ROIs or loaded from file.

Load Shape from File. This option will load and add a shape from file.

Add Overlay as Shape. This can be used to build a surface from an overlay. Options are provided to smooth the overlay image, select a surface threshold, and smooth the surface. See the Surface Rendering Tips section for more information on these parameters.

Add ROI as Shape. This can be used to build a surface from a ROI. Options are provided to smooth the ROI image, select a surface threshold, and smooth the surface. See the Surface Rendering Tips section for more information on these parameters.

Added Shapes List. All added shapes will be found in this list. Each will have a menu that includes options to change the surface lighting and color, as well as options to hide and remove the shape from the surface view.

Show/Hide All. This will toggle the visibility of all the added shapes in this surface view.

Remove All. This remove all shapes from the surface view.

Window Menu

This menu manages the surface window.

Maximize. This will expand the surface window to it maximum size (based on screen size) and move it to the top of the screen.

Minimize. This will lower the surface window into the holding dock or task bar.

Zoom In. This will incrementally expand the size of the window.

Zoom Out. This will incrementally reduce the size of the window.

Stick to Viewer. When selected, this will cause the surface window to move along with the viewer window.


Toolbox

The toolbox is the executive window of the application. It displays information and provides controls for the active viewer and for global options. If multiple viewers are open, the information and options presented by the toolbox will change depending on which viewer is currently active.


Coordinate and Value Display. If the mouse cursor is within the bounds of the active viewer's image, its coordinate (orange) and the image value at that coordinate (white) will be displayed here. If an overlay is selected, the image value will represent that of the overlay image. The coordinate format depends on the currently selected coordinate type.


Image Stack. All images loaded in the currently active viewer are organized here and can be accessed via an ordered drop-down list. The icon displayed on the image stack button represents the color table of the currently selected image. The stack order of overlay icons represents the stack order of overlay images, with the base image icon always at the bottom. Hovering the mouse cursor over an item in the drop-down list will open a sub-menu with options to hide and remove the overlay, move it up or down the stack, change the color table, adjust transparency, and get information about the overlay image file. If only the base image is in the stack, pressing the button will open a menu to chnage the color table and get information about the image. This is not a global feature and will change depending on the active viewer.

Transform Selection. All loaded transforms for a viewer can be selected here via a drop-down list. Depending on the current coordinate type selection, this list will represent a list of all image or world transforms. The icon displayed on the transform selection button indicates the current transform. The number in the lower-right hand corner represents the transform index, with zero indicating none selected (i.e., identity image transform). Hovering the mouse cursor over an item in the drop-down list will open a sub-menu with options to edit, remove, and get information about the transform. This is not a global feature and will change depending on the active viewer.

Coordinate Type Selection. The coordinate type can be selected here via a drop-down list. The selection will determine how the image coordinates are formatted in the coordinate and value display area and will determine which set of transforms (image or world) are displayed when the transform selection button is used. Choosing a coordinate space associated with anatomical labels will automatically open the label display area. This is not a global feature and will change depending on the active viewer.


This represents voxels and will display the voxel index location.


This represents a generic coordinate space and will format the coordinates using voxel spacing and origin information.


This represents World Space and will format the coordinates using voxel spacing, origin information, as well as possible index-to-world coordinate transforms (such as are found in NIFTI image headers). In this mode, a voxel index within the viewer is designated as the origin and the image origin is aligned to it. By default, the World Space origin is at the center of the image.


ROI/VOI Mode Toggle. The VOI and ROI modes can be toggled with this button. In VOI mode, the entire region-of-interest volume is affected. In ROI mode, only the main slice view is affected. This mode is considered for most all menu-driven ROI operations, including ROI clipboard operations. This is a global feature.

ROI Color Selection. The current ROI color can be selected here via a drop-down list. If multiple ROI colors are displayed, the current ROI color will appear on top.

ROI Tool Selection. The current ROI tool can be selected here via a drop-down list. This is a global feature.


Navigation Mode. This mode is required to individually select, move, and reshape ROIs.

Paint Tools. With these tools, an ROI can be created and edited as with a paint brush. Options are provided to set the paint brush tool shape and size. The size of the tool can be changed from the keyboard using the [Minus] and [Plus] keys. The number of slices that are affected is determined by the Set Tool Slice Range option. An option is provided to set an explicit range on which these tools will operate.


Edit Mode. This is a hybrid of Erase Mode and Paint Mode. If the mouse cursor is pressed and dragged starting outside of the ROI, it will behave as Erase Mode. If the mouse cursor is pressed and dragged starting inside of the ROI, it will behave as Paint Mode. If an explicit range is set, only those voxels that are both edited and in range will be affected.


Paint Mode. This mode can be used to fill ROI area. If an explicit range is set, only those voxels that are both painted and in range will be affected.


Erase Mode. This mode can be used to erase ROI area. If an explicit range is set, only those voxels that are both erased and in range will be affected.

Trace Tools. With these tools, an ROI can be created by tracing a region. An option is provided to set an explicit range on which these tools will operate.


Draw Region as Rectangle. This tool can be used to trace a new rectangular ROI. If an explicit range is set, only those voxels both in the range and in the rectangle will be included in the ROI.


Draw Region as Ellipse. This tool can be used to trace a new ellipsoidal ROI. If an explicit range is set, only those voxels both in the range and in the ellipse will be included in the ROI.


Trace Region. This tool can be used to trace new ROIs of any shape. The tool can either be dragged across the image or clicked in a point-to-point fashion. The polygon will be closed automatically once the end point reaches near to the start point. The new ROI will not be generated until the polygon is closed. Use [Backspace] or [Delete] to remove a polygone in progress. If an explicit range is set, only those voxels both in the range and in the polygon will be included in the ROI.


Trace Line. This tool can be used to trace new ROI lines. It can either be dragged across the image or clicked in a point-to-point fashion. The line can either be closed or open and will be closed automatically once the end point comes near to the start point. Use [Enter] to commit a non-closed line in progress. Use [Backspace] or [Delete] to remove a line in progress.

A number of additional options are available while in line mode. Control-clicking inside of a closed ROI line will convert it into a ROI region (and vice versa). Control-clicking the line start-point (or end-point if the line is open) will smooth the line. Double-clicking an open line end-point can be used to continue the line (and can be closed if the extension reaches the other end-point). Double-clicking a point of a closed line will break the line at that point.

Individual points can be grabbed and moved, as well new points can be added by grabbing the line between already existing points. While a point is grabbed, [Backspace] or [Delete] can be used to delete it.


Add Points. This tool can be used to make individual ROI points.

Magic Wand Tools. With these tools, sub-regions of ROIs can be selected and operated on. To select a sub-region, first set the appropriate current ROI color, then click the sub-region of that ROI with the magic wand tool. Sub-regions may be selected in 2D or 3D depending on the ROI/VOI mode. An option is provided to set an explicit range on which these tools will operate.


Add Region. This tool can be used to construct an ROI. Clicking an image voxel will include it in the current ROI as well as any neighboring voxels of the same or near value. An option is provided to set the relative range, or tolerance, of this tool. Note, an explicit range will supersede this relative range.


Preserve Region. This tool can be used to select sub-regions of ROIs for preservation, while deleting all ROI area outside of the selected region.


Erase Region. This tool can be used to delete selected sub-regions of a ROI.


Erode Region. Using this tool, selected sub-regions (which can be further limited by the explicit range) can be eroded.


Dilate Region. Using this tool, selected sub-regions (which can be further limited by the explicit range) can be dilated.


Copy Region. This tool can be used to copy selected sub-regions onto the clipboard.


Image Capture. Depending on which window is currently active, the main slice view or the surface view can be captured and saved to disk as an image. The file is named automatically based on the image file name and will increment a four-digit number if the file already exists. See the Screen Capture section of Preferences for more information. Alternatively, pressing [Shift] while clicking the camera button will open a file dialog that can be used to select a destination folder and file name.


Window Controls. The left value represents the screen minimum or what value will appear completely black. The right value represents the screen maximum or what value will appear completely white. The sliders can be used to dynamically adjust the settings within this range. Moving the middle slider adjusts both end-sliders equally in the same direction (brightness). Double-clicking or shift-clicking an end-slider and moving it will adjust both end-sliders equally in opposite directions (contrast). Double-clicking or shift-clicking the middle slider will reset the sliders to the default position. Triple-clicking or shift-control-clicking the middle slider will both reset the sliders to the default position as well as reset the range to the original values. If an overlay is selected, these values will represent that of the overlay image. The actual color mapping will depend on the currently selected color table. Depending on the Options Menu setting, this may affect all viewers or only the currently active viewer.



Anatomical Label Display. This display area will be visible when an atlas is selected. If the coordinate is in range, it will display up to four labels: orange being gross anatomical labels and white being finer anatomical labels. See Select Atlas for more information.


Open Menu


This menu manages the opening of image files.

Open Image. Images can be opened via this file chooser. [Command][o] is a keyboard shortcut to open an image, while [Command][Shift][o] indicates that the image is to be opened as an overlay onto the currently active viewer.

Open DICOM Folder. Folders that contain DICOM files can be opened here. See DICOM Folder for more information

Open Raw Image. Images which lack a recognized file header, can be opened here. See the Open Raw Image section.

Add New Image. New images can be generated using this option. See the Add New Image section.

Recent Images. The ten most recently opened images will be listed here for quick access.



DICOM Folder. Folders (including external media such as CD-ROMs) that contain DICOM files can be accessed using this option. Folders are searched up to three sub-folders deep. Each tab represents a single DICOM study. Each item within a tab consists of one DICOM session or volume. Table header cells can be clicked to provide different kinds of information contained in the DICOM header. The first column contains descriptive information about the patient and DICOM session. The second column contains image and voxel dimensions. The third column contains slice information (number, size, and direction). Once an image has been opened, the corresponding table row will be highlighted.



Open Raw Image. This window can be used to specify image parameters when a recognized header file is not available. Options are provided to specify image size, voxel size, datatype, number of bytes, byte order, spatial and temporal units, as well as preferred data orientation. Data scales can either be entered as a single number (global) or as a file which contains one data scale per line for each slice in the image. Image offset is calculated based on the file length and image parameters.



Add New Image. This window can be used to generate a new, blank image. Options are provided to specify image size and voxel size. A new image can also be added as a copy or subset of data (specified as the bounds of an ROI) from an existing viewer.


Options Menu


Session-level and application-level options can be managed here.

Use Global Window. If selected, the window controls affect all the viewers.

Use Group Overlay Window. If selected, all overlays in a viewer will use the same window controls.

Link Navigation. If selected, navigation is synced among the viewers. When synced, navigating in one viewer simultaneously navigates (by the same amount and in the same direction) in all other viewers.

Add/Edit Color Table. Color tables (or LUTs) can be managed here. See the Add/Edit Color Table section.

Add/Edit Filter. Filters can be managed here. See the Add/Edit Filter section.

Add Plugin. Compiled Java classes that implement one of the plugin interfaces recognized by Mango can be registered with the application via this menu option. See the Plugins section.

Install Utitlies. This tool can be used to facilitate the installation of command-line utilities included with the application. It creates the executable scripts to run the utilities as well as updates shell initialization files.

Select Atlas. Any plugins that implement the Atlas interface can be selected here to show atlas labels relative to the current mouse coordinate. If the plugin contains options, selecting it will open its options dialog. The application must be in either Coordinate Space or World Space in order for atlas labels to be displayed.

Preferences. Application-level options can be managed here. See the Preferences section.



Add/Edit Color Table. This window can be used to create new and edit existing lookup tables (LUTs). Each knot along the color map is associated with a percent, a red value, a green value, a blue value, and a boolean option for using a gradient. Percent indicates at what distance along the color map a knot is located (0 to 100). The red, green, and blue values indicate the color the knot represents in RGB color-mixing space (0 to 100). The gradient option indicates whether the colors should be solid or gradiently composed between a knot and the knot above it. Clicking a marker will display its current values. Options are provided to export and import color table files.



Add/Edit Filter. This window can be used to create new and edit existing filters. A filter can be constructed as a kernel or as an expression. Expressions can use keywords -- col, row, slice, and time -- to indicate the value of the dimension index. A button is provided to open an expression editor, if necessary. Options are also provided to set the size of the kernel as well as to normalize it before processing. Kernels can be one-dimensional (temporal filtering), two-dimensional (slice filtering), or three-dimensional (within and across slice filtering). An option is also provided to indicate that the multi-dimensional filter is separable into one-dimensional kernels (for faster processing). A point-spread image is provided which illustrates the kernel of the currently selected filter. Hovering the mouse over the image will update the value label. If the filter is three-dimensional, dragging the mouse up and down within the point-spread image will move it throughout the third dimension. Options are provided to export and import filter files.



Preferences. This window is used to manage application-wide settings.

• Interpolation. This option will affect the speed and quality of how transformed images are displayed on the screen.

• Listen for Files. When selected, the application will listen for file paths on the specified port. If a path is detected, the file will be opened. (The command-line program mango can be used to send file paths to the GUI. See Install Utilities and the Command-Line Utilities section of the Download page for more information.)

• Quick Toggle. Used to select two tools associated with the quick key shortcut. See the Keyboard Shortcuts section.

• Check for Update. Select whether the application automatically checks for a more recent version during launch. A manual check can be performed at any time via the Help menu.

• Screen Capture. The location can be set to the current image's folder or to the desktop.

• Function Keys can be used to assign any function key from F2 through F24 to viewer menu items (including plugins and filters). In some cases, if a function key is assigned to an operating system function, the application may not respond to its assignment.
Help Menu


The user guide and application info can be accessed here.

User Guide. This will open the user guide.

Check for Update. This checks the application webpage for a version more recent than the current one in use.

License Agreement. Displays the terms of use.

About Mango. This will display version and contact information.


Window Menu


This menu manages control over all the application's windows.

Minimize All. This will minimize all windows.

Bring All to Front. This will un-minimize and bring all windows associated with this application to the top of the operating system's window stack.

Stack Viewers. This option can be used to neatly re-stack all open viewers.

List of open windows. All currently open viewers are listed and grouped with their associated windows. The active viewer is indicated by a checkmark.

Show/Hide Image Browser. This toggle can be used to show or hide the image browser. See Image Browser.

Show/Hide Statistics. This toggle can be used to show or hide the statistics window.

Show/Hide Console. When selected, the application console will be shown.


Image Browser. This tool can be used to quickly preview several images without the necessity of having to open each one in a viewer. The image chooser area is a live representation of the underlying files. Only files which contain recongnized header information are listed. Multi-file images (such as DICOM) are rendered into a single entry in the list. The folder hierarchy can be traversed by double-clicking a folder name or by selecting a parent folder from the selection box. Multiple tabs can be opened to quickly switch between two or more folders. Selecting an image will show its preview information and slice. Multiple images can be selected using [Shift] and [Command] keys. The image list can be filtered by name or extension using the filter box in the lower right-hand corner. Selected images can be opened by double-clicking them, selecting and pressing [Return], or by the use of the open button. To overlay the images (onto the current viewer) instead of opening them in a new viewer, add [Shift] or use the overlay button. The list can be navigated using [Arrow Up] and [Arrow Down]. The hotkey [b] will toggle the show/hide state of the window.



Keyboard Shortcuts

If a shortcut indicates the use of a command key, the actual key to press will be dependent on the operating system. On Mac OS, the command key is the apple or command key. On Windows and Unix/Linux, the command key is the control key.

Fast-Switching Toolbox Keys

[f] Quick Toggle. Toggles between two ROI tools. See the Preferences section.
[Shift][f] Cycles through the four most recently selected tools.
[d] Cycles among those ROI colors that have been used, defaulting to a toggle between red and green.
[s] Toggles ROIs on/off.
[a] Toggles main crosshairs on/off.

 Viewer Navigation Keys

[Spacebar] Toggle the main slice view in a clockwise rotation.
[Page Up] or [Page Down] Increment the axial slice.
[Arrow Up] or [Arrow Down] Increment the coronal slice.
[Arrow Right] or [Arrow Left] Increment the sagittal slice.
[< or ,] or [> or .] Increment the timepoint.
[Esc] Opens a window that allows an exact coordinate to be chosen.
[o] Navigates the viewer to the image origin.
[c] Navigates the viewer to the center of the image.

 Menu Keys

[Command][o] Opens a file chooser to select an image to open.
[Command][Shift][o] Opens a file chooser to select an image to overlay.
[Command][i] Opens the Image Info window.
[Command][w] Closes the viewer.
[Command][s] Saves the image.
[Command][Shift][s] Opens the Save As window.
[Command][z] Undo an ROI operation.
[Command][Shift][z] Reverts an undo operation.
[Command][x] Copies then deletes selected ROIs.
[Command][c] Copies selected ROIs.
[Command][v] Pastes the contents of the ROI clipboard.
[Delete] Deletes an active polyline or selected ROIs.
[Command][a] Selects all ROIs.
[Command][Shift][a] Deselects all ROIs.
[Command][m] Minimize the window.
[Command][Minus] Decrease the size of the viewer window.
[Command][Plus] Increase the size of the viewer window.
[F1] Opens this user guide.
[F2] through [F24] Can be assigned to any viewer menu item already not assigned. See Preferences section.

 Other Keys

[Command][0] Fill outside of the union of all selected ROIs with the value 0.
[Command][Shift][0] Fill inside of the union of all selected ROIs with the value 0.
[Command][p] Executes the camera button.
[Backspace] Behaves the same as [Delete].
[Minus] Decreases the size of the ROI tool.
[Plus] Increases the size of the ROI tool.
[r] While being pressed, reduces the size of the ROI tool by 75%.
[t] Brings the toolbox to the top of the window stack.
[b] Shows/hides the Image Browser.
[Command][q] Quits the application.
Most dialog windows can be navigated using the [Tab] and arrow keys. [Esc] will close an open dialog window.
Technical Details

Surface Rendering Tips

In most cases, the default parameters will produce a surface with a high degree of detail while still maintaining good rendering performance. Changes to these values can have dramatic effects on the amount of time it takes to produce the surface, the amount of surface data generated, and the overall resolution of the surface. If too much surface data is generated, dynamic performance will suffer (and in extreme cases can produce an "out of memory" error). Smoothing will tend to reduce the amount of surface data generated, removing noise, while preserving most of the surface features. However, too much smoothing can filter out relevant surface features and degrade the quality of the rendering.

Image Smoothing. This will perform a gaussian smoothing filter on the image data, prior to building the surface, removing image noise that would consequently produce surface noise. Increasing the kernel size or width will increase the effect this smoothing operation will have. To turn this feature off, set the values to zero.

Surface Threshold. The surface threshold controls at what image intensity the surface will be constructed. (To get an idea of what the surface will look like before building it, create a threshold-based ROI at the same intensity level. The boundary of this ROI will approximate the surface.) If the range option is selected, then surface data will be generated at both the minimum and maximum boundaries. Increasing the minimum surface threshold value will tend to produce less noisy surface data with more features.

Surface Smoothing. After the surface has been generated, surface smoothing can be used both to reduce noise as well as to reduce the overall amount of data, thereby increasing performance. Surface smoothing works by removing redundant surface points or points that are not contributing to surface features. The feature error option sets the threshold at which a point might be removed. The larger the feature error threshold, the more a point will need to be different from its neighboring points in order to be considered a feature. That is, increasing the feature error will remove more points, causing a smoother surface. The feature angle option tells the surface renderer the minimum angle that neighboring points (i.e., triangles) need to have in order to be considered a feature. Setting this value to zero would indicate that any deviation between neighboring points is a feature. To turn surface smoothing off, set the number of iterations to zero.

After a surface has been built, its lighting and color properties can be further adjusted.

Lighting. Ambient and diffuse lighting both effect the light reflected off of the surface. The emissive lighting option controls the amount of light emitted by the surface. Specular and shininess control surface highlights (e.g., to make a very glossy-looking surface, set these values to their maximum).

Color. Surface color can be changed here as well as shading preference.

Header File Types

The following image header types are supported: Analyze (rw), NIFTI (rw), NEMA (rw), and DICOM (basic, read-only). Data without a recognized header type can be opened using the Open Raw Image utility or by making a plugin which implements the ReadableHeader interface.

Image Data Types

The following image data types are supported: 8, 16, and 32-bit integer and 32-bit floating point. RGB data (8-bit per channel) is supported, however channel data is summed and rendered as a grayscale, intensity image. Byte order, image offset, and data orientation specification are supported. Image data is assumed to be contiguous. The image data file may be compressed using GZIP.

Image Orientation

Image orientation is stored differently based on header format and not all orientations are supported by all formats. By default, images are shown in RAS Neurological format.

Correct orientation within a viewer is dependent on sufficient and accurate information being stored in the image header file (this includes how to read the image data file in regards to XYZ as well origin specification). Because many images rely on "default" orientation, a best guess will be attempted when incomplete information is provided. Orientation confidence is indicated by orientation label color (white = sufficient information; yellow = incomplete/suspicious information; red = no information, default). See the View Menu for more information on how orientation is displayed within the viewer.

NIFTI orientation and origin are stored as a transform (qForm). This format supports orientations at oblique angles. Orientations stored as transforms which contain oblique rotations, scaling, and translations other than origin offset (qForm and sForm) can be applied via the transform drop-down list while in World Space mode.

Analyze orientation is stored as a numeric code which indicates data ordering as well as axis sense. Voxel dimension parameters with negative values are also used to indicate negative axis sense (but this is non-standard and not supported by all software). The following data orderings are supported: XYZ, XZY, YZX (fastest-changing first). Origin is stored as a set of three two-byte integers indicating the offset of voxel indices (beginning with an index of 1).

NEMA orientation is stored as a text string consisting of 6 characters: the first three characters indicate data order and the last three indicate their respective axis sense (e.g., XYZ+--). This format supports every possible orientation orthogonal to the native data organization. Origin is stored as a set of three values indicating offset in millimeters from the LAS boundaries.

DICOM orientation is stored as text strings in the DICOM header [tags (0020, 0032) and (0020, 0037)] and supports orientation at oblique angles. Orientations stored as oblique rotations can be applied via the transform drop-down list while in World Space mode.

Why Java?

Java was chosen as the development language for Mango primarily for its cross-platform ease and flexibility. Mango is a GUI-based application and Java lends itself to building feature-rich, cross-platform GUIs. Additionally, Java is often the first computer programming language introduced to students. With the Java plugin API, Mango serves as a learning tool, giving students with at least basic programming experience the ability to write plugins that interact with image data in a GUI environment.

Acknowledgements

Mango makes use of JAMA for matrix calculation, niftilib for NIFTI orientation conversion, QuaQua for some Mac OS X Look-and-Feel, and Java3D for surface rendering.