Last modified 11 years ago Last modified on 09/25/06 14:51:29

Surface Projection Method Documentation


The surface projection method, a means of displaying volumetric data on a 3D surface, is implemented in the MindSeer framework. This document explains each of the components that contribute towards the execution of this method and is intended to supplement the JavaDoc embedded in the code.

Important Classes & Interfaces

Class ColorizedVolumeSurface3DView

This class is the main handler of the surface projection method. It and its inner classes maintain references to the volume data and the attached surface. It handles changed parameter events and issues appropriate invalidation calls to force the resampling of data values and colors. It also issues long tasks to the thread pool for performing these resampling procedures.

Class SurfaceVolumeDataController?

This class provides a user interface for manipulating the settings for the Colorized-VolumeSurface3DView. It displays sliders for controlling thresholding, color schemes, color legends for mapping data values to colors, filter kernel controls, and sampling method controls. It also acts as a listener for the backing 3D surface controller to report changes in the attached surface to the instance of the ColorizedVolumeSurface3DView.

Class SurfaceDataViewUnion?

This class exists to service the shared data aspect of the ColorizedVolumeSurface3D-View. In order to permit the display of multiple volumes on a single surface without creating multiple instances of that surface, this class manages the invalidation steps and initializes the coloring pipeline. It also tells each registered ColorizedVolumeSurface3D-View whether or not it is to return a BranchGroup? object containing the colored surface to the view port when the view port attempts to display the surface.

Class SurfaceDataViewUnionController?

This class provides a user interface for manipulating the settings for the SurfaceData?-ViewUnion?. It displays a tree of each surface and attached volume data sets. It also provides controls for adding more volumes, changing the combiner method and blend function, and setting the color schemes for combiners that override the volumes’ selected color schemes.

Classes PreprocessingData? and CombinerPreProcessor?

The PreprocessingData? class stores a collection of aggregate data for use by the combiners. It contains min values, max values, mean values, mean of positive values, and mean of negative values. Additional value types can be added to the collection by modifying each of these two classes; edit PreprocessingData? to provide storage for the data, and edit CombinerPreProcessor? to sample the data.

Interface VolumeDataCombiner?, Its Implementing Classes, and Class VolumeDataCombinerFactory?

The VolumeDataCombiner? interface provides a definition of the necessary methods for creating a combiner. The combiner takes a set of sampled volumes and computes a single value to represent each point and yields a color for each vertex on the surface. A set of sample implemented classes are provided that each perform a different computation. Each of these, and any future implementations of the VolumeData?-Combiner interface, need to be registered with the VolumeDataCombinerFactory? to ensure that existing code is able to use each of these combiners.

Interface DataPointSampler?, Its Implementing Classes, and Class DataPointSamplerFactory?

The DataPointSampler? interface provides a definition of the necessary methods for creating a data point sampler. The sampler takes a volume data set and a surface model and yields a collection of sample values, one for each vertex in the model. A set of sample implemented classes are provided that each perform a different computation. Each of these, and any future implementations of the DataPointSampler? interface, need to be registered with the DataPointSamplerFactory? to ensure that existing code is able to use each of these samplers.

Class BlendFunction?, Its Subclasses, and Class BlendFunctionFactory?

The abstract class, BlendFunction?, provides some basic implementation and a definition of some additional methods required to create a blend function. A blend function takes two input colors (the base color of the unmodified surface and the computed volume color) and outputs a single color for use on the surface. A set of sample concrete classes are provided that each perform a different computation. Each of these, and any future implementations, need to be registered with the BlendFunctionFactory? to ensure that existing code is able to use each of these blend functions.

Class Kernel3D

This class, when instantiated with a kernel definition, can apply a filter kernel over a volume yielding a new volume. While the kernel is only a 3D filter kernel, volumes containing multiple time points can also be used; in this case, each time point is filtered independently. This class also provides a couple static methods for creating a 3D Gaussian-blur kernel, which can be used to bring data that is close to the surface out to the surface.

Class SHColorLegend

This class renders an image of a color legend, which maps data values to colors, and vice-versa. Instances of this class can be placed in UI controls. When provided the appropriate values, colors, and color lookup tables, it will display the appropriate legend.

Color Calculation Pipeline Implementation


The volume sampling and color calculation pipeline is implemented as a series of stages. A few of these stages are replaceable by implementing instances of the interfaces and abstract classes listed in the previous section. The pipeline consists of the following stages:

  • Pre-filter the volume data using a filter kernel
  • Sample the volume data to compute a value at each vertex of the model
  • Perform aggregate summary calculations over each sampled dataset for later use
  • If multiple volume datasets are present, unify them into a single dataset
  • Perform color calculations, then create and display the textured model

These stages are illustrated in the diagram below. A triplet of arrows represents multiple datasets passing between stages. A single arrow represents a single data set passing between stages.


This section describes the basic steps that occur during usage of this rendering method.

Loading the First Volume

After a user clicks on the button to add a volume to a surface, and selects a surface to load, the SessionImpl? object loads an instance of the ColorizedVolumeSurface3DView into the view port and associated data model. The file group used to perform this loading is slightly tweaked to include a unique tag representing the surface model. As a result, when the ColorizedVolumeSurface3DView is added to the model, it is able to read that tag and know which surface to use as the sampling surface.

As the ColorizedVolumeSurface3DView is added to the model, it performs a few other initialization steps. It searches for an appropriate volume data mask so that it can know which of the volume data is valid and which is not valid. It also generates a SurfaceDataViewUnion?, if one does not already exist in the data model, for managing multiple loaded volumes and managing the pipeline. Additional steps include the initialization of the default values for the view and the creation of a controller. When the default values are sent to the ColorizedVolumeSurface3DView, the view triggers an unforced invalidation, described in a later section.

Handling a User Specified Parameter Change

Parameters can be changed by the user in a few places: by using the SurfaceVolume?-DataController?, by using the SurfaceDataViewUnionController?, or by using the original surface’s controller. Changes made using the SurfaceVolumeDataController? only invalidate the sampled data for the modified volume. Changes made using the SurfaceDataViewUnion?-Controller invalidate only the combiner stage. Changes made using the original surface’s controller invalidate all of the attached volumes completely.

Handling an Invalidation

All types of invalidate propagate back to the SurfaceDataViewUnion? instance that is shared by the ColorizedVolumeSurface3DViews. The invalidation can be forced or not forced. Of the three parameter-changed cases mentioned in the previous section, only the last two are forced invalidations. If the invalidation is forced, even if none of sampled data changes, the colors will still be recalculated.

Once the invalidate method is called in SurfaceDataViewUnion?, any currently running invalidations are cancelled. Then each of the ColorizedVolumeSurface3DViews is invalidated. Each ColorizedVolumeSurface3DView knows if it truly needs to be resampled during invalidation. If a ColorizedVolumeSurface3DView needs to be resampled, then it submits a task to the thread pool to filter the data (if the filter kernel is enabled and has changed) and resample the data. The data is resampled using the selected instance of the DataPointSampler? interface. Once the data has been resampled, it returns the new sample set to SurfaceDataViewUnion? for further processing. If resampling was not necessary, the old sample set is immediately returned to SurfaceDataViewUnion?.

Once each of the ColorizedVolumeSurface3DViews reports back a sample set, the combination and color calculations begin. If at least one of the sample sets is reported as having changed or the invalidation is forced, then computation continues. First each of the sample sets are reorganized into the format the combiner uses. Then a task is submitted to the thread pool to perform the color calculations. This task first computes the aggregate data using the CombinerPreProcessor? and PreprocessingData? classes. Then the selected VolumeDataCombiner? and BlendFunction? are used to process the data and compute a set of color arrays. Once the color arrays are ready, the new surface model is attached, and the old surface model is detached.

Possibilities for the Future

There are several possibilities for future development, listed as follows:

  • Create new combiners for supporting more types of comparative analysis
  • Extend the other types of 3D models to support the ColorizedVolumeSurface3DView
  • Convert the BlendFunction? abstract class into an interface and default abstract class
  • Convert each of the factories to use configuration files
  • Provide thresholding support for the combiner’s overriding color schemes