MBIV 1.0 User Guide



  1. Getting Started
  2. Uploading Images
  3. Troubleshooting


1. Getting Started

When the MBIV browser is either launched as an web-based applet or installed and run on the users local machine, initial dialog windows will inform the users about the progress and necessary actions. The user is notified once the initial processes are done. A screen shot of MBIV browser at this stage is illustrated here:


 

2. Uploading and Display Images


The browser is the client part of the client-server system. Together with the sever part, it manages the access to the images and atlases in our database. Before an image/atlas can be displayed and visualized, it must be uploaded from our remote database sever to MBIV. This is done via the "File" selection in the browser menu bar. The two selections under "File" are:

    "Open": Upload remote database images.

    "Import" : Import local image datasets. Currently, this option is not yet available.

When the user selects "Open->Remote Database Image", a Graphical User Interface (GUI) opened up within the browsers desktop area as illustrated below:


This user interface consists of a window with two tabs, "Atlas Database" and "Display Image/Atlas". The "Atlas Database" tab opens a panel allowing the user to query the database for those datasets fitting the selection criteria and then initiate the uploading process. The "Display Image/Atlas" tab opens a panel that allows a user to select the images/atlases already uploaded for visualization. More details are described in the following sections.



2.1 Instructions About the "Atlas Database User Panel


As previously mentioned, the "Atlas Database" user panel allows querying the datasets matching the given selection criteria in our database. The two selection criteria are a) the genetic strain and b) the data type. The genetic strain is self-explanatory and described on the main mouse brain web page. The data type as in our current release includes: raw MRI images of individual mouse brains, associated individual mouse brain atlases, averaged (minimum deformed) MRI brain image and corresponding atlas and a probabilistic atlas set. The list of MRI brain images and associated atlases is given in two scroll windows as illustrated below:



The user can then select the images and/or atlases that he/she wants to upload using the mouse. Multiple selections are allowed by using the SHIFT key in conjunction with the mouse. Also, deselect ion can be accomplished using CTRL key with mouse. As can be seen on the interface, there are three upload choices:


    a. Image/Atlas: Upload selected MRI images together with their corresponding atlases (whether or not the atlases have been explicitly selected) or with any other selected atlases.


    b. Image ONLY: Upload selected MRI images ONLY (no atlases are upload, even those associated with the selected images)


    c. Atlas ONLY: Upload selected atlases ONLY.


Once an upload selection has been made, a dialog box opens up for confirmation of the operation.



Note, in addition to a list of selected images and atlases, the dialog box also contains an option for selecting a uncompressed version of the selected images (compressed 8 bit, ~34MB vs. uncompressed 16bit, ~64MB). The user can Continue or Cancel the operation. If Continue is selected, a progress bar will keep track of the ongoing uploading status. Depending on what was selected to be uploaded, there could be more than one progress bar.

A single progress bar in the progress monitor is illustrated in here . The Name field is the internally generated name of the upload operation. The user can query the images and/or atlases that are being uploaded by moving the cursor over the name in the first column; a tool tip window will appear, describing what is being uploaded. The Progress field displays the current progress of the associated operations, Upload Time is the time that the operation has taken and Status shows the current status: "In progress" indicates the task is still running, "Completed" indicates the task has completed or "Aborted (exception") indicates the task was aborted due to some errors.




2.2 Instructions About "Display Image/Atlas" User Panel



Once the images and/or atlases have been successfully uploaded, they can be displayed via the Display Image/Atlas panel. At the top of the interface panel is a pull down menu containing all of the images that have been uploaded and a scrolling window with a list of available atlases. Appended to each atlas name is a a status indicator: [P] Pending (still loading), [L] for Loaded and [D] for displayed. Also, an atlas is marked with (*) to indicate the correspondence with the currently displayed MRI image. There are three display types as described below. The display type can be selected from the pull down list in the Display Selection area of the panel. Then by clicking on the "Open Display" button, the selected graphic window will show up.

    a) Single View Display: A single slice of image displayed in a single graphic window with one of the Coronal, Transverse or Sagittal views.

    b) Multiple View Display: All three views (Coronal, Transverse, Sagittal) of the image are displayed simultaneously in multiple windows.

    c) Multiple Slice Display: A series of consecutive slices from a same image are displayed side-by-side in a single graphic window. This function is not yet available.



Here is a single view graphic window:



The left of the graphics window contains a scroll window listing the color coded brain structure names. The captions in the main display window can be turned off/on from the Option pull down menu, such as the structure legends, image and atlas information, brain structure name and the intensity at the current mouse pointed location.




2.2.1 Display Functions



Single and multiple view display windows share much of the same image manipulation functions. Some most commonly used image manipulation functions are directly accessible on the menu bar, such as zooming, translation/panning, traversing slices.

The following features are also provided in both single and multiple display windows: 

    Traversing slices: Moving the slice slider bar will display slices in increasing or decreasing order.


    Zooming: Positioning the mouse in the graphics window, holding down the middle mouse button and moving the mouse in the +-Y direction (down/up). There are also zoom-In/-Out buttons that accomplish the same function on the user interface panel.


    Panning/Translating: Images in the graphics window can also be panned and/or translated in any direction. This is accomplished by positioning the mouse over the image, holding down the left mouse button and dragging the mouse in the desired direction of movement.


    Orientation: Changing the orientation of an image is done via the menu option, "Display->Orientation", allows a user to select the following preset image orientations: "Coronal", "Transverse" or "Sagittal".

    Brightness and Contrast: The brightness and contrast of a displayed image can be changed using the menu option, "Tools->Brightness and Contrast: The brightness and contrast of a displayed image can be changed using the menu option, "Tools->Image Intensity", which opens up a intensity control dialog . A user can independently change the intensity of each image or simultaneously change all in a multiple view display.




2.3 Displaying Regular Atlas



Regular atlases(individual atlases and minimum deformation (average) atlases) are displayed as color coded regions (or closed polygons edges), corresponding to the identified structures in the mouse brain. The color coded structures from the atlas are typically overlaid on the original MRI image Figure.

There are several options of the atlas display mode via the display mode panel located in the lower half of the MBIV panel:

    -Filled: In this mode, the brain structures in the atlas are represented as filled color-coded regions. There is also a slider that can be used in this mode to control the transparency of the color-filled regions (transparency ranges from 0.0 (invisible) to 1.0 (opaque)).

    -Outlined: The mouse brain structures in the atlas are represented as color-coded outlines.


    -None: Turns off the rendering of the atlas.



The browser provides the following additional functionality for selectively displaying regions and manipulating region colors. Also, the user can query the statistics and measurements for the selected region:

    Brain Structure Selection: A list of the brain structures and their corresponding colors is provided in the sub-window located on the left of the graphic window. The user can enable/disable the display of any selected region. First, the user has to select a region using the mouse (left button), highlight the  item in the list, click the middle mouse button and the corresponding colored region is rendered transparent in the graphics window. To enable the region, click the middle mouse button, which toggles the region on/off.

    Color selection/editing: The original color assigned to a region can be changed by a user in an interactive fashion. Selecting "Tools->Atlas Color" opens up a color selection palette window. In order to change the color of a region, it must be selected (highlighted) in the "Structures" scroll window.

    Brain Structure Statistics & Measurements: Users can query brain structure statistics and measurements. This can be done in two ways. First, by positioning the mouse over the structure of interest and right clicking the mouse which will pop up a menu from which a user can choose to query statistics or measurements. Selecting one will open up a dialog with the requested information. Second (which is not yet enabled), by right clicking on a highlighted region in the scroll window and following the same steps. 


    Displaying Multiple Atlases: By default, the atlas associated with the selected MRI image is displayed. It is possible to overlay more than one atlas on a MRI mouse brain image. When the user opens up a single image display via the local image user interface in the main browser, multiple atlases can be chosen by selecting other atlases from the list under the "Display" option in the menu bar. Given that our individual MRI mouse brain images/atlas are not aligned in a common space (in order to reduce interpolation error to the original data), it might not make any sense for this kind of visualization at this point. We keep this functionality for future display flexibility.




2.4 Displaying the Probabilistic Atlas



Probabilistic atlases are spatial probability maps of a group of mouse brains, in which each voxel value represents the probability p (0.0 ~1.0) of the brains having the same structure at this voxel. A probabilistic atlas is super-imposed on a chosen reference MRI image against which the whole group has been registered (Figure). Note that the user interface functionality for probabilistic atlas displays are different from those for regular atlases. Below is one unique function designed for the probabilistic atlas:


Thresholding of the probabilistic atlas: Users can dynamically change the threshold of the current probabilistic atlas from 0% to 100% by using the thresholding slider.




2.5 Displayable Captions



There are several captions that can be "turned on/off" and rendered in the graphics window. Enabling/disabling display of these captions is done via the "Options" selection in the display's menu bar. The available captions are:

    a) Color coded legends: Displays region names and associated colors.

    b) Probabilistic atlas color bar: Displays mapping of color to probability value.

    c) Image caption: Displays information about the brain image (name, dimension, and resolution, etc.)

    d) Atlas caption: Display information about the atlas (name, dimension, etc.) Note: Display of image & atlas captions is done in a mutually exclusive manner (i.e., both cannot be visible at the same time)

    e) Display caption: Displays mouse coordinate information, the brain structure name and the image intensity at where the mouse is currently positioned.




3. Troubleshooting



This section describes some problems that can arise when running the browser or the downloadable version with suggested solutions.

The only way to monitor the status of an applet is to open up a Java Console. All output (stdout, stderr) from the applet is redirected to the console, so that if there is a unrecoverable error (i.e. java.lang.OutOfMemoryError), the user will be aware of it. Also, the console serves as a tool by which errors can be diagnosed. So, when sending bug reports/errors, please include the contents of the console (cut and paste into email).


With respect to the downloadable browser application, all output is redirected to the window/terminal in which the application was launched. If the application was launched using Windows Explorer, a terminal (Command Prompt window) is created in which the batch file is executed.




3.1 java.lang.OutOfMemoryError



This occurs when the JVM (Java Virual Machine) runs out of memory. If this occurs, the browser has to be restarted, either by refreshing the page or closing the current page and reopening the browser. The images that are uploaded are on the order of 35MB (compressed) to 64MB (uncompressed), so the user may be limited by the memory capacity of his/her local machine. In this case, care has to be taken when uploading multiple images. Unfortunately, when images are no longer needed, there is no ready way to "free" that memory immediately. In a future release, the user will be able to free memory, but reclamation of freed memory will still be under the control of the garbage collection mechanism in the JVM.

One other factor that could contribute to java.lang.OutOfMemoryErrors is the JVM used to run applets in a web browser that has not been configured to run with a larger heap (memory area). Please refer to the Setup section.



Similarly, the same error can occur during the execution of the downloadable browser application if too many images are uploaded or the amount of memory on the local (client) system is low (e.g., too many applications running). One suggestion is to terminate unnecessary applications. Like the applet, the JVM might needed a larger heap area. A default heap size is specified in the run batch and script files as -Xmx200m (200 Megabytes). This value can be increased/decreased by editing the batch/script file. It is important and required that there is no white space in the parameter. If you want to increase size to 350 Megebytes, the format of the parameter is -Xmx350m.




3.2 Connection Error



Since the browser talks to remote servers, an image server and a database server, there could be connection problems if network problems are occurring. Connection to the servers could be lost while using the browser or during initialization. Moderate checking for connection/network errors has been added to the browser, but some could be unrecoverable. If a connection cannot be established after many retries, it's possible the machine hosting the servers is down.