Inputs

Environment

JIV can be run either as a Java applet, either as a (standalone) Java application.

Running it as an applet requires an HTML file to invoke it; however, this can be a very simple file, containing only the applet tag. This applet expects a run-time parameter (in the form of an applet parameter): the URL of a config file, which contains information about which 3D data volumes to load, the layout of the user interface, initial settings of various controls, and so on.

The applet can be launched by some HTML code like this:

<applet height=50 width=400 archive="jiv.jar" code="jiv/Main.class">
        <param name="cfg" value="config_file">
</applet>

where jiv.jar should be the URL of the JAR file containing the JIV Java bytecode, and config_file should be the URL of the appropriate JIV config file (config can be used instead of cfg for the parameter name). The config file can also be supplied ``inline'' within the HTML file using the inline_cfg (or inline_config) applet parameter; for example:

<applet height=50 width=400 archive="jiv.jar" code="jiv/Main.class">
        <param name="inline_cfg" value=" ;
# config file's content here: ;
data1 : data1.raw_byte.gz ;
jiv.panel.0 : data1 ;
# ... ;
">
</applet>

Note that, unlike the separate config file, the inline config needs to have each line terminated with the ';' character. Both a separate config file and an inline config can be supplied at the same time: the inline config is read last, so its content takes precendence for keys defined in both places.

The HTML file is not needed when JIV is not run as an applet but as a regular Java application. In this case, the config file's URL can be supplied as a command line argument, or as the value of the cfg or config Java system properties (``environment variables''). The top-level class that needs to be run is the same (jiv/Main.class).

Config File

The config file is expected to be in the following format:

• Lines are separated by ';' in the inline config, and by the normal 'newline' in a config file.
• Lines that begin with # or ! are comments and are ignored.
• Blank lines are ignored.
• All other lines should specify a key/value pair and be of any of the following three equivalent forms:

           key = value
           key : value
           key value
  

  Leading/trailing whitespace and control characters in value are trimmed off.
• The following escape characters are also recognized and treated as follows:
  • \newline : an escaped newline character is ignored, along with the spaces or tabs that follow it.
  • \n : expands to a newline character.
  • \r : expands to a return character.
  • \t : expands to a tab character.
  • \uxxxx : expands to the Java Unicode character code specified by the hexadecimal digits.

Keys which start with ``jiv.'' are JIV configuration options. Keys which do not start with ``jiv.'' give the location of the image data files (image volumes). JIV configuration options refer to data files by means of data volume aliases, i.e. a kind of a short name. The alias is displayed as a title at the top of each panel, hence it's a good idea to choose something descriptive and short (such that it will fit in the, possibly narrow, panel).

For a given alias ``myalias'', the value associated with key myalias is the volume image file's URL (URL-s for the individual slices are derived from the volume URL, as described in section 1.3). The value associated with key myalias.header is the URL of the header file associated with the image file(s). All relative URL-s are interpreted relative to the base URL of the config file, or relative to the base URL of the HTML file launching the applet if a config file is not defined (by means of the cfg or config applet parameters). If all volumes have the same header, it is acceptable to specify it only for one of the volumes; otherwise, a header should be specified for all volumes (see section 1.3 for the header file format).

The following JIV configuration options are supported:

• jiv.sync = [true|false]
  Sets the initial state of the Sync all cursors control. The default is false.
• jiv.world_coords = [true|false]
  If false, only voxel coordinates will be available in the user interface (however, doing this is not recommended practice!). The default is true.
• jiv.byte_values = [true|false]
  If true, all the voxel values, including the colormap range values, are presented in the user interface as byte values (0-255). If false, they are presented as fractional values (0.0-1.0). The default is false.
• jiv.panel.N = alias
  Specifies an individual volume panel, i.e. an interface panel displaying a single data volume (specified by alias, which should be a data volume alias declared somewhere else in the same config file). N should be a non-negative integer and represents this panel's number.
• jiv.panel.N.combine = alias1 alias2
  Specifies an combined volume panel, i.e. an interface panel displaying a combined view of two data volumes (specified by alias1 and alias2). N should be a non-negative integer and represents this panel's number. The two aliases should be separated by one or more blanks ( ) or tabs (\t). Also, these two aliases should be displayed in their individual panels as well. If an alias is displayed in more than one individual panel, then the lowest numbered such panel is used as the ``source'' for that volume alias.
• jiv.panel.N.coding = [gray|grey|hotmetal|spectral|\
red|green|blue|mni_labels]
  Specifies the initial color coding for panel N, which has to be an individual volume panel.
• jiv.panel.N.range = L U
  Specifies the initial lower and upper limits of the color coding range for panel N, which has to be an individual volume panel. L and U should be fractional (float) numbers in the range 0.0-1.0. The two should be separated by one or more blanks ( ) or tabs (\t).
• jiv.download = [upfront|on_demand|hybrid]
  Specifies the data (down-)loading method.

  In mode upfront, all of the data is loaded and stored in memory before the user can view and interact with any of it. This guarantees the best interactive response of the viewer, however the user has to wait for all the data to load before the JIV interface becomes available. This mode is recommended when the data is available locally, but is impractical for accessing remote data over a slow network.

  In mode on_demand image data is loaded one slice at a time, and only if and when the user is viewing that particular slice number. This mode is recommended for remote access over very slow networks. It minimizes the data downloads and the amount of memory required by JIV, but the interactive performance is completely dependent on the network speed.

  Mode hybrid combines the other two: the complete image volume is downloaded in the background, and the slices at the cursor are downloaded with priority, as soon as they are needed. This mode is the recommended for typical remote data access situations; it provides the fast startup of on_demand and, after the background downloading completes, the optimal interactive performance of upfront.

Panels are displayed left to right, sorted by their increasing number. Note that these numbers do not have to be consecutive -- ``gaps'' in the numbering sequence are silently skipped. Note that the same alias (i.e. the same data volume) can be displayed in several individual and combined volume panels.

The config file is parsed in several passes, so the order of the key/value pairs is irrelevant. However, if several conflicting key/value definitions are given (which is bad practice, by the way), not the last definition given but a random one of them will be considered!

Data Files

JIV reads 3D image data from an image file which should contain the image intensity (gray level) data represented as unsigned bytes (8-bit). The image data are interpreted using an associated header file, which specifies the volume sampling, world coordinates (real world mm), and real image values. All the data files can be optionally compressed using gnuzip, in which case their names (URL-s) need to have the .gz suffix.

The header file is a text file with the same syntax as the config file (see section 1.2). The following statements are supported (where the 3 values of the right-hand side can be separated by whitespace or ``,'') :

• size : x_size y_size z_size
  the sizes (voxel counts) of the 3D image along the x, y, and z axes respectively.
• start : x_start y_start z_start
  the distance (in real world mm) from the origin to the first voxel along the x, y, and z axes respectively.
• step : x_step y_step z_step
  the signed distance (in real world mm) between the centers of consecutive voxels along the x, y, and z axes respectively; a negative value indicates that the file scans the volume in negative direction along that axis.
• order : (permutation of {x,y,z})
  the order of dimensions in the file, i.e. the order in which the volume file scans the (3D) data volume -- e.g. ``order : z y x'' means that the $x$ coordinate changes fastest (volumes using this particular dimension ordering are also known as ``transverse'').
• imagerange : range_min range_max
  the linear mapping from the byte voxel values to the real image voxel values: 0 maps to range_min, 255 maps to range_max.

The $x, y, z$ axes and their positive direction are assumed to be (respectively): left to right, posterior to anterior, and inferior to superior of a 3D medical image. Note that the sizes, starts, and steps are always expected in $x, y, z$ order, regardless of the file dimension order. If any of the header information is not specified, the following defaults are used (they correspond to the ``ICBM'' sampling and to the ``Talairach'' stereotaxic coordinates systems used at the Montreal Neurological Institute, McGill University):

  size   :  181 217 181
  start  :  -90 -126 -72
  step   :  1 1 1
  order  :  z y x
  imagerange  :  0.0 1.0

Performance tip: Due to internal optimizations, the initial download of the image data will be faster if all the steps are positive and equal (for all dimensions and all image volumes) and the dimension ordering is 'z y x'. However this performance difference will be hardly noticeable when using a modern Java runtime environment (JVM)...

There are two kinds of image files:

volume file:

contains the complete (3D) image volume data; it is required by the upfront and the hybrid download modes.

slice file(s):

contain a 2D slice of the 3D image volume; three sets of all the slices orthogonal to each of the three coordinate axes are required by the on_demand and the hybrid download modes.

The volume file URL is specified in the config file (as shown above in section 1.2); the slice files are expected at URL-s of the form: base/orientation/slice_number.extension, where orientation is one of ``01'', ``02'', or ``12'' -- the name indicates which are the in-slice dimensions (in file dimension order) for that orientation. For example, for a ``transverse'' volume (order: z y x) 01, 02, 12 correspond to ``sagittal'' (z-y), ``coronal'' (z-x), and ``transverse'' (y-x) slice orientations.

base and extension are obtained by breaking the volume file URL at the last ``.'' (other than the suffixes .gz or .bz2); for example, all of the following:

  /some/dir/somename.raw_byte.gz
  /some/dir/somename.raw_byte
  /some/dir/somename.gz
  /some/dir/somename

result in base = /some/dir/somename .

For converting MNI-MINC data to the JIV input format, two utilities (Perl scripts) are distributed along with JIV: minc2jiv.pl, and jiv.pl.

Note: the upfront download mode requires the volume file(s), the on_demand mode requires the slice files, and the hybrid download mode requires both the volume and the slice files.