iiV User's Guide (Version 1.1.8.1)

iiV, Internet Image Viewer, is a brain imaging data display tool written in Java^tm1.1. Java provides platform independence to run in any Java Virtual Machine (JVM) supporting Java 1.1. The Java language, with its Abstract Window Toolkit (AWT), simplified iiV development by providing basic tools for creating the General User Interface (GUI) and by providing an excellent object oriented environment for building easily extensible code. By extending the Java Applet class, iiV can execute from within a web page (as long as the browser supports Java 1.1) creating an interactive environment for displaying brain imaging data on the web.

The following list outlines the main features of iiV:

displays 3-D data sets as images sliced perpendicular to any of the 3 major axis
displays maximum (minimum) intensity projections (MIP)
supports ANALYZE, Siemens/ECAT/ECAT7, Stimulate SDT, DICOM, NIfTI, NEUROSTAT 3D-SSP dat, and raw data formats
extends to read new data formats with no modifications to existing code
displays GIF, JPEG and PPM images
displays color bars, text objects, simple shapes and voxels values
keeps each displayed item as an individual object for independent updating of settings
drags objects to any display location
labels data slices with orientation and slice numbers (or real world coordinates)
permits image transforms of zooming, rotating, cropping, and flipping
supports independent color maps for each displayed object
allows complete control of linear scaling for mapping input data to display colors
supports color map opacity levels from opaque to transparent for overlaying images with see-through
overlays data on top of displayed data duplicating the slice, view, zoom, rotation, etc.
groups objects to lock their relative positions
displays pixel locations and values for multiple objects simultaneously
tracks pixel location with cross hairs over objects
quantitates pixel values to reflect true data values
transforms pixel locations based on an input transform to reflect convenient coordinates (e.g., Talairach, MNI space)
records pixel values and locations
updates any data slice and crosshairs to automatically display the same location the mouse was released over another data slice
permits fine adjustment of cross hair or object positions via arrow key
permits slice and cross hair jump to specified location
hides control menu and dialogs for maximizing the display area
includes a script language that duplicates and extends the GUI commands with text commands
saves the display contents as a script allowing redisplay with editable objects
saves the display contents as a GIF or PPM image
saves users' preferred startup settings
supports full undo/redo
supports cut and paste to

iiV is composed of a main display window and multiple dialog windows. The display window displays data slices, voxel values, images, color bars, simple shapes, and text objects. Each displayed object may be individually selected, moved, zoomed, rotated, etc. Mouse input over the display panel enables object selection, object dragging, pixel value and location viewing, etc. Either the top menu bar on main display window or the separate main control panel control what is displayed in the main display window. They contain buttons, text areas, menus and sliders for reading and displaying files, controlling display options and launching other dialog windows. Dialog windows extend the options and controls in logical modules.

This document outlines the basic tasks available via the general user interface (GUI). It also describes the scripting language. More information for programmers can be derived from iiV's API.

Reading files

Reading files is the act of interpreting the file format and bringing all the data stored in a file into memory. iiV is designed to work primarily with 3 dimensional voxel data. iiV also works with some 2d image formats and iiV script files. When a file is read its data is kept as a data object which remains in memory as long as other objects refer to it. The data may or may not be immediately displayed (or run in the case of a script) depending on whether “read displays” is on or off. Keeping the original data in memory allows displaying voxels as scaled and mapped colors while being able to refer to original values and reduces the need to reread the same file.

Input file types supported and selecting

iiV supports reading NIfTI, ANALYZE^tm, Siemens/ECAT/ECAT7, Stimulate SDT, DICOM, and raw data formats; JPEG, GIF, and PPM image formats; iiV script files; and 3D-SSP dat files. NIfTI, ANALYZE, ECAT, ECAT7, Stimulate SDT, and DICOM are 4 dimensional data formats displayed as multiple 2 dimensional slices. The raw data format also supports 4 dimensional data with the user inputting word size, dimension, offset, increments, orientation, and quantification values. JPEG and GIF are 2 dimensional image formats supported directly by Java. PPM is another image format supported by classes from ACME Labs. iiV script files are ASCII text files containing commands specific to iiV for displaying complex combinations of objects. The 3D-SSP dat files are produced by NEUROSTAT software and contain voxel locations and values that iiV displays as 8 surface views with a mapping file that transforms locations to Talairach space.

File types for reading new files may be selected by pulling the submenu labeled “Read File Type:” under the main “File” menu and also via a choice menu in the main control panel. With the default choice "Standard File Types" the read operation attempts reading the file as a script then as an ANALYZE, ECAT 6, ECAT 7, DICOM, JPEG, GIF, and PPM format file. The choice menu also lists the following individual file types: "Raw File Type" for reading raw files; "CNUDisplayScript" for reading only script files; "CNUAnalyzeImgFile" for reading ANALYZE files; "CNUEcatImgFile" for reading ECAT 6; "CNUEcat7ImgFile" for reading only ECAT 7; "CMRRSdtImgFile" for reading Stimulate SDT files; "DICOMImgFile" for reading DICOM files; and "CNUStdImgFile" for reading JPEG, GIF or PPM files. These odd choice names are actual Java class names. New file classes can be added to the select list from the "File Types" dialog.

Raw file type settings

Raw file type settings are stored as default static values in the CNURawImgFile class. Changing these defaults is done in the "File Types" dialog brought up by pressing the "Add File Types/Raw Settings…" button under the main “File” menu or in the main control panel, or by selecting the “File Types/Raw Settings Dialog” in the main “View” menu. This dialog shows raw file values that may be edited and then applied by pressing the "Apply to Defaults" button before reading the raw data. The "Set to Current" button grabs settings from the currently selected display object.

Settings for raw files include the following:

§ Skip bytes - the number of 8-bit words to skip in the file before finding raw data

§ Data type - the word format type for each voxel. Currently supported types are byte, unsigned byte, short, unsigned short, integer, long, float, and double.

§ Data conversions - conversion that must be performed on the data before interpreting the format type. Currently supported conversions are no conversion, swap bytes, swap shorts, reverse bytes, and VAX to SUN. The VAX to SUN conversion is for floating point numbers and does some odd manipulations of exponents as well as reversing bytes.

§ Dimensions - the x, y, z and i dimensions

§ Manual increments - sets spatial increments for each dimension other then the defaults based on dimensions. Increments are taken as multiples of words so if the data type is integer which is 4 bytes long an x increment of 1 jumps 4 bytes (the current voxel) to get to the next voxel along the x dimension.

§ Orientation - whether the x and y dimensions represent transverse, coronal or sagittal slices and whether increasing values represent left or right, anterior or posterior and inferior or superior

§ Spatial resolutions - the real world distance in meters between centers of voxels

§ Quantification factor - the factor to multiply each voxel value by to get a real world value

Note - settings don't apply until "Apply to Defaults" is pressed and a new read is done which might require read anew.

Adding a new file type

Adding new file types is also done in the "File Type" dialog brought up by pressing the "File Types" button.

In the "File Type" dialog the name of a valid class is typed into the text field and the "Add File Type Class" button pressed. iiV searches to find the class and verifies that the class extends java.awt.Component, CNUData, or CNUDisplayScript before adding it to the selection menus on the main display panel and in the main control panel. When added the new class is automatically selected and ready for the next read. Besides extending one of the aforementioned classes, the new class must also have public constructor that accepts a String as the only parameter to be valid. This string contains the file name to be read. The valid constructor is not checked for until a read is attempted.

Compressed files

When an input file name ends with ".gz" iiV assumes it is a GZIP compressed file. ANALYZE, ECAT, raw, PPM, and script input files may be in the GZIP compressed format. JPEG and GIF files have their own compression techniques and may not be GZIP compressed. When an ANALYZE file is compressed both the header ".hdr" and image ".img" files must be compressed because of file naming conventions.

Entering path on text field line

A file may be selected by typing its name in the text field under the browse button, in the main control panel, and then hitting return to read and possibly display the file (see automatic display). The field becomes inactive while reading or displaying. After reading the file becomes available in the previous list. Selecting a file via browsing or from the previous list replaces the text in this field.

Browsing

File selection may also be achieved via the "Browse" button under the main display “File” menu or in the main control panel. This brings up a browse window that may be different for different platforms and gives the ability to navigate the file architecture looking for images. When accepted a browsed file is read, entered into the text field line, entered in the previously read list, and possibly displayed (see automatic display). The "Browse" button changes to a red "Break" button while reading or displaying a file (see breaking or canceling a read).

Selecting from previous list

After reading a file it is added to the previous list which may be accessed by pulling the “files” menu right under the “File” menu on the main display menu bar or as a list shown under file text field in the main control panel. When a file from the previously list is selected the file is entered into the text field line and possibly displayed (see automatic display). The list becomes inactive while reading or displaying a file.

Automatic display

When any of the above mentioned methods reads a file, portions of the file are automatically displayed depending on whether the "Read Displays" box is checked. Having the box checked is the same as hitting the "Display" button whenever a read occurs. The “Read Displays” box is seen both in the main display “File” menu and in the main control panel.

Read anew

Reading an image normally checks the last displayed object, all existing displayed objects and undo/redo objects to prevent rereading the same data. Selecting the "Read Anew" check box negates the search causing the file to always be opened and read again. This slows things down and eats memory but may be needed if a file is being updated by another program. The “Read Anew” box is seen both in the main display “File” menu and in the main control panel.

Breaking or canceling a read or display

Reading and displaying are performed in a separate thread. During either of these operations a red “Break” button appears on the main display menu bar and in the main control panel the "Browse" button becomes a red "Break" button. Pressing the "Break" button aborts the thread performing the read or display. While the red "Break" button is present the "Display" button and previous files list are disabled. Other tasks are still enabled but may or may not effect what is currently being read or displayed (i.e. if one forgets to set positive scaling before hitting display quickly changing it to positive scaling, while the red "Break" button is present, may save the day).

Related script commands:

Displaying

Displaying is the act of creating display objects from data read. If the file read is a script displaying runs the script which may or may not display anything.

Displaying

Hitting the “Display” button, either under the “File” menu or in the main control panel, displays the last read or displayed file. How it gets displayed depends on the current mode for limits, cropping, orientation, flipping, labels, zoom, color model, and scaling.

Related script commands:

display(); // displays the last read or displayed file
position(x_integer, y_integer); // sets the display position for next object displayed

Displaying different views

The view mode is selected from a pull right “View mode:” menu under the “File” menu in the main display menu bar or from the choice menu right of the “Display” button in the main control panel. Three dimensional data may be viewed as slices perpendicular to one of the major axis. The view mode needs to be selected before displaying. Transverse specifies slices perpendicular to a z-axis running from the inferior (bottom) to superior (top) of the brain. Sagittal slices are perpendicular to an x-axis from the left to right of the brain. And, coronal slices are perpendicular to a y-axis from the posterior (rear) to anterior (front) of the brain. Most brain imaging data contains info on how the views are stored. If not iiV defaults to assume that the fastest changing dimension corresponds to the x-axis or left to right. The second fastest corresponds to the y-axis or front to back. And the third dimension to the z-axis or bottom to top.

Related script commands:

view("coronal"); // sets view mode to coronal
view("sagittal"); // sets view mode to sagittal
view("transverse"); // sets view mode to transverse

Displaying limited and cropped slices

When displaying an image limits may be set to contain what is displayed in all 4 dimensions. The fourth dimension, labeled i, is supported by many brain imaging formats and may be associated with time or just another batch of 3 dimensional images. The first 3 dimensions are designated as x, y, and z as discussed in displaying different views. Any 2 of the first 3 dimensions may be associated with the slices displayed as 2 dimensional images in the display window. Which dimensions depends on how data is stored in the image file and the currently selected view mode of transverse, coronal, or sagittal. The slice number and limits corresponds the remainder of the first 3 dimensions. To have affect the i dimension and slice dimension limits are set before displaying to determine how many display objects are created. The limits for the displayed 2 dimensional image may be set as cropping during or after an objects initial display.

Limits and cropping are controlled by a “Limits/Cropping” dialog and enabling checkboxes. The dialog is brought up by pressing the “Crop/Limits…” button in the main display “Tools” menu or the main control panel or by selecting “Limits/Crop Dialog” checkbox in the “View” menu. The “Tools” menu, “Limits/Cropping” dialog and main control panel have checkboxes called “Limit i dim”, “Limit slices”, and “Crop new” that enable or disable the limits and cropping. Selecting "Limit i dim" limits the i dimension of slices that appear during a display operation. Selecting "Limit slices" causes only a range of slices to appear during a display operation. Selecting "Crop new" causes the images to be cropped during a display operation.

i Dimension limits

In the "Limits/Cropping Dialog Window" the first and last i dimension are set via scroll bars. Modifying either value automatically selects the "Limit i dim" checkbox.

Slice limits

In the "Limits/Cropping Dialog Window" the first and last slice are set via scroll bars. Modifying either value automatically selects the "Limit slices" checkbox.

Cropping range

In the "Limits/Cropping” dialog window cropping ranges are set via the horizontal begin, horizontal end, vertical begin, and vertical end scroll bars and text areas (hitting enter may be required to get typed numbers to register). The "Crop new" checkbox is not automatically selected unless the “Crop” button is pressed.

1. Interactive selection

When the "Select via mouse" checkbox is selected the mouse may manipulate the crop box size by pressing it over a displayed image. The crop box may be sized and resized by dragging the mouse with the left button pressed. The crop box is moved by dragging the mouse with the middle button pressed. The box appears in blue over the selected region. The scroll bar values change concurrently with mouse drags and the inverse is true - when changing the scroll bar values directly the displayed box resizes. The blue crop box disappears when the "Select via mouse" checkbox is deselected, when the crop is applied or, when the "Limits/Cropping” dialog window is dismissed.

Note - the "Select Region" checkbox fails if the mouse input is currently diverted to another window for another reason such as the "Save Dialog" window for setting save region sizes.

2. Applying and removing

Hitting the "Crop" button in this dialog causes currently selected (or all) displayed images to be cropped by the current scroll settings. Hitting "Uncrop" causes currently selected (or all) displayed images to not be cropped.

3. Existing values

The "Reset crop to current" button sets the cropping ranges to those of the currently selected image.

Related script commands:

crop("apply");// applies crop to all or currently selected images
crop("current");// sets crop to that of currently selected image
crop("off"); // sets crop to none
crop("undo"); // removes cropping from all or currently selected images
crop(x_beg_integer, y_beg_integer, x_end_integer, y_end_integer); // sets crop box to given range
iRange(first_integer, last_integer); // sets first and last i dimension limits
iRange("off"); // turns off i dimension limits

slices(first_integer, last_integer); // sets first and last slice limits
slices("off"); // turns off slice limits

Display layout

iiV has a simple layout manager that controls the position for newly added components and redistributes components when re-layout is preformed. The goal of the layout manager is to organize objects in an orderly fashion with no overlapping. The manager places components in rows and columns starting from the top left, inserting components to the right until the max number of columns is reached, and then starts a new row from the left below all components in the previous row. The total number of rows becomes the number of objects divided by the number of columns rounded up. The height of a row depends on the tallest object in the row. Columns are not aligned between rows unless all objects are the same width. The layout manager decides where to place the next added object by keeping track of the next insert location, current number of objects in the row and maximum height of existing objects in the row.

Insert cursor

If “Show Insert Cursor” in the edit menu is selected then a blinking inverted L shaped cursor is shown in the display area at the next insert location. This location may be dragged with the middle mouse button. Repositioning the insert location doesn’t change the layout manager’s notion of the height or number of columns in the current row.

Number of columns

The number of columns per row is selected by a slider and text area labeled “Columns:” in the main display “Edit” menu and also the main control panel. As the slider moves the number changes but it has no instant effect on what's displayed. Future added objects are put in new row if there is already that number objects in the current row. This number also effect future re-layouts.

Re-layout of what's displayed

Hitting the "Relayout" button in either the main display “Edit” menu or the main control panel rearranges the currently displayed objects according to the current number of columns. The layout manager arranges the images with no overlap, with the back most image (normally the image added first) in the top left corner, and with only the number of columns per row. Rows are aligned with the top of all objects level and new rows are started below the lowest extent on any object in the previous row. Columns are not aligned. If the "front" or "back" menu options were applied to any images their relative position changes from when originally added.

Related script commands:

back(); // moves currently selected images to be behind other images;
columns(integer); // sets the number of columns for display layout columns integer;
front(); // move currently selected image to be in front of other images
position(x_integer, y_integer); // sets the display position for next object displayed
relayout(); // rearranges displayed objects according to current number of columns

Selecting displayed objects

Once objects are displayed they may be manipulated by various functions. To determine which objects are manipulated a list of currently selected objects is maintained. Selected objects are displayed with a blue border around them. If no items are selected, most functions apply to all objects. Items are normally selected with the mouse over the display area but may also be selected with the various select buttons or script commands.

Select All

Hitting the “Select All” button, either under the “Edit” menu or in the main control panel, selects all current displayed objects.

Select Top

Hitting the “Select Top” button under the “Edit” menu or in the main control panel selects all displayed objects with no overlapping objects in front of them.

Select Bottom

Hitting the “Select Bottom” button under the “Edit” menu or in the main control panel selects all displayed objects with no overlapping objects behind them.

Select Adds

When this check box is selected, via the “Edit” menu or in the main control panel, any new objects added to the display are automatically selected.

Select Region

Hitting the “Select Region…” button in the “Edit” menu, main control panel, or “Save” dialog brings up the select region dialog. The selected region dialog defines a region of the display for saving or copying. When the selected region is displayed over the main display area the “Copy” command and the “Save Selected Region or Selected Components” command work with this region. The select region dialog has the following functionality:

1. Pressing the "Select Region" check box diverts the mouse input over the display panel for selection of a save region. If a previous save region has been selected it appears as a blue box outline in the display panel. If there is no previous region a region may be selected by pressing any mouse button over the display panel at the corner of a desired box and dragging the mouse until the whole box region is selected. The region may be resized by pressing the mouse button again and dragging the nearest corner. The middle mouse button drags the whole box to a new location. When the “Select Region” check box is deselected the blue box disappears and is no longer active for copying or saving.

2. The "Clear Selection" button removes previously selected regions so a new one may be created starting from a beginning corner.

3. The horizontal and vertical, begin and end, scroll bars also size the selected region.

4. Hitting the “Dismiss” button hides this window which also deactivates and hides any current selected region.

Note - the "Select Region" check box fails if the mouse input is currently diverted to another window such as when selecting a crop box.

Related script commands:

select("additions"); // any further display additions will be automatically selected
select("all"); // select all displayed objects
select("bottom"); // selects all displayed objects with no overlapping objects behind them
select(displayed_object); // selects the given currently displayed object
select("first"); // select the first display object
select(first_integer, last_integer); // select the given range of display objects
select("last"); // select the last display object
select("top"); // selects all displayed objects with no overlapping objects over them
unselect("additions"); // turns off automatic selection of display additions
unselect("all"); // deselects all objects

Copy, Paste, Delete

iiV supports the basic editing functions of copy, paste and delete. When an object(s) is copied a script to recreate the object(s) is placed on the system clipboard if available or else on the local process clipboard. The created script is written to place the object(s) into a single group for easy pasting. From the system clipboard objects can be pasted into other iiV processes that support the script and they maintain the full functionality of the original object. If limited to a local clipboard the object may only be pasted to the creating iiV process. The system clipboard is often unavailable for security reasons when running as an applet within a web browser.

Along with the script two other flavors of the original object might also be placed on the clipboard. There is an image flavor that is often supported by local clipboards and only supported in system clipboards with Java 1.3 or greater. And there is the text flavor which is supported by all clipboards. The image flavor when available may be pasted into iiV or other programs like Microsoft word but the pasted image doesn’t maintain the original object(s) functionality. The text flavor only contains text from objects that implement the getText() function. This includes objects like text components and show point display lines. The text flavor can be pasted in almost any program that supports pasting. Note – the script flavor is actually viewed as text by other programs.

Copying

Hitting the “Copy” button copies the selected region, the selected components, or the whole display area if nothing is selected, to the clipboard as a script, an image if allowed, and text.

Hitting “Copy Special->Script Only Copy” copies only the script flavor to the clipboard.

Hitting “Copy Special->Image Only Copy” copies only the image flavor to the clipboard.

Hitting “Copy Special->Text Only Copy” copies only the text flavor to the clipboard.

Note - when a region is copied as a script, the script groups all objects within the region and crops the group to show only the region

Deleting

Hitting the “Delete” button, either under the “Edit” menu or in the main control panel, deletes components currently selected in the display. If none are selected none are deleted. This doesn't update the next layout position. The deleted objects are not copied to the clipboard.

Clearing

Hitting the “Clear” button, either under the “Edit” menu or in the main control panel, removes all components currently displayed whether selected or not. It also resets the next layout position to the top left. The deleted objects are not copied to the clipboard.

Pasting

Hitting the “Paste” button pastes the clipboard contents to the display area. Paste looks at the flavors in the clipboard and pastes the script flavor if available, else it pastes the image flavor if available, or else it pastes the text flavor if available. When pasting scripts the script is actually run to recreate the original objects. When pasting an image a single image component is created in the display area. When pasting text a single text display component is created in the display area. Objects are inserted at the next layout position.

Hitting “Paste Special->Script Only Paste” pastes only the script flavor from the clipboard if available.

Hitting “Paste Special->Image Only Paste” pastes only the image flavor from the clipboard if available.

Hitting “Paste Special->Text Only Paste” pastes only the text flavor from the clipboard if available.

Related script commands:

clearDisplay();// clears display area
copy(); // copies selected region, selected objects or all objects to the clipboard
copy("image"); // copies as an image only
copy("script"); // copies as a script only
copy("text"); // copies as text only
delete(); // deletes the currently selected display objects
paste(); // pastes from the clipboard to the display area
paste("image"); // pastes only an image from the clipboard
paste("script"); // pastes only a script from the clipboard
paste("text"); // pastes only text from the clipboard

Overlaying on top of existing displayed objects

Objects are considered overlaid if part of their minimum bounding boxes overlap in the display area. The last object drawn is seen in front of the other. This order may be changed with the "front" or "back" menu options. The ability to see an object behind another object is controlled by front objects transparent settings. Shapes and texts normally have transparent backgrounds. The scaling and color model control the transparency of data slices.

Objects may be overlaid by dragging one object on top of another but this doesn't allow easy alignment. The snap options in the grid dialog facilitate precise alignment but it still takes some playing to get all object parameters correct for overlaying. The overlay button circumvents some of these hassles. The following steps describe the procedures to perform an overlay with the overlay button:

Display the background images such as MRI slices with their desired orientation, color model, zoom, cropping, etc.
Turn off "Read Displays".
Browse and read the desired overlay file or select it from the file list if it was previously read.
Select the color model with the appropriate transparent colors for the overlay images and apply to defaults.
Select the scale model to map the overlay pixels to the right colors and apply to defaults.
Select the background images to be overlaid in the display window.
Press the overlay button.

Overlay

Hitting the “Overlay” button, either under the “File” menu or in the main control panel, overlays the current object (last read or displayed object) on top of all selected objects (or on top of all displayed objects if there are none selected). Each displayed object is tested individual to make sure it is overlay compatible with the current object. Currently, a slice of any of the supported 4D data types can be overlaid on top of a slice of any of the supported 4D data types if they have the same dimensions. The overlaid image is displayed in front of the original showing the same slice, orientation, cropping, zoom, rotation, and flips. The originals crosshair and slice tracking modes are also duplicated. Scaling and color model are not duplicated from the original so that they maybe set via defaults to allow for transparency.

Overlay and group

Hitting the “Overlay&Group” button, either under the “File” menu or in the main control panel, performs the same task as "Overlay" mentioned above followed by grouping each newly created object with the object they where created to overlay. This helps maintain the same relative location between the top and bottom overlay objects during drags.

Related script commands:

overlay(); // overlays current display object on top of all selected or all displayed objects
overlayAndGroup(); // overlays current display object on top of all selected or all displayed objects and groups each overlay with the object it was created to overlay

Grouping displayed objects

Grouped objects keep their same relative location when translated or moved and can only be selected as a group. Most functions applied to a group are applied to all objects within the group. A group may be zoomed with each object their relative positions being zoomed. A group may also be cropped and the crop option applies to the whole group not the individual objects. Currently rotation can not be applied to groups.

Grouping

Hitting the “Group” button, either under the “Edit” menu or in the main control panel, combines currently selected objects into one group.

Group overlapping

Hitting the “Group Overlapping” button, either under the “Edit” menu or in the main control panel, combines currently selected objects that overlap into groups.

Ungrouping

Hitting the “Ungroup” button, either under the “Edit” menu or in the main control panel, will ungroup any currently selected (or allif nothing selected) top level groups. Groups within groups are not ungrouped.

Related script commands:

group(); // groups all selected objects
groupOverlapping(); // groups overlapping objects
ungroup(); // ungroup all selected (or all) top level grouped objects

Intensity Projections

Intensity projections display the maximum or minimum voxel values for each voxel in the same position from all (or limited) slices in the current view mode. As noted below, the current slice limits mode determines which slices contribute to the projection and the current scale mode determines if maximum or minimum values are projected. Mouse selection over an intensity projected image selects the indices to the raw data where the value was projected from (i.e. if the maximum value at 2-D location (30,30) came from the 3^rd slice the indices would be (30,30,3) where a voxel next to it, one x location over, might be from the 10^th slice with indices (31,30,10)).

Intensity Project

Hitting the “Intensity Project” button, either under the “File” menu or in the main control panel, displays a single intensity projection of the last read or displayed file. Like the "Display" button, how it gets displayed depends on the current mode for limits, cropping, orientation, flipping, labels, zoom, color model, and scaling. Unlike the "Display" button, no matter what the slice limits are only one view is generated with slice limits determining the range and order of slices to search for maximum (or minimum) intensities. Also, if the current scale mode is negative (or the default scale has a negative scale factor) then a minimum intensity projection is generated, otherwise a maximum intensity projection is generated. The scale mode also influences the mapping of projected values to colors as with standard slices (see scaling). Once generated, applying a new scale will not change the projected values (min projections stay min projections and max projections stay max projections) but can change the color mapping.

Related script commands:

CNUVIEWER.intensityProject(); // creates an intensity projection of the current display object

Setting color models

Every image displayed by iiV has a color model. Image formats such as GIF and TIFF come with their own color models that may not be set or edited within iiV. Data types such as ECAT or ANALYZE have no predefined color models. DICOM usually defines a color model but it may be changed within iiV. To map pixels from these formats into displayable colors iiV linearly scales them to values from 0 to 255 and finds a color for that value via an indexed color model. The index color model contains 256 colors with each individual color defined by three numbers one for Red, one for Green and one for Blue (RGB values). For an individual color the value of red can range from 0 (no red) to 255 (maximum red) and similarly for green and blue. The default color model is a gray scale that maps all three color numbers to same value as the index (i.e. index value 0 maps to RGB: 0, 0, 0 (black) and index value 255 to RGB: 255,255,255 (white)). Index color models are a precise way to define colors but, the color actually displayed varies with platform, system display setting, current color resource allocation and final display device variances. The Java Abstract Window Toolkit (AWT) determines the best way to display a color which may be directly or by dithering other colors to get an approximation.

Along with colors the index color model also supports alpha (opacity) values. Alpha values allow see through when overlaying images. There is one alpha value for each of the 256 indices. An alpha value of 255 is completely opaque and 0 completely transparent. When a voxel value maps to an index with an alpha value of 0 the color from behind is seen. Alpha values between 1 and 254 attempt to show part of this objects color and part of the color from behind. Alpha values of 255 show this objects color only. The Java Abstract Window Toolkit determines the best way to implement alphas.

Invoking color dialog window

Hitting the “Color…” button, either under the “Tools” menu or in the main control panel or selecting the “Color Dialog” checkbox under the “View” menu brings up a color dialog window. This window is used for reading lookup tables from files, applying color tables to displayed objects, adding color bars to the display, setting the display background color and invoking the color editor.

Reading a color file

iiV works with iiV script color tables or ANALYZE style color tables. Script color tables are ASCII files that are interpreted by the iiV script parser. Script files support any combination of pixel opacity (Alpha) values. ANALYZE style color tables are also ASCII files but the format doesn't support any opacity values. The following are the steps for reading and applying a color model:

1. Entering name on text field line

Typing the name of a lookup table file and hitting enter reads that file and displays it in this window.

2. Browsing

Alternatively the user may locate the file with a browser which is then read and displayed in this window upon opening.

3. Selecting from previous list

All tables read get added to a list and may be selected from the a list with the mouse.

4. Setting to current

The reset to current button grabs the color table of the currently selected displayed image.

Clarifying/Unclarifying

Pressing the “Clarify” button creates and/or selects a version of the current color model with index 0 set to clear. If the current color model is already clarified the “Unclarify” button is visible in place of the “Clarify” button. Pressing “Unclarify” creates and/or selects a version of the current color model with index 0 not set to clear.

Editing the color model

Pressing the "Edit" button in the color dialog window or selecting the “Edit Color Dialog” checkbox under the main display panel “View” menu invokes a simple color editor. When invoked from the color dialog window the editor is set to edit the color model currently displayed in the window. A grid of boxes with one color per box represents the color model. The editor works with two colors simultaneously. One donated as "A" and reflected by a grid box outlined in black and red and by the index, RGB and Alpha values immediately to the right and below the "Set Color A Index" button. And, another donated as "B" reflected by a grid box outlined in black and blue and by the index, RGB and Alpha values immediately to the right and below the "Set Color B Index" button.

1. Selecting colors to change

Pressing the left mouse button over a desired color within the grid selects that color and index as "A" for editing. Pressing the middle or right mouse button over a desired color selects that color and index as "B" for editing. The "A" or "B" scroll bars are set to reflect the current selected color with the top scroll bar showing the index value (0 to 255) and the red, green and blue scroll bars showing the color intensities (also 0 to 255) for each corresponding color. The background color of each of the color scroll bars reflects its current value. The background color of the index scroll bars reflects the combined setting of the red, green and blue scroll bars.
Another way to adjust the current "A" or "B" index is by adjusting the corresponding index scroll bars. Changes to the index scroll bar are reflected by position changes of the grid box outlines but, unlike mouse selecting over the grid, no changes are made to the current scroll bar color values. This combination of methods to change the index values allows the transferring color from one index value to another by: selecting an index and color with the mouse;changing the index value with the scroll bar;and then applying the color to the new index with the appropriate "Set Color A Index" or "Set Color B Index" button.

2. Changing and setting a color

Adjust a color scroll bar by dragging or clicking it or typing a new value in the associated box and hitting enter.

The changes are reflected by the background colors of the associate red, green and blue labels with the index label reflecting the combined RGB value. Pressing the corresponding "Set Color A Index" or "Set Color B Index" button applies the color to the color grid at the index reflected by the adjacent index scroll bar.

3. Enabling alphas

When the "Enable Alphas" check box is selected the alpha component for "A" and "B" is a scroll bar and the "Alphas" check box is enabled to allow alpha interpolating, incrementing or decrementing. When not selected the alpha component for "A" and "B" is a "Transparent" check box. Without alphas only one index value in the color table may be transparent. Deselecting "Enable Alphas" automatically removes alphas from the current color model.

4. Transparent check boxes (related to Clarifying/Unclarify)

When alphas are not enabled the alpha scroll bars are replaced by "Transparent" check boxes. This may be used to set one and only one index color to be totally transparent alpha value of 0. Attempting to set a second index to transparent will result in a beep and no change to the color model. This option is related to the "Clarify" and "Unclarify" pull down menu options available over objects in the display panel. The "Clarify" option sets the 0 index color to transparent. The "Unclarify" set the 0 index alpha to totally opaque or if 0 isn't transparent and another index is it sets the other index to totally opaque.

5. Interpolating colors

The interpolate button sets the color components from the "A" index to the "B" index as a linear interpolation of the current scroll bar color components. Index "A" is set to the "A" scroll bars color components, index "B" is set to the "B" scroll bars color components and indices between are interpolated to color components between color "A" and color "B" based on their index distance from each. The interpolation applies immediately to the color grid. The check boxes labeled "Reds", "Greens", "Blues" and "Alphas" designate which of the four components are interpolated. Only the checked colors and/or Alphas are modified.

6. Increment and decrement colors

The increment button increases the intensity of the color components from the "A" index to the "B" index by 1. Values already at the maximum of 255 are not modified. The decrement button decreases the intensity of the color components from the "A" index to the "B" index by 1. Values already at the minimum of 0 are not modified. As with interpolating both increment and decrement modify only the color components with corresponding "Reds", "Greens", "Blues" or "Alphas" boxes checked.

7. Undo/Redo

The "Undo" button becomes available when the color table displayed in the grid is modified. Hitting the "Undo" button reverses changes made to the color table. An undo history is stored from the time the color editor was first invoked or the "Disable" box was deselected. When an undo is performed it is removed from the undo history and the inverse placed in a redo history which enables the "Redo" button.

The "Redo" button, when enabled, may be pressed repeat changes that where undone. The redo history is maintained for each undo until it becomes invalid because of changes made to the display area not via an undo or the history is lost because the "Disable" box is selected. When a redo is performed it is removed from the redo history and the inverse added to the undo history.

Selecting the "Disable" button wipes out both the undo and redo history and disables both buttons. Further undo history is not added until the "Enable" button is pressed with the undo history beginning at that time.

8. Saving the color model

Next to the "Save" button is a select menu that allows the choice of "Script" or "Analyze" files.

The "Save" button in the color window brings up a file browser to select a file to save to. The browser should allow the user to select or enter a file name with an option to accept or cancel. Another warning with chance to cancel appears if an existing file is selected. It is standard but not necessary to use the ".lkup" extension for ANALYZE lookup files and the ".cnu" extension for script lookup files.

9. Accepting

Pressing the "Accept" button makes the modified color model current in the main color dialog window. The modified color model is given a unique name beginning with the word "edited" followed by a number. The edit window also dismisses.

10. Dismissing

The "Dismiss" button hides the edit window. Dismissing the edit window doesn't erase the current state of the edited color model but, invoking the edit window sets the color model to that currently displayed in the "Color Dialog" window. The "Undo" button may be used to return to the previously editing state.

Applying color

The "Apply Color Map" button applies the color model to all currently selected images or all images if none are selected. It also applies it to the default color table displayed in the control panel so that any further displays use the table. The "Apply To Default Only" button sets only this default table.

Adding color bars to the display

Color bars may be put directly into the display by pressing either the "Add Horz Color Bar", "Add Vert Color Bar", or "Add Color Quilt" buttons. The added color bars may that be treated as most other images and zoomed, cropped or scaled. Scaling acts different then other images in that it doesn't change the colors displayed but the label values are changed to match the range of an image using the same scale as either the integer pixel range or the quantified range when quantification is selected. There is currently no way to change the labeling except by scaling or cropping. Scaling changes these values and cropping changes the range of values by keeping the 3 markers equal spaced on the cropped region.

Setting background color

Select the background color from the choice list of colors which appears when pressing the mouse over the current color. Pressing the "Apply Background Color" button sets it.

Related script commands:

backgroundColor(Color_object);// sets the current background color to the given color object
backgroundColor(color_string); // sets the back ground color to the named color if known
backgroundColor(red_integer, green_integer, blue_integer); // sets the background color to the RGB value
color("apply"); // applies the current color map to all or selected images
color(ColorModel_object); // sets the current color map to the given color map object
color("current"); // sets the current color map to that of the currently selected image
color("filename"); // reads the current color map from a file
colorMap("horizontal"); // displays a horizontal color map
colorMap("quilt"); // displays a color map quilt
colorMap("vertical"); // displays a vertical color map
transparentColor("apply"); // applies the current default transparent index to currently selected images
transparentColor(index_byte); // sets the default transparent color index
transparentColor("off"); // turns off the transparent index for the current color map

Scaling data values to a color model

For data types that don’t provide their own color tables iiV maps the data through an 8 bit, 256 value indexed color model to determine the color displayed for a given voxel. Unless the data type is 8 bit some form of scaling is needed to get the pixels within the limits of the color model. The scale factor is a versatile tool for applying a linear scaling with threshold to transform voxels into the set range of the lookup table. It includes a quantification value so values may be entered in terms of quantified voxel values (i.e. z-scores, decays, etc.). Also, with quantification the same color mapping may be obtained across images that have the same units only when quantified.

Invoking the scale dialog

Hitting the “Scale…” button, either under the “Tools” menu or in the main control panel or selecting the “Scale Dialog” checkbox under the “View” menu brings up a scale dialog window.

Scale factor

The scale factor may be typed in manually and set to any valid floating point number including exponents such as 2.3e-3 for 0.0023. This value is applied to the input pixels after the threshold and translation. It is normally set automatically to get a proper value for a given range. Its units are color table index divided by raw pixel values unless quantification is selected then it is in color table index divided by quantified units.

Translation

The translation may also be typed in manually and set to any valid floating point value including exponents such as 1.3e-3 for 0.0013. This value is applied to the input pixels after the threshold and before the scale factor. It is normally set automatically to get a proper translation for a given range. Its units are the raw pixel values unless quantification is selected then it is in the quantified units.

Minimum threshold & value

A minimum threshold is applied only if checked. The threshold may be entered manually or set automatically with "Set to Positive" or "Set to Negative" buttons. The minimum threshold is in units of raw pixel values unless quantification is selected then it is in the quantified units. The minimum threshold is applied to pixels before the maximum threshold, translation and scaling. If a pixel is less then the minimum threshold (not equal to)the minimum value is used with no further conversions. The minimum value is in color table units and may be set manually or automatically by one of the set buttons.

Maximum threshold & value

A maximum threshold is applied only if checked. The threshold may be entered manually or set automatically with "Set to Positive" or "Set to Negative" buttons. The maximum threshold is in units of raw pixel values unless quantification is selected then it is in the quantified units. The maximum threshold is applied to pixels after minimum threshold but before translation and scaling. If a pixel is greater then the maximum threshold (not equal to) the maximum value is used with no further conversions. The maximum value is in color table units and may be set manually or automatically by one of the set buttons.

Quantification

The quantification value may be automatically derived from an input image or set manually. Quantification allows efficient storage of data as binary words such as 16-bit integer. The quantification factor is normally calculated when a data file is created to scale the maximum storage value to the maximum of the raw data (i.e. a factor to scale the maximum storable value for signed 16-bit integer, 2^15 or 32768, to the data's maximum z-score of 5.0 would be 5.0/2^15 ~ 1.53e-4). The quantification value defaults to 1.0 if unavailable for an image file. When the scale is set to default for a selected image (i.e. after pressing "Reset to default" button) the original or default quantification value is shown. The user may manually modify this number to a known value but only when the box next to it is not selected. Normally the quantification factor is displayed but ignored. If the box next to quantification is selected then the units of the displayed values for threshold and translation are quantified and, more importantly, this changes how the scaling applies to other images. When applied to an image with a different quantification factor the assumption is that the quantified values have the same units such as z-scores and the scale is applied in terms of the quantified units. This makes z-scores of the same value appear the same color where normally they may appear different colors even when using the same scale. Scale and quantification may also be applied to color maps to change their labeled ranges.

Current data type

The current data type is used by reset to default, set to positive, and set to negative to determine default input value maximum and minimums. For example with type short the input values range from -32768 to +32767 so set to negative would calculate a scaling to map -32768 to color index 255 and 0 to color index 0.

Reset to current

Pressing the “Reset to Current” button retrieves all the scale values based on the currently selected component.

Reset to default

Pressing the “Reset to Default” button resets all scale values to the default for the current data type.

Set to positive or negative

Pressing the “Set to Positive” or “Set to Negative” button sets the scale values to a default value that displays only positive or negative values for the current data type.

Set to range

Pressing the “Set to Range” button calculates scale and translation based on the minimum and maximum values currently shown. The translation is calculated to translate the "minimum threshold" to the "minimum value". The scale factor is calculated to fit input values between "minimum threshold" and "maximum threshold" to the display range between "minimum value" and "maximum value". "Minimum value" and "maximum value" may be outside of the true displayable range of 0 to 255 but those values display as 0. Integer and floats types use a default range of -65535 to +65535 just for fun.

Applying

Pressing the “Apply” button applies the scale values to the currently selected display components or all displayed components if none selected.

Related script commands:

max(thresh_float, thresh_value_float); // sets the scale maximum threshold and value
max(thresh_float); // sets the scale maximum threshold
maxValue(thresh_value_float); // sets the scale maximum threshold value
min(thresh_float, thresh_value_float); // sets the scale minimum threshold and value
min(thresh_float); // sets the scale minimum threshold
minValue(thresh_value_float); // sets the scale minimum threshold value
quant(quantification_factor_float); // sets a quantification value and turns on quantification
scale("apply"); // applies the scale to all or current selected images
scale("current"); // sets scale to currently selected image
scale("CNUScale_object"); // sets scale to given scale object
scale("default"); // sets scale to default
scale("negative"); // sets scale to display negative values only
scale("positive"); // sets scale to display positive values only
scale("toRange"); // sets scale to display range as specified by min and max thresholds and values
scale(value_float); // sets the scale factor
scaleToRange(); // sets scale to display range as specified by min and max thresholds and values
translation(value_float); // sets the translation amount

Adding text

Text components may be added to the display area to annotate images.

Invoking text dialog window

Hitting the “Text…” button, either under the “Tools” menu or in the main control panel or selecting the “Text Dialog” checkbox under the “View” menu brings up a text dialog window. This window allows the addition of text as components to the display panel. The window also allows the changing of text font, style, size and color for existing text and labels on other components.

Setting and adding text

The text window contains an area for typing text. The "add text" button inserts this text as a component in the display window. The text is treated as any other component and inserted at the next layout position.

Setting font type, style and size

Select the font type, style and size from the separate choice lists which appear when pressing the mouse over the current selection. These values apply when adding new text or when "apply font" is pressed they are applied to selected components that contain text include images with labels.

Setting justification

Select the justification left, right or centered from the choice list. The selection applies when adding new text or when "apply justification" is pressed it is applied to all or currently selected objects. Only lines within the same text object are justified with respect to each other. Therefore, only text objects containing more then one line of text show justification effects.

Setting color

Select the text color from the choice list of colors. The color applies to new text or pressing "apply color" applies it to selected components that contain text.

Setting text to current

The "set to current" button sets the text dialog values to that of the first currently selected display item. Text and justification are set only from items that support get text

Setting text defaults

The "apply to default only" button sets the default font, justification and text color for the further displayed items.

Related script commands:

font("apply"); // applies the current font to all or selected objects
font("type_string style_string", points_integer)" // sets the current font to given the type, style and size
font("off"); // clears the current font to use default
justification("centered"); // further text will be center justified
justification("left"); // further text will be left justified
justification("right"); // further text will be right justified
text("text_string"); // adds a display object with the given text
textColor("apply"); // applies the current text color to all or selected objects
textColor(Color_object); // sets the current text color to given color object
textColor("color_string"); // sets the current text color to a named value
textColor("off"); // restores default color for future text
textColor(red_integer, green_integer, blue_integer); // sets the current text color to the given RGB value

Adding shapes

Simple shapes may also be added to the display area to help annotate images.

Invoking the shape dialog window

Hitting the “Shapes…” button, either under the “Tools” menu or in the main control panel or selecting the “Shape Dialog” checkbox under the “View” menu brings up the shape dialog window. This window allows the addition of simple shapes as components to the display panel.

Setting thickness and fill options

A pull down menu allows the selection of different thickness for the lines that make up a shape.

Selecting the fill check box causes shapes to be solid. On lines this only affects the arrow heads.

Setting dash options

A dashed or solid line for the composition of shapes is chosen from a pull down choice menu. In the dashed mode additional fields corresponding to the dash length and dash spacing become available.

Line options

With the "Line" check box selected fields unique to the line shape become available. This includes the length of the line and check boxes for selecting left or right arrow heads. Also, if a left or right arrow head is selected the arrow length and width fields become available.

Box and oval options

With "Box" or "Oval" check box selected width and height fields become available.

Setting and applying shape color

The color for a shape is selected from a pull down menu. This color can also be applied to existing display objects via the "apply color" button. This color applies to any object that utilizes a foreground color such as text.

Adding the shape

The "add shape" button adds a shape according to the selected shape type and appropriate fields.

Setting shape to options current

The "set to current" button sets all shape selections and fields according to the currently selected displayed shape.

Related script commands:

iiv.display.DisplayShape.setDefaultLineThickness(width_integer); // set default thickness of future shapes
iiv.display.DisplayShape.setDefaultLineType(iiv.display.DisplayShape.SOLID); // future shapes will be made of solid lines
iiv.display.DisplayShape.setDefaultLineType(iiv.display.DisplayShape.DASH); // future shapes will be made of dashed lines
iiv.display.DisplayShape.setDefaultDashLength(length_integer); // set default length for line dashes
iiv.display.DisplayShape.setDefaultDashSpace(space_integer); // set default space between line dashes
iiv.display.DisplayShape.setDefaultFillMode(true); // future shapes will be filled
iiv.display.DisplayShape.setDefaultFillMode(false); // future shapes will not be filled
displayClass("DisplayBox", width_integer, height_integer); // display a box of given width and height
displayClass("DisplayOval", width_integer, height_integer); // display an oval of given width and height
iiv.display.DisplayLine.setDefaultLeftArrow(iiv.display.DisplayLine.SIMPLE_ARROW); // future lines will have simple left arrows
iiv.display.DisplayLine.setDefaultLeftArrow(iiv.display.DisplayLine.NONE); // future lines will not have left arrows
iiv.display.DisplayLine.setDefaultRightArrow(iiv.display.DisplayLine.SIMPLE_ARROW); // future lines will have simple right arrows
iiv.display.DisplayLine.setDefaultRightArrow(iiv.display.DisplayLine.NONE); // future lines will not have right arrows
iiv.display.DisplayLine.setDefaultArrowLength(length_integer); // sets default length for line arrows
iiv.display.DisplayLine.setDefaultArrowWidth(width_integer); // sets default width for line arrows
displayClass("DisplayLine", length_integer); // display a line of given length

Grid

A grid along with the snap options provides a useful aid in aligning displayed objects. A paper outline is also available as an aid for arranging objects to print on a given size paper although display units won’t always translate correctly to print devices. Pressing the "Grid…" button in either the display panel “Tools” menu, the main control panel or selecting “Grid Dialog” from the “View” menu brings up the "Grid Dialog" window to control the background grid, the background paper outline and snapping objects to grid lines.

Units

Grid spacing and paper sizes are displayed in inches, centimeters or pixels. The units are selected via a choice menu. Selecting different units automatically converts the displayed values. Inches and centimeters are approximately the distances as seen on the display device and don't always translate correctly to print devices. Getting sizes right for print devices is best done by actually printing a grid to paper and then measuring it with a ruler to calculate a correction factor for the grid and paper dimensions. This value can be set in the "Resolution Correction" field and changes the true pixel sizes when they are input in inches or centimeters.

Displaying a grid

The "Grid On" check box, "Grid Spacing" text field, "Grid Offsets" text fields, and "Grid Color" choice menu specify whether, with what spacing, with what offsets, and with what color a grid appears in the display panel. Changes to these values don't take effect until the "Apply" button is pressed. Even if not displayed, the applied grid spacing effects the snap options.

Displaying a paper outline

The "Paper Outline On' check box, "Paper Size" text fields, "Paper Offsets" and "Paper Color" choice menu specify whether, with what dimensions, with what offsets, and with what color a paper outline appears in the display panel. Changes to these values don't take effect until the "Apply" button is pressed.

Applying

As noted above the grid and paper outline settings do not take effect until the "Apply" button is pressed. If there are any errors in the size text fields the field is reset to the current setting.

Setting to current

Pressing the "Set to Current" button, before hitting apply, resets the grid and paper values those currently applied to the display panel.

Snapping objects to the nearest grid line

The four snap buttons align currently selected or all displayed objects to a grid line. The "Snap Top" button aligns the top of an object to the nearest horizontal grid line. The "Snap Bottom" button aligns the bottom of an object to the nearest horizontal grid line. The "Snap Left" button aligns the left edge of an object to the nearest vertical grid line. And, the "Snap Right" button aligns the right edge of an object to the nearest vertical grid line. The grid lines need not be displayed for aligning.

Related script commands:

grid("on"); // turns on grid lines
grid("off"); // turns off grid lines
grid(spacing_float, "units_name"); // sets the spacing between grid lines
gridColor("colorName_string");// sets the grid to the named color
gridColor(Color_object); // sets the grid to the color object
gridColor(red_integer, green_integer, blue_integer); // sets the grid color to the given RGB value
gridOffsets(x_float, y_float, "units_name"); // sets the grid offset from the display origin
paper("on"); // turns the on paper outline
paper("off"); // turns off the paper outline
paper(width_float, height_float, "units_name"); // sets the paper outline size
paperColor(Color_object); // sets the paper outline color to the given color object
paperColor("colorName_string"); // sets the paper outline to the named color
paperColor(red_integer, green_integer, blue_integer);// sets the paper outline color to the given RGB value
paperOffsets(x_float, y_float units_name); // sets the paper offset from the display origin
screenResCorrection(factor_number); // sets screen resolution correction factor for grid and paper sizing
snap("top"); // snaps object tops to the nearest grid line
snap("bottom"); // snaps object bottoms to the nearest grid line
snap("left); // snaps left side of objects to the nearest grid line
snap("right"); // snaps right side of objects to the nearest grid line

Refresh

The "Refresh" button in the main control panel use to update the size of the display area after drags but this is no longer needed. This button now revalidates the parent frames which may act as a refresh when things get messed up.

Image Labels

Some display objects, such as data slices and color bars, support automatic labels showing current slice, orientation, or value ranges. These labels may be turned on or off and the numbers they display formatted.

Turning on and off image labels

Next to the "Labels Format:" button in either the display window “Tools” menu or the main control panel there are two check boxes for turning on and off image labels and a "Apply Default Labels" button for applying the selections. Selecting the "Orientation" box before displaying causes letters to appear on the lower and right edges of the images with the following designations: R=right; L=left; A=anterior (front); P=posterior (back); S=superior (top); and I=inferior (bottom). Selecting the "Slice" box before displaying causes numbers to appear at the bottom center of the images signifying which slice each image corresponds to. The slice numbers are integers between 0 and the total number of slices less 1. Or, if the image has a map file, the number corresponds to an mm location relative to the origin (see setting the coordinate map). Hitting the apply button next to the label selections adds or removes labels from the currently selected images or all images if there are none selected. After applying labels a re-layout may be needed to remove overlap between images.

Number formatting for labels

Pressing the "Labels Format…" button in either the display windows “Tools” menu or the main control panel brings up a number format dialog window. This window controls formatting numbers in automatic labels such as the Talairach slice coordinate. The following options are available:

integer digits max - sets the maximum number of digits left of the decimal point. Too small and most significant digits may be dropped.
integer digits min - sets the minimum number of digits left of the decimal point. Unneeded most significant digits display as zeros.
fraction digits max - sets the maximum number of digits to the right of the decimal point. Rounds to the nearest shown digit.
fraction digits min - sets the minimum number of digits to the right of the decimal point. Unneeded least significant digits display as zeros.
commas - sets whether commas are shown or not.
exponent multiples - controls whether exponents are shown and and what powers of 10 are allowed. An exponent multiple of 1 enforces the scientific standard with any exponent power that leaves 1 most significant digit left of decimal point. An exponent multiple of 3 enforces the engineering standard with the exponent power a multiple of 3 leaving 1 to 3 most significant digits left of the decimal point. The "Zero_int" chooses any exponent power that leaves "0" as the single digit left of the decimal point with the most significant digit just to the right of the decimal point.
exponent symbol - sets the characters shown between the number and exponent. Built in settings are "E", "e" or "x10^" but any ASCII string may be specified with the "numberFormat" script command.
apply - applies current settings to selected objects and defaults.
apply to default only - applies current settings to defaults for newly created objects.
set to current - sets the above options from the values of a selected object or the current defaults.
dismiss - hides the dialog window.

Related script commands:

labelsApply(); // applies orientation and slice label modes to all or current images
labelsOff(); // turns slice and orientation labels off
numberFormat(max_int_digits_integer, min_int_digits_integer, max_fraction_digits_integer, min_fraction_digits_integer, commas_boolean, exponent_multiples_integer, "exponent_symbol_string"); // creates a number format and sets as default
numberFormat(NumberFormat_object); // sets a numberFormat object as default
numberFormatApply(); // applies default number format to selected display objects
orientationLabelsOff(); // turns orientation labels off
orientationLabelsOn(); // turns orientation labels on
sliceLabelOff(); // turns slice labels off
sliceLabelOn(); // turns slice labels on

Flipping images horizontally and vertically

Next to the "Apply Default Flips" button in either the display window “Tools” menu or the main control panel there are two checkboxes. Selecting the "Horizontal" check box before displaying will cause images to be flipped horizontally. Orientation labels are corrected for the flip. Selecting the "Vertical" box before displaying will cause the images to be flipped vertically. Orientation labels are corrected for the flip. Hitting the “Apply Default Flips” button applies the flip choices to currently selected images or all images if none are selected.

Related script commands:

flip("apply"); // applies flips to all or currently selected images
flip("horizontal"); // sets horizontal flipping
flip("horizontalOff"); // unsets horizontal flipping
flip("off"); // unsets both horizontal and vertical flipping
flip("vertical"); // sets vertical flipping
flip("verticalOff"); // unsets vertical flipping

Image filtering

Image filtering allows for the zoom and rotation of most displayable objects. The amount of zoom and rotation can be set and applied from the “Image Filtering” dialog window which is invoked by pressing the “Image Filtering…” button either on the main displays “Tools” menu or in the main control window or by selecting “Image Filter Dialog” in the “View” menu. Newly displayed images are zoomed when the zoom value is other then 1 and the "Zoom" checkbox is selected and rotated when the rotation value is other then 0 and the "Rotate" checkbox is selected.

Pixel sampling

Zoom and rotation are spatial mappings that sample pixels from the original. Each filtered pixel is generated by inversely mapping its location to the original image space and sampling the surrounding original pixels based on the sampling mode. Both rotation and zoom are handled by one filter operator that allows only one filter sampling type per image. In the “Image Filtering” dialog the pixel sampling mode is selected from a pull down menu as either "Replicate", "Interpolate", “Alpha_Weighted_Interpolate”, “Index_Interpolate”, or “Alpha_Weighted_Index_Interpolate”. To apply a new sampling type to a displayed object, select the object, Press “Reset to current” to grab the current zooms and rotation, select the appropriate sampling mode and then re-apply the rotation or zoom. The sampling types are described below.

“Replicate” sets rotated and zoomed image pixel values to the nearest associated value from the original image.

“Interpolate” sets the value to a spatial interpolation of the four nearest original pixels creating a smoother looking image then “Replicate”. The four color components (Alpha, Red, Green and Blue) from each of the four nearest pixels are interpolated independently.

“Index_Interpolate” also linearly interpolates except, if the images color model is an “IndexColorModel”, the single index value from each of the four nearest pixels are interpolated instead of the four ARGB values. If the color model isn’t an “IndexColorModel” this mode falls back to the same independent ARGB interpolation as the “Interpolate” mode above. When index values linearly scale from data values such as z-scores this interpolation usually works best. When index values map to random colors, such as with most gif images, this sampling may produce odd effects and “Interpolate” may fair better.

“Alpha_Weighted_Interpolate” and “Alpha_Weighted_Index_Interpolate” are similar to their namesakes mentioned above except that values from each of the four nearest pixels are weighted by their alpha component. The more transparent a pixel is the less weight it gets. This reduces edge effects which occur typically when an image has been thresholded and pixels below the threshold set to transparent.

Rotation

The rotation angle in degrees is entered into the field right of the “Rotate” checkbox. It may also be selected from common values in the pull down menu just right of the field. Hitting the "Apply Rotation" button applies the field value with the selected sampling to any currently selected display objects and automatically selects the “Rotate” checkbox. When the “Rotate” checkbox is selected newly displayed objects are rotated by the current angle. The “Rotate” checkbox also appears in the “Tools” menu and main control panel.

Zoom

The zoom is divided into separate vertical and horizontal values. The vertical zoom value is entered in the field next to the "Vertical:" label. The horizontal zoom value is entered in the field next to the "Horizontal:" label. Zooms may also be selected from common values in the pull down menus just right of the corresponding field. The horizontal zoom may be locked to the same value as the vertical zoom by selecting "= vert" from its pull down menu – note this disables the horizontal zoom field. Hitting the "Apply Zoom" button applies the zoom values with the selected sampling to any currently selected display objects and automatically selects the “Zoom” checkbox. The “Zoom” checkbox also appears in the “Tools” menu and main control panel.

Mouse zoom

Selecting the “Mouse Zoom” checkbox grabs mouse input over the main display area to allow sizing (zooming) objects. With this selected move the mouse over an object in the display window. If the object can be zoomed the cursor becomes directional arrows while over the right edge, lower edge or lower right corner. Press the mouse and drag to resize that object. While dragging a blue outline is drawn to reflect the new size and when the mouse is released the zoom applied to defaults and the object is resized. Dragging is only allowed from the lower and right areas so the tool doesn’t have to translate the object to reflect the drag box. Dragging from the corner (diagonal arrow visible) maintains horizontal to vertical zoom ratio where as dragging from the right side scales horizontally only and dragging from the bottom scales vertically only.

Reset to current

The "Reset to Current" button sets all the values in this dialog to the currently selected displayed objects or if none selected to the defaults displayed in the control panel.

Apply to defaults

The "Apply to Defaults Only" button makes all the settings in this dialog defaults for future displayed objects.

Related script commands:

filterSampling("interpolate"); // sets filter sampling mode to interpolate
filterSampling("replicate"); // sets filter sampling mode to replicate
rotate("apply"); // applies rotation setting to all or current images
rotate(degrees_float); // sets rotation to the given angle in degrees
rotate("off"); // turns off automatic rotation of newly displayed images
rotate("on"); // turns on automatic rotation of newly displayed images
zoom("apply"); // applies zoom settings to all or current images
zoom("interpolate"); // sets zoom mode to interpolate
zoom("off"); // turns off automatic zooming of newly displayed images
zoom("on"); // turns on automatic zooming of newly displayed images
zoom("replicate"); // sets zoom mode to replicate
zoom("smooth"); // sets zoom mode to smooth
zoom(value_float); // sets zoom to a given floating point value
zoom(vertical_float, horizontal_float); // sets separate vertical and horizontal zooms to a given floating point values

Undo/Redo

Undo/redo for the main display area is controlled via “Undo”, “Redo”, “Enable undo”, and “Disable undo” buttons duplicated in three locations. Under the main display “Edit” menu, near the bottom of the main control panel and under the “Edit” menu of the “Show Point” dialog.

The "Undo" button becomes available when something is added, removed or changed in the display area unless the "Disable undo" button has been pressed. When available the text on the button reflects the type of action that it would undo. Hitting the "Undo" button steps backwards through changes made to the display area. An undo history is stored from the time the viewer was invoked or the "Enable undo" button was selected. Performing an undo also removes it from the undo history and places the inverse in the redo history.

The "Redo" button becomes available after performing an undo. When available the text on the button reflects the type of action that it would redo. Pressing the "Redo" button repeats changes that where undone. The redo history is maintained for each undo until it becomes invalid because of changes made to the display area not via an undo or the history is lost because the "Disable undo" button is selected. Performing a redo also removes it from the redo history and adds the inverse to the undo history.

Selecting the "Disable undo" button wipes out both the undo and redo history and disabling both. Further undo history is not added until the "Enable" button is selected with the undo history beginning at that time.

Related script commands:

clearUndos(); // clears undo/redo history
disableUndos(); // clears undo/redo history and disables further history
enableUndos(); // enables undo/redo history for future commands
redo(); // redo an undone command
undo(); // undo last command

Show point dialog

Hitting the “Show Point…” button, either under the “Tools” menu or in the main control panel or selecting the “Show Point Dialog” checkbox under the “View” menu brings up a show point dialog. This window contains a menu bar for controlling show point features and a table for displaying voxel values and locations. The first row of the table, under the title row, displays the object name, pixel location and pixel value when the mouse is pressed over an object or the background location when the mouse is pressed off an object or dragging an object. Object names are usually the image file name. Locations are displayed as a 0 relative integer location. Pixel values are displayed as a raw, usually integer, values followed by the quantification factor and the quantified product value. Images with applied coordinate maps also display the map file name and the mapped pixel location. The mapped pixel location displays in millimeters relative to the origin defined by the map file.

Along with the location and value from the object the mouse was pressed over the table can contain secondary lines displaying corresponding values from one or more other objects. To correspond either the indices are the same or the coordinate mapped locations are the same. If the indices fall outside an objects range no corresponding value is shown.

Secondary lines displaying corresponding values from other objects can also be added as objects to the main display window.

Show point dialog secondary lines are stored with the main display panel. The show point dialog shares its undo/redo history with the main display panel.

Setting the coordinate map

Pressing the "Coordinate Map..." button under the “Image Features” menu in the show point dialog or selecting the checkbox under the “View” menu in the main display menu bar invokes “Coordinate Mapping” dialog. This dialog is for reading, defining, and applying coordinate maps. When a coordinate map is defined the coordinate map window displays the map values as origin (in pixels or millimeters), scale, and rotation (in degrees or radians). When a coordinate map is applied to a displayed data slice the slice labels are in displayed as millimeters instead of slice numbers and the corresponding show point lines display mouse locations in mapped millimeters as well as the raw pixel locations.

Along with the map file name and values the coordinate map window contains the following buttons:

The "Browse" button invokes a file selection window for finding the a map file or the a file may be selected from the previously read list.
The "Set to Current" button brings up the coordinate map of the currently selected display object.
The "Set to null" button clears the selection to allow removal of coordinate maps from display objects.
The "Apply Coordinate Map" button applies the coordinate map to currently selected display objects or all displayed objects if none are selected.
The "Save" button brings up a browser for selecting and saving the coordinates to a file. The "Enable Edits" button allows the user to change coordinate values.
The "Accept" button takes currently shown values and creates a new CoordinateMap object listing it in the previously read list and making it ready to be applied and/or saved.

Adding show point lines

The "Add Show Point Line(s)" button in the “Show Point Lines” menu adds a secondary line for each appropriate object currently selected in the main display window. If a group is selected a line for each object in the group is added. Lines remain and continue to display the objects values even if the object is removed from the display panel.

Secondary lines shown in this dialog are saved to the script when the main display panel is saved as a script.

Deleting show point lines

The "Delete Show Point Line(s)" in the “Edit” menu removes currently selected lines from this window.

Clearing show point lines

The "Clear Show Point Line(s)" in the “Edit” menu removes all secondary show point lines from this window.

Adding show point lines to the main display

The "Add Show Point Line(s) to Display" button in the “Show Point Lines” menu adds a secondary line for each appropriate object currently selected in the main display window as an object in the main display area. If a group is selected a line for each object in the group is added. Lines remain and continue to display the objects values even if the object is removed from the display panel. Selection and deletion of these lines is handled by the main display window.

Recording show point values

The "Start Record" button in the “Show Point Lines” menu starts recording values in the status window for display lines currently selected in the show point dialog. Until stopped the activated show point line continues to record new values generated by the mouse.

The "Start Record in Display" button in the “Show Point Lines” menu starts recording values in the status window for display lines currently selected in the main display panel. Until stopped the activated show point line continues to record new values generated by the mouse.

The "Stop Record" button in the “Show Point Lines” menu stops recording values in the status window for display lines currently selected in the show point dialog.

The "Stop Record in Display" button in the “Show Point Lines” menu stops recording values in the status window for display lines currently selected in the main display panel.

The recording feature is treated as any other object feature in that undo/redo history is maintained and the state is saved in script files.

Freezing show point lines

The "Freeze Line(s)" button in the “Show Point Lines” menu stops the updating of values displayed in the show point lines currently selected in the show point dialog.

The "Freeze Line(s) in Display" button in the “Show Point Lines” menu stops the updating of values displayed in the show point lines currently selected in the main display panel.

The "Unfreeze Line(s)" button in the “Show Point Lines” menu starts the updating of values displayed in the show point lines currently frozen and selected in the show point dialog.

The "Unfreeze Line(s) in Display" button in the “Show Point Lines” menu starts the updating of values displayed in the show point lines currently frozen and selected in the main display panel.

The freeze state is treated as any other object feature in that undo/redo history is maintained and the state is saved in script files.

Mapped point tracking

The "Map Tracking" checkbox under the “Image Features” menu changes the rules for corresponding indices from a mouse press over one object to indices in another object with a show point line. When unchecked the indices are used directly. When checked, and both the mouse press object and the show point line object have coordinate maps, the indices are first mapped by the mouse press object's coordinate map, then inverse mapped by the show point line's coordinate map and finally rounded to the nearest show point line's indices. Rounding differences may appear in the mapped locations.

Showing crosshair

The “Crosshair color:” choice menu under “Image Features” selects the color for both tracking and permanent crosshairs. The color of exiting crosshairs doesn’t change until it is updated by tracking.

If the “Show Tracking Crosshair” checkbox under the “Image Features” menu is selected a tracking crosshair is displayed when the mouse is pressed and dragged over an object that supports crosshairs. This temporary crosshair is drawn with exclusive or’ing of the selected color and disappears when the mouse is released.

Pressing the “Add/Unfreeze Crosshair(s)” buttons under the “Image Features” menu adds and/or unfreezes crosshairs to each object selected in the main display panel that supports crosshairs. These crosshairs will track mouse presses over any other object unless frozen and remain when the mouse is released.

Pressing the “Freeze Crosshair(s)” buttons under the “Image Features” menu freezes the crosshairs for each object selected in the main menu that is currently tracking mouse presses. Unfreeze crosshair(s) by re-adding crosshair(s).

The "Delete Crosshair(s)" button in the “Image Features” menu removes tracking and frozen crosshairs from selected objects in the main display.

Slice tracking current point in images

Slice tracking is a tool for keeping views of different data or different views of the same data in synchronized to the same voxel location.

Pressing the “Start Slicetracking” button under the “Image Features” menu adds slice tracking for each object selected in the main display panel that supports slice tracking. Slice tracking causes the displayed slice of an object to be updated to reflect the same point the mouse is released when pressed over another object.

Pressing the “Stop Slicetracking” button under the “Image Features” menu deletes slice tracking for each object selected in the main display panel that is currently slice tracking.

The tracking features is treated as any other object feature in that undo/redo history is maintained and the state is saved in script files.

Number format

Show point lines display numbers formatted according to their current number format. One format is applied to all numbers within a display line object. Within the main display area the number format can be changed from the Labels/Format dialog. Within the Show Point Dialog the number format can be changed by pressing “Set Number Format”. This applies the current default, which may be changed from the Labels/Format dialog”, to the selected or all display lines. Applying to all display lines also applies to the top, always present, show point line - which can’t be selected and so can only be changed with none selected.

Related script commands:

addCrosshairs(); // adds crosshairs to selected display objects
addShowPointLines(); // adds show point lines for selected display objects
addUnrelatedShowPointLine(); // adds a show point line not related to any object to the main display
clearCrosshairs(); // same as deleteCrosshairs
deleteCrosshairs(); // removes crosshairs from selected display objects
displayAddShowPointLines(); // adds show point lines for selected display objects to the main display area
displayShowPointLinesFreeze(freeze_boolean); // sets selected show point lines in the main display area to freeze or not
displayShowPointLinesRecord(record_boolean); // sets selected show point lines in the main display area to record or not
freezeCrosshairs(); // freezes crosshairs in selected display objects
hideShowPoint(); // hides the show point window
selectShowPointLines("additions"); // newly added show point lines will be selected
selectShowPointLines("all"); // selects all secondary show point lines
selectShowPointLines(displayed_ShowPointDisplayLine_object); // selects a show point line object
selectShowPointLines("first"); // selects the first secondary show point line
selectShowPointLines("last"); // selects the last secondary show point line
selectShowPointLines(first_integer last_integer); // selects a range of show point lines
showPointCrosshair(visible_boolean); // sets whether temporary crosshair shows over the primary object
showPointLinesCrosshair(visible_boolean); // sets selected show point lines to show crosshairs or not
showPointLinesFreeze(freeze_boolean); // sets selected show point lines to freeze or not
showPointLinesRecord(record_boolean); // sets selected show point lines to record or not
showPointLinesTrack(track_boolean); // sets select show point lines to track point or not
showPointMapTracking(map_tracking_boolean); // sets whether tracking is via mapped coordinates or raw indices
showPointRecord(record_boolean); // sets whether primary show point line records or not
showShowPoint(); // shows the show point window
spatialMap("apply"); // applies the spatial map to all or currently selected images
spatialMap("current"); // sets the spatial map to a currently selected images
spatialMap(CoordinateMap_object); // set the spatial map to give coordinate map object
spatialMap("filename"); // reads the spatial map from the given file
spatialMap("off"); // turns off spatial mapping for further displayed images
startSliceTracking(); // starts slice tracking in selected display objects
stopSliceTracking(); // stops slice tracking in selected display objects
unselectShowPointLines("additions"); // newly added show point lines will not be selected
unselectShowPointLines("all"); // unselects all show point lines

Goto point dialog

The Goto Point Dialog is a tool to update slices and crosshairs to a given slice and voxel location. It is often more convenient then trying to reset slices crosshairs with mouse and key motions.

Invoking the Goto Point Dialog

Hitting the “Goto Point…” button, either under the “Tools” menu or in the main control panel or selecting the “Goto Point Dialog” checkbox under the “View” menu brings up the goto point dialog.

x, y, z locations

x, y, & z indices may be selected by typing them into the corresponding text areas or sliding the corresponding sliders.

Mapped points

If a map files has been set the area below the x, y, & z sliders shows the name of the map file as well as the mapped x, y, & z values corresponding to the x, y, & z indices.

Tracking the mouse

When “Track mouse” is selected and the mouse is depressed over a valid object in the main display area the indices and mapped points will update to reflect the mouse location.

Auto updating trackers

When “Auto update trackers” is selected and the indices are updated then all objects, that are currently set as slices trackers by the show point dialog, update to display the new location.

Auto updating selected objects

When “Auto update selected” is selected and the indices are updated then all selected objects, of the appropriate type, update to display the new location.

Map tracking

The "Map Tracking" checkbox is tied directly to the “Show Point Dialog” map tracking and has the same affect of causing tracking to use mapped points instead of actually indices.

Set to current

Pressing the “Set to Current" button updates the indices, mapped point, and map file to reflect the current selected object.

Set coordinate map

Pressing the “Set to Coordinate Map" button sets the map file to the current default map file which can be set by the “Coordinate Map” dialog.

Number format

Pressing the “Set Number Format" button sets the number format for displaying mapped points in this window. This sets it to the current default which can be set in the “Labels format” dialog.

Apply to trackers

When “Apply to Trackers” is pressed the current indices are applied to all current slices trackers set up by the show point dialog.

Apply to selected

When “Apply to Selected” is pressed the current indices are applied to all currently selected objects.

Status Window

When iiV catches an error, processes a script file, or receives a request for image info the text is displayed in the "Status Window". By default the status window pops up when ever it has new text to display. This option may be turned on or off via its “File” menu “Auto Show” checkbox or the script command "autoShowStatus". The status window may also be brought up by pressing the "Status Window…" button in either the “Tools” menu or in the main control panel or by selecting “Status Window” in the “View” menu. The status window works as a basic text editor. It includes a “File” menu with buttons for saving and dismissing and an “Edit” menu with buttons for copying, pasting, cutting and clearing text, undoing and redoing edits, and enabling and disabling input. Hitting the "Save" button brings up a file browser for selecting a file and saving the text (this may write over existing files with no warning). The "Enable Input" button starts a script interpreter and allows the user to type anywhere in the text area and when a carriage return is hit the text prior to the return is interpreted as a script command. When edits are enabled the "Enable Input" button is disabled and its inverse the "Disable Input" button enabled. The "Dismiss" button makes the window invisible until it has new text to display or the user presses the "Status Window" button. After processing a script the window is automatically hidden unless an error occurred or it was visible prior to the start of processing.

Note - most system errors, such as out of memory exception, are not caught by the viewer itself andappear in the shell that launched the Java interpreter or in the Java console of the web browser that launched iiV.

Related script commands:

autoShowStatus(boolean); // set whether the status window automatically appears when written to
clearStatus(); // clears all text from the status window
disableStatusEdit(); // turns off show status edit option
enableStatusEdit(); // enables edits in status window
hideStatus(); // hides the status window
saveStatus("filename"); // saves the status window's text to the given file name
showStatus(); // shows the status window

Memory monitoring

Pressing the "Memory…" button in either the “Tools” menu or the main control panel or selecting the “Show Memory Dialog” checkbox in the “View” menu invokes the "Show Memory" dialog. This window displays the total amount of memory currently allocated by Java and the amount of this memory that is free or not in use. The total amount of allocated memory may increase depending on limits imposed by Java and the system. Since the amount of free memory is only based on the current total amount allocated it may not reflect a true limit on how much memory is available. The "Garbage Collect" button forces Java to perform garbage collection. Java automatically performs garbage collection when it requires more memory. This button is available to give the viewer a more accurate reading of free memory.

When memory allocation problems occur they are not always obvious but often indicated by something not being displayed. Memory allocation is a Java Virtual Machine (JVM) error and not caught by iiV. An error message may appear in the window that launched the JVM or the Java console in a web browser. It would be nice to receive the memory allocation errors in the status window but there is the following basic problem: If you’re out of memory can you allocate memory to display that message?

Steps to perform when encountering memory problems

If iiV is having memory problems bring up this memory window to begin monitoring the memory and try garbage collecting. Try disabling undo/redo to free up memory from image files no longer displayed. Remember to enable undo/redo if you wish to be able to undo future changes. If there still isn't enough memory you may need to restart iiV with greater memory available. Before restarting, even though short on memory you may be able to save what is displayed as a script allowing you to recover your current work. See Java options for increasing memory allocation.

Related script commands:

garbageCollect(); // requests garbage collection by the Java virtual machine
hideShowMemory(); // hides the show memory window
showShowMemory(); // shows the show memory window

Hiding and detaching the control panel

The main control panel is now invoked and dismissed like any other dialog window..

Related script commands:

hideTools(); // hides the control panel
showTools(); // shows the control panel

Saving

Pressing the "Save…" button in either the “File” menu or the main control panel or selected the “Save Dialog” checkbox in the “View” menu invokes a dialog for saving what's displayed in any of the file formats described under file type below.

Selecting the output file name

The various save buttons described below save to the file named by the text field. The name should be complete with the desired extension. If the name does not include a complete path (i.e. doesn't start from the root directory) it is treated as relative to the directory where iiV was invoked. All save functions warn before writing over an existing file.

Browsing for an output file name

Hitting the "Browse" button invokes a file browser initialized with the current text field path. If the current path is null the browser lists the directory where iiV was invoked from. File browsers varies form platform to platform. Some file browsers have a button labeled "save" while others have a button labeled "accept". In either case, no saving is actually done at this point. The browser only selects the file name and enters it in the text field.

File type

The pull down menu allows the selection of either GIF, Script, or PPM output file types. The filename extension selected above should correspond to the file type for easy recognition (i.e. name.gif, name.cnu or name.ppm).

Note - on some machines there is a color table problem when saving GIF or PPM files. The images seem to save correctly but when displayed have incorrect gray colors. The problem usually occurs on displays supporting more then 256 colors. A solution is to drop the display mode down to 256 colors but, first save what's displayed as a script in case the program exits. Always reload and view the images to verify correct color saving.

Save display

Pressing the “Save Display” button saves the current display in the file specified above with the file type format selected. An affirmation dialog appears before writing over existing files.

Select region

The “Select Region…” button displays the “Select Region” dialog for selecting a region.

Save selected region or selected components

The "Save Selected Region or Selected Components" button works like the "Save Display" button except only the selected region or selected objects are saved. The selected region is saved if the selection box is currently displayed else the selected objects are saved if any are currently selected else nothing is saved and an error message is given.

Note - when a region is saved as a script, the script groups all objects within the region and crops the group to show only the region.

Saving viewer settings

The "Save Viewer Settings" button saves a special script that describes only the current tool panel settings. This allows retrieving the basic environment when the defaults are not well suited (see Automatic script processing).

Related script commands:

Printing what's displayed

Pressing the "Print…" button in the “File” menu or the main control panel pops up a machine depended dialog for printing what is currently shown in the display panel. The only print options available are those supported by the print driver.

Related script commands:

No script commands because current print interface requires GUI interaction.

Help

Pressing the "Help" button in the “File” menu or the main control panel invokes a browser to display this help file. When running as an applet, iiV pops up another window with the current browser. When running directly on a windows system, iiV invokes the default system browser. When running directly on a Unix system, iiV invokes the executable program "netscape" unless overridden with the "browser" or "BROWSER" property. The default help file displayed is the local file "iiV1181Help.html" if it exists otherwise "http://james.psych.umn.edu/iiV/doc/iiV1181Help.html". The following properties affect which browser is invoked and what html file is displayed:

browser=unixExecutableToDisplayHelp
BROWSER=unixExecutableToDisplayHelp
CNU.help.file=localHtmlFileToUseForHelp
CNU.help.url=universalResourceLocatorHtmlToUseForHelp

Quitting

When running as an applet (i.e. inside a web browser) iiV may be stopped by going to a different page or quitting the applet viewer. The applet viewer is in charge of this. When running directly in Java, iiV may be exited by pressing the "Quit" button in “File” menu or the main control panel or closing with one of the platform dependent methods.

Related script commands:

exit(); // exits iiV
quit(); // exits iiV

Input over display panel

Input over the display area may be used to select images, display pixel values, drag selected images, increment selected image slices, display a hidden or detached control panel, and display a pull down menu.

Any mouse button (object selection)

Pressing any mouse button over a display object selects that object and for some images displays the pixel value under the mouse in the show point dialog. Off a display object it deselects all objects. Holding the shift button while pressing the mouse button keeps previous selections while adding an object or removing an object if previously selected. Dragging a pressed mouse off an object creates a selection box and selects all objects within, keeping previous selections if shift is down.

Left mouse button (object selection)

The left mouse button is an object selection only button and has the effects mentioned above.

Middle mouse button (drag selections or scrollpane)

The middle mouse button (also, Alt-any or Control-any mouse button for one or two button systems) selects and drags selections. Or, if not over an image, the middle mouse button drags the display area within the scroll window.

Right mouse button (pull down menu)

Off an image the right mouse button shows a hidden menu bar and invokes the popup menu of functions. Over an image the right mouse button selects that image and invokes the popup menu of functions. The functions apply to the currently selected images. The following functions are available via this menu:

View - brings up a selection menu for showing and hiding known dialogs
Zoom - zooms the selected objects to the value selected (see Zoom)
- 1x
- 2x
- 3x
- 4x
- .25x
- .5x
Flip - flips the selected objects as selected (see Flipping images)
- No Flip
- Flip Vertically
- Flip Horizontally
- Flip Vertically & Horizontally
Labels - displays the selected labels on the selected objects (see Turning on and off image labels)
- No Labels
- Slice Labels
- Orientation Labels
- Slice & Orientation Labels
clarify - modifies the color table for selected objects to clarify indexed color 0 (see Clarifying)
unclarify - removes any clarified colors from the color tables of selected objects (see Unclarifying)
uncrop - removes any cropping applied to currently selected images
info - writes information about this object to the status window
front - causes the selected objects to be drawn in front of all other objects (see Re-layout)
back - causes the selected objects to be drawn behind all other objects (see Re-layout)
Select All - selects all currently displayed objects
Copy - copies current selected objects to the clipboard
Delete - deletes the currently selected objects
Group - groups currently selected objects
Ungroup – ungroups currently selected groups

Plus/minus (incrementing slices)

Pressing a plus symbol, over the display area, increments all or selected data slices to another slice. Pressing the minus symbol decrements al or selected data slices. Slices normally increment or decrement by one but, this may be changed by typing an integer number before typing a plus or minus. The new increment/decrement amount remains in effect until a new integer number is typed. If the increment/decrement amount is beyond the range of slices the slice is wrapped to a valid slice. The increment amount is shared with the arrow key increments noted below.

Arrow keys (translate pane, selections or crosshair)

Pressing an arrow key over the display area scrolls the pane the direction of the arrow. Holding the control key and pressing an arrow key translates currently selected objects. Holding the alt key and pressing an arrow key translates the crosshair if present in a current selected object. Arrow keys normally translate things by 1 pixel but this may be changed by typing an integer number before hitting the arrow key. The new increment amount remains until a new integer number is typed. The increment amount is shared with plus/minus slice incrementing noted above.

Notes:

On some combinations of SUN workstations and Java environments the diamond key works instead of the alt key.
On some keyboards arrow keys fight with numeric values. If the keyboard has independent arrow keys use those instead or make sure keyboards numeric lock is off.

Related script commands:

incrementSlices(amount_integer); // increments by the given number of slices the slice displayed in all or selected images
move(x_integer, y_integer); // move selected objects by given number of pixels
select("additions"); // any further display additions will be automatically selected
select("all"); // select all displayed objects
select("bottom"); // selects all displayed objects with no overlapping objects behind them
select(displayed_object); // selects the given currently displayed object
select("first"); // select the first display object
select(first_integer, last_integer); // select the given range of display objects
select("last"); // select the last display object
select("top"); // selects all displayed objects with no overlapping objects over them
showTools(); // shows the control panel
unselect("additions"); // turns off automatic selection of display additions
unselect("all"); // deselects all objects

Script language

iiV now supports BeanShell for scripting. The script language allows text commands to be stored in a file or typed to standard input. The text commands perform all the tasks available via the general user interface (GUI) plus has access to all the utility of the java language and iiV's API. Examples of scripts may be generated by displaying something and saving the display as a script (see Saving). More can be learned about BeanShell scripting at http://www.beanshell.org/docs.html. Old style iiV scripts are still supported.

Script file naming conventions

Files containing iiV scripts should end with the ".cnu" extension though this is not enforced anywhere. Specifying a file named "-" causes iiV to read script commands from standard input if available.

Automatic script processing

Naming a script file ".cnu" causes the script to run automatically the next time iiV is invoked from the directory. If no local ".cnu" file exists and a ".cnu" file exists in the users home directory it runs automatically. This file normally contains viewer settings (see Saving viewer settings) and allows a user to have the viewer come up in a preferred mode.

Note - Users home is not well defined under Microsoft Windows and may default to the root directory or the home directory of iiV.

Script header

To allow iiV to verify the file type, script files must contain the following comment lines:

// iiVBshScript
// Version 1.181

These lines must be in order next to each other, but can start anywhere within the first 10 lines, and can only be proceeded by comment lines starting with "//" or "#!". The version number should be less then or equal the version of iiV because some commands implemented in later versions may fail.

Allowing the header to occur after the first lines gives room for creating UNIX executable scripts. For example, to create a UNIX script that would invoke iiV and run the iiV BeanShell script from the same file, the script could start like one of the following:

#!/usr/bin/java iiv.iiV

// iiVBshScript
// Version 1.181

#!/bin/sh

//bin/true; exec java -jar iiV1181.jar "$0" "$@"

// iiVBshScript
// Version 1.181

Script comments

The standard C++ comment types work — everything following "//" to an end of line is treated as a comment and everything between a "/*" and "*/" is treated as a comment. BeanShell treats #! if the first line of a file to allow building UNIX executable scripts.

Script quotes

Quotes are handled like java and similar to C++. A single character may be quoted with a backslash "\". Since this is the standard path separator in windows double backslashes "\\" may be required or alternatively Java recognizes the standard slash "/" as path separator even under windows.

Script command format

Script commands are now called with java programming syntax just like functions. Most of the old commands are available as functions with arguments as a comma separated list between parenthesis. The syntax is described more in the BeanShell manual at http://www.beanshell.org/manual/syntax.html#Basic_Syntax.

Note - commands typed to standard input should execute upon hitting a carriage return but may not execute unless followed by a second carriage return or a semicolon before the first carriage return.

Script variables

Script variables provide a way storing strings or objects for repeated usage and use by other commands. BeanShell handles variable declaration and assignment like java except it allows for loose assignments without declaration and has slightly different scoping rules. iiV assigns two variables automatically -- the variable "CNUVIEWER" contains the reference to the main control panel object and the variable "CNUDISPLAY" contains the reference to the display panel object. Care must be taken not to use the BeanShell clear() command or these variables will be unset. See the BeanShell (http://www.beanshell.org/manual/syntax.html#Basic_Syntax) manual for more info on variable assignments.

Script commands for creating objects and invoking methods

iiV's previous script language had special commands for creating objects and invoking methods. With BeanShell objects are created and methods invoked just like in Java. There is still a newFileObject function that first searches displayed objects and undo/redo history for objects related to a filename and returns that object if it exists to save memory.

newFileObject("filename_string", "className_string", [param1], [param2], [...]); // Constructs new object of given class with given parameters or returns existing object based on same file

Script commands for displaying objects

The following script commands cause objects to be displayed in the display window.

CNUVIEWER.intensityProject(); // creates an intensity projection of the current display object
display(); // displays the last read or displayed file
display(component_object x_location_integer, y_location_integer); // displays the given component at the given display location
display(class_name, [param1], [param2], [...]); // create and display a given class
display(displayable_object); // displays the given displayable object
displayAddShowPointLines(); // adds show point lines for selected display objects to the main display area
displayClass("class_name", [param1], [param2], [...]); // creates and display a given class
displayImageData(displayable_object); // displays the given displayable object

Script specific commands:

autoShowStatus(boolean); // set whether the status window automatically appears when written to
help(); // prints command menu to status window
help("commandName"); // prints command forms for given command
newColorObject("colorName_string"); // Gets the color object for the given name
newColorObject(red_integer, green_integer, blue_integer); // Creates a color object with the given RGB values
newFileObject(filename_string, className_string, [param1], [param2], [...]); // Constructs new object of given class with given parameters or returns existing object based on same file

All Script Commands:

addCrosshairs(); // adds crosshairs to selected display objects
addShowPointLines(); // adds show point lines for selected display objects
addUnrelatedShowPointLine(); // adds a show point line not related to any object to the main display
attachTools(); // attaches the control panel to the display panel
autoShowStatus(boolean); // set whether the status window automatically appears when written to

back(); // moves currently selected images to be behind other images
backgroundColor(Color_object);// sets the current background color to the given color object
backgroundColor(color_string); // sets the back ground color to the named color if known
backgroundColor(red_integer, green_integer, blue_integer); // sets the background color to the RGB value

clearCrosshairs(); // same as deleteCrosshairs
clearDisplay();// clears display area
clearStatus(); // clears all text from the status window
clearUndos(); // clears undo/redo history
CNUVIEWER.intensityProject(); // creates an intensity projection of the current display object
color("apply"); // applies the current color map to all or selected images
color(ColorModel_object); // sets the current color map to the given color map object
color("current"); // sets the current color map to that of the currently selected image
color("filename"); // reads the current color map from a file
colorMap("horizontal"); // displays a horizontal color map
colorMap("quilt"); // displays a color map quilt
colorMap("vertical"); // displays a vertical color map
columns(integer); // sets the number of columns for display layout
copy(); // copies selected region, selected objects or all objects to the clipboard
copy("image"); // copies as an image only
copy("script"); // copies as a script only
copy("text"); // copies as text only
crop("apply");// applies crop to all or currently selected images
crop("current");// sets crop to that of currently selected image
crop("off"); // sets crop to none
crop("undo"); // removes cropping from all or currently selected images
crop(x_beg_integer, y_beg_integer, x_end_integer, y_end_integer); // sets crop box to given range

delete(); // deletes the currently selected display objects
deleteCrosshairs(); // removes crosshairs from selected display objects
detachTools(); // puts the control panel in its own window
disableStatusEdit(); // turns off show status edit option
disableUndos(); // clears undo/redo history and disables further history
display(); // displays the last read or displayed file
display(component_object x_location_integer, y_location_integer); // displays the given component at the given display location
display(class_name, [param1], [param2], [...]); // create and display a given class
display(displayable_object); // displays the given displayable object
displayAddShowPointLines(); // adds show point lines for selected display objects to the main display area
displayClass("class_name", [param1], [param2], [...]); // creates and display a given class
displayCursor();
displayCursor(boolean);
displayImageData(displayable_object); // displays the given displayable object
displayShowPointLinesFreeze(freeze_boolean); // sets selected show point lines in the main display area to freeze or not
displayShowPointLinesRecord(record_boolean); // sets selected show point lines in the main display area to record or not

echo([param1], [param2], [...]); // echos given objects to status window
enableUndos(); // enables undo/redo history for future commands
enableStatusEdit(); // enables edits in status window
exit(); // exits iiV

file("filename"); // reads the given file and displays according other settings
fileType(classToSelect); // given class is added if needed and selected in control panel
fileType("classNameToSelect_string"); // named class is added if needed and selected in control panel
fileType("raw"); // raw file type is selected in control panel
fileType("standard"); // standard file types is selected in control panel
filterSampling("interpolate"); // sets filter sampling mode to interpolate
filterSampling("replicate"); // sets filter sampling mode to replicate
flip("apply"); // applies flips to all or currently selected images
flip("horizontal"); // sets horizontal flipping
flip("horizontalOff"); // unsets horizontal flipping
flip("off"); // unsets both horizontal and vertical flipping
flip("vertical"); // sets vertical flipping
flip("verticalOff"); // unsets vertical flipping
font("apply"); // applies the current font to all or selected objects
font("type_string style_string", points_integer)" // sets the current font to given the type, style and size
font("off"); // clears the current font to use default
foregroundColor(Color_object;); // sets the current foreground color to the given color object
foregroundColor("apply"); // applies the current foreground color to all or selected objects
foregroundColor("colorName_string"); // sets the current foreground color to a named value
foregroundColor("off"); // restores default color for future foreground drawing
foregroundColor(red_integer, green_integer, blue_integer); // sets the current foreground color to the given RGB value freezeCrosshairs(); // freezes crosshairs in selected display objects
front(); // move currently selected image to be in front of other images

garbageCollect(); // requests garbage collection by the Java virtual machine
grid("on"); // turns on grid lines
grid("off"); // turns off grid lines
grid(spacing_float, "units_name"); // sets the spacing between grid lines
gridColor("colorName_string");// sets the grid to the named color
gridColor(Color_object); // sets the grid to the color object
gridColor(red_integer, green_integer, blue_integer); // sets the grid color to the given RGB value
gridOffsets(x_float, y_float, "units_name"); // sets the grid offset from the display origin
group(); // groups all selected objects
groupOverlapping(); // groups overlapping objects

help(); // prints command menu to status window
help("commandName"); // prints command forms for given command
hide(component_object); // hides the given component - not undoable
hideShowMemory(); // hides the show memory window
hideShowPoint(); // hides the show point window
hideStatus(); // hides the status window
hideTools(); // hides the control panel

incrementSlices(amount_integer); // increments by the given number of slices the slice displayed in all or selected images
iRange(first_integer, last_integer); // sets first and last i dimension limits
iRange("off"); // turns off i dimension limits

justification("centered"); // further text will be center justified
justification("left"); // further text will be left justified
justification("right"); // further text will be right justified

labelsApply(); // applies orientation and slice label modes to all or current images
labelsOff(); // turns slice and orientation labels off

newColorObject("colorName_string"); // Gets the color object for the given name
newColorObject(red_integer, green_integer, blue_integer); // Creates a color object with the given RGB values
newFileObject(filename_string, className_string, [param1], [param2], [...]); // Constructs new object of given class with given parameters or returns existing object based on same file
numberFormat(max_int_digits_integer, min_int_digits_integer, max_fraction_digits_integer, min_fraction_digits_integer, commas_boolean, exponent_multiples_integer, "exponent_symbol_string"); // creates a number format and sets as default
numberFormat(NumberFormat_object); // sets a numberFormat object as default
numberFormatApply(); // applies default number format to selected display objects

orientationLabelsOff(); // turns orientation labels off
orientationLabelsOn(); // turns orientation labels on
overlay(); // overlays current display object on top of all selected or all displayed objects
overlayAndGroup(); // overlays current display object on top of all selected or all displayed objects and groups each overlay with the object it was created to overlay

paper("on"); // turns the on paper outline
paper("off"); // turns off the paper outline
paper(width_float, height_float, "units_name"); // sets the paper outline size
paperColor(Color_object); // sets the paper outline color to the given color object
paperColor("colorName_string"); // sets the paper outline to the named color
paperColor(red_integer, green_integer, blue_integer);// sets the paper outline color to the given RGB value
paperOffsets(x_float, y_float units_name); // sets the paper offset from the display origin
paste(); // pastes from the clipboard to the display area
paste("image"); // pastes only an image from the clipboard
paste("script"); // pastes only a script from the clipboard
paste("text"); // pastes only text from the clipboard
position(x_integer, y_integer); // sets the display position for next object displayed

quant(quantification_factor_float); // sets a quantification value and turns on quantification
quit(); // exits iiV

readanew("off"); // turns off read anew feature
readanew("on"); // turns on read anew feature
readdisplays("off"); // turns off read displays feature
readdisplays("on"); // turns on read displays feature
redo(); // redo an undone command
relayout(); // rearranges displayed objects according to current number of columns
rotate("apply"); // applies rotation setting to all or current images
rotate(degrees_float); // sets rotation to the given angle in degrees
rotate("off"); // turns off automatic rotation of newly displayed images
rotate("on"); // turns on automatic rotation of newly displayed images

save("gif", "filename"); // save the display in Gif format to given the given file
save("ppm", "filename"); // save the display in PPM format to the given file
save("script", "filename"); // save the display as a script to the given file
save("settings", "filename"); // save the control panel settings as a script to the given file
saveStatus("filename"); // saves the status window's text to the given file name
scale("apply"); // applies the scale to all or current selected images
scale("current"); // sets scale to currently selected image
scale("CNUScale_object"); // sets scale to given scale object
scale("default"); // sets scale to default
scale("negative"); // sets scale to display negative values only
scale("positive"); // sets scale to display positive values only
scale("toRange"); // sets scale to display range as specified by min and max thresholds and values
scale(value_float); // sets the scale factor
scaleToRange(); // sets scale to display range as specified by min and max thresholds and values
screenResCorrection(factor_number); // sets screen resolution correction factor for grid and paper sizing
select("additions"); // any further display additions will be automatically selected
select("all"); // select all displayed objects
select("bottom"); // selects all displayed objects with no overlapping objects behind them
select(displayed_object); // selects the given currently displayed object
select("first"); // select the first display object
select(first_integer, last_integer); // select the given range of display objects
select("last"); // select the last display object
select("top"); // selects all displayed objects with no overlapping objects over them
selectShowPointLines("additions"); // newly added show point lines will be selected
selectShowPointLines("all"); // selects all secondary show point lines
selectShowPointLines(displayed_ShowPointDisplayLine_object); // selects a show point line object
selectShowPointLines("first"); // selects the first secondary show point line
selectShowPointLines("last"); // selects the last secondary show point line
selectShowPointLines(first_integer last_integer); // selects a range of show point lines
set(); // echos all set variables with value
set("variable_name"); // echos given variable value
set("variable_name value"); // sets variable to value
show("tools"); // shows the control panel
show("window_name_string"); // shows the named dialog window
showPointCrosshair(visible_boolean); // sets whether temporary crosshair shows over the primary object
showPointLinesCrosshair(visible_boolean); // sets selected show point lines to show crosshairs or not
showPointLinesFreeze(freeze_boolean); // sets selected show point lines to freeze or not
showPointLinesRecord(record_boolean); // sets selected show point lines to record or not
showPointLinesTrack(track_boolean); // sets select show point lines to track point or not
showPointMapTracking(map_tracking_boolean); // sets whether tracking is via mapped coordinates or raw indices
showPointRecord(record_boolean); // sets whether primary show point line records or not
showShowMemory(); // shows the show memory window
showShowPoint(); // shows the show point window
showStatus(); // shows the status window
showTools(); // shows the control panel
sliceLabelOff(); // turns slice labels off
sliceLabelOn(); // turns slice labels on
slices(first_integer, last_integer); // sets first and last slice limits
slices("off"); // turns off slice limits
snap("top"); // snaps object tops to the nearest grid line
snap("bottom"); // snaps object bottoms to the nearest grid line
snap("left); // snaps left side of objects to the nearest grid line
snap("right"); // snaps right side of objects to the nearest grid line
spatialMap("apply"); // applies the spatial map to all or currently selected images
spatialMap("current"); // sets the spatial map to a currently selected images
spatialMap(CoordinateMap_object); // set the spatial map to give coordinate map object
spatialMap("filename"); // reads the spatial map from the given file
spatialMap("off"); // turns off spatial mapping for further displayed images
startSliceTracking(); // starts slice tracking in selected display objects
stopSliceTracking(); // stops slice tracking in selected display objects

text("text_string"); // adds a display object with the given text
textColor("apply"); // applies the current text color to all or selected objects
textColor(Color_object); // sets the current text color to given color object
textColor("color_string"); // sets the current text color to a named value
textColor("off"); // restores default color for future text
textColor(red_integer, green_integer, blue_integer); // sets the current text color to the given RGB value
translation(value_float); // sets the translation amount
transparentColor("apply"); // applies the current default transparent index to currently selected images
transparentColor(index_byte); // sets the default transparent color index
transparentColor("off"); // turns off the transparent index for the current color map

undo(); // undo last command
ungroup(); // ungroup all selected (or all) top level grouped objects
unselect("additions"); // turns off automatic selection of display additions
unselect("all"); // deselects all objects
unselectShowPointLines("additions"); // newly added show point lines will not be selected
unselectShowPointLines("all"); // unselects all show point lines
unset(variable_name); // unsets the given variable

view("coronal"); // sets view mode to coronal
view("sagittal"); // sets view mode to sagittal
view("transverse"); // sets view mode to transverse

zoom("apply"); // applies zoom settings to all or current images
zoom("interpolate"); // sets zoom mode to interpolate
zoom("off"); // turns off automatic zooming of newly displayed images
zoom("on"); // turns on automatic zooming of newly displayed images
zoom("replicate"); // sets zoom mode to replicate
zoom("smooth"); // sets zoom mode to smooth
zoom(value_float); // sets zoom to a given floating point value
zoom(vertical_float, horizontal_float); // sets separate vertical and horizontal zooms to a given floating point values

Running with Sun Java Interpreter

The following is the basic command for running iiV directly with Java 1:

java -classpath iiV1181.jar:bsh.jar iiv.iiV

The following is the basic command for running iiV directly with Java 2:

java –jar iiV1181.jar

Java options

Any values before "iiV" in the Java command line are options to the Java interpreter. In the example above "-classpath iiV.jar" is an option telling Java where to find classes needed by iiV. Another important option is the maximum heap size. Java defaults to a maximum of 16 megabytes which may not be enough when multiple data files are displayed simultaneously. If Java is giving out memory allocation exceptions it may need to be restarted with a larger maximum heap size. Below is an example that sets the size to 256 megabytes.

java -mx256m -jar iiV1181.jar

Refer to Java documentation or type "java -help" to learn about other Java interpreter options.

Command line parameters

Any values after "iiv.iiV" or the -jar iiV1181.jar in the Java command line are passed as arguments to iiV. iiV recognizes the following arguments:

filename
-l lookupFilename
-c numberOfColumns

Example:

java -classpath iiV1181.jar iiv.iiV p0000dy1.img -l lookup.lkup -c 4

Where p0000dy1.img is the filename of a data file to read upon startup, lookup.lkup is the filename of a color map file to read upon startup and 4 is the desired initial number of columns.

Properties

Properties may be set on the Java command line with a "-D" flag before the jar file or "iiv.iiV". There are many default properties already set up by Java such as "user.home". The "-D" flag overrides these and can define new properties. Properties may also be set with the following script command:

java.lang.System.setProperty("propertyName", "propertyValue"); // sets a system property

The following properties are recognized by iiV:

browser=unixExecutableToDisplayHelp
BROWSER=unixExecutableToDisplayHelp
CNU.ColorDialog.path=pathToDirectoryWithLookupTables
CNU.CoordinateMapDialog.path=pathToDirectoryWithCoordinateMapFiles
CNU.defaults.file=filenameAutomaticlyReadOnStartup
CNU.help.file=localHtmlFileToUseForHelp
CNU.help.url=universalResourceLocatorHtmlToUseForHelp
ftpProxySet=trueOrFalse
ftpProxyHost=proxyHostToSendFtpRequestsThru
ftpProxyPort=portOnProxyHostToSendFtpRequestsThru
proxySet=trueOrFalse
http.proxyHost=proxyHostToSendHttpRequestsThru
http.proxyPort=portOnProxyHostToSendHttpRequestsThru
user.home=usersHomeDirectory

Example:

java -DCNU.defaults.file=myCNUSettings -DCNU.ColorDialog.path=/home/lookups -DCNU.CoordinateMapDialog.path=/home/mapfiles -classpath iiV1181.jar iiv.iiV

Where "myCNUSettings" is the name of a file to read upon startup instead of ".cnu", "/home/lookups" is a default directory to browse for color lookup tables, and "/home/mapfiles" is a default directory to browse for coordinate map files.

Running as an applet

iiV is written to be runnable as an applet within an HTML document. The most common applet parameter is the file parameter. The filename can be a complete Universal Resource Locator (URL) or a name relative to the applet context. Script files work best to control exactly how things are displayed. Files referenced in the script also can be complete URL's or relative to the applet context.

Applet parameters

Applet parameters are specified in HTML code as a param command (see example HTML code below). The following parameters are recognized by iiV:

name="file" value="filename"
name="help" value="helphtmlfilename"
name="columns" value="numberOfColumns"
name="lookup" value="lookupFilename"

Example HTML code

The following is an example of HTML code invoking iiV as an applet:

<html>
<head>
<title>iiV as an applet</title>
</head>
<h1> iiV as an applet </h1>
This sample only works with a Java 1.1 enabled browser.<p>
<applet ARCHIVE="http://james.psych.umn.edu/java/iiV1181.jar" CODE="iiv.iiV.class" WIDTH=500 HEIGHT=500>
<param name="file" value="http://james.psych.umn.edu/iiVSample.cnu">
If you see this message you don't have a java enabled browser!
</applet>
</body>
</html>

Applet limitations

There are some limitations when running as an applet due mainly to security issues as listed below.

May not read local files - security limitation enforced by applet environment.
File browse buttons disabled - although native browsers are sometimes available to the applet they mistakenly browse only local directories which are not available for reading. Hopefully future applet environments will support URL directory browsing.
Saving may not be allowed because of security problems. This is enforced by the applet environment.
Printing may not be allowed because of security problems. This is enforced by the applet environment. Printing should work directly from the web browser.
Quit button disabled - the applet environment is in charge of stopping and quitting.

When an applet security violation occurs the only notice appears in the Java console which is handled by the applet environment and often only displayed as an option.

Known problems

The following is a partial list of problems known to exist in the current iiV version.

· (A pain) Printing the display area sometimes produces black and white or grey level images instead of color. This seems to be related to color table handling in drawing an image to the print graphics. Sometimes it works if you change the number of colors supported by the system display area.

· (A pain) Saving gif images only supports 256 colors. This may generate an error with no save or may produce grey level images as with the printing error above or may work for mysterious reasons. Playing with display setting may work otherwise saving as ppm will work but then you have to find a tool to convert ppm to gif.

· (Deadly) Java 2 virtual machines can cause freezing and/or rebooting of Windows XP machines when too many resources are consumed. This is a known XP problem. No user process should be allowed to cause this type of system problem. It can help to set a large maximum memory on the java command line with an option like “–Xmx512m” which sets the max memory to 512 megabytes. The other option is to use java 1.1.8 which gives out of memory errors and may fail to display stuff but doesn’t freeze or reboot the system.

Acknowledgments

ANALYZE is a trademark of Biomedical Imaging Resource, Mayo Foundation, Rochester, MN

Java and all Java based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.

NIfTI - Neuroimaging Informatics Technology Initiative

DICOM – Digital Imaging and Communications in Medicine

Siemens USA

Stimulate – Center for Magnetic Resonance Research, University of Minnesota, Minneapolis, MN

JPEG – Joint Photographic Exports Group

GIF – Graphics Interchange Format

PPM – Portable PixMap

NEUROSTAT - Minoshima S, Frey KA, Koeppe RA, Foster NL, Kuhl DE: A diagnostic approach in Alzheimer's disease using three-dimensional stereotactic surface projections of fluorine-18-FDG PET. J Nucl Med 1995, 36:1238-1248.

iiV uses Fmt, GifEncode, JpegEncoder, PpmEncoder, PpmDecoder Java classes written by Jef Poskanzer at ACME Labs and requires the following copyright notification and redistribution statements:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistribution's of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistribution's in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Visit the ACME Labs Java page for up-to-date versions of this and other fine Java utilities: http://www.acme.com/java/