From Van Essen Lab

Jump to: navigation, search


Project Organization


Listed below are the names of the projects. A project may rely on any project that is listed under the project. For example, Brain may call anything in Files since Files is under Brain. However, File MAY NOT call anything in Brain.

  • Testing
  • Desktop, CommandLine
  • Commands
  • GuiQt
  • OpenGL
  • Statistics
  • Brain
  • Algorithms
  • Helpers
  • Files
  • Cifti
  • Gifti
  • Nifti
  • Palette
  • Xml
  • Common

Some Objects and Processes in Caret

Listed in this section are descriptions Caret's essential data structures its fundamental processes.

What is an Object?

An object is a thing that is different than other things and possesses both attributes and behaviors. An example is a Dog. Its attributes include its size and color. Its behaviors include barking and running. Your dog is an instance of Dog. See

The Caret software is composed of many objects such as Display Control, Brain, Metric File, and so forth. The interaction of these objects creates the Caret software.

Windows and Window Panes

Using the latest design, Caret eliminates the concept of Main Window and Viewing Windows and replaces them with Windows. Each of these windows can have multiple Window Panes with each Window Pane accessed by a 'Tab' in the Window. Surface and Volume overlays are assigned to each Window Pane. Thus, the same surface may be displayed in multiple Window Panes with different coloring and orientation in each of the Window Panes.

Brain Object

Like the human brain, the Caret 'Brain' holds all of the data loaded into Caret (volumes, surfaces, metric files, foci files, etc.) from one spec file. Some of the data will be held in the Brain and other data in child objects of the Brain. In addition, the Brain contains the 'DisplaySettings' for each data type. The DisplaySettings objects are used to control the display of individual data types. In most cases, the DisplaySettings objects are updated by the user by using the Display Control Window. As files are loaded, modified, or deleted, the Brain will notify the appropriate DisplaySettings object that the data has changed and that DisplaySettings object will update itself.

Surface-based files for a cerebral cortex or the cerebellum are grouped into a BrainStructure. Grouping is performed using both a structure identifier and the number of nodes. There have been discussions regarding the loading of multiple resolution surfaces and grouping by structure along with the number of nodes will allow this in the future.

Reading of data files from a Spec File will be performed by an algorithm object. As each file is read, the data file will be delivered to the Brain. If the file is structure independent (volume, foci), the brain will take ownership of it. If the file is surface-based, the brain will use the file's structure identifier and its number of nodes to find the appropriate BrainStructure. If no matching BrainStructure is found, one will be created. The BrainStructure will then take ownership of the surface-based data file. After all of the Spec File's data files are loaded, all of the DisplaySettings are updated.


No files will be merged as they were in Caret5 and Caret6. Each file will be stored separately and thus, if modified, saved separately. A option to consolidate files of the same type may be offered in either the GUI or the command line.

Brain Manager

Since there have been discussions about loading multiple Spec Files, a BrainManager may be needed. The purpose of the BrainManager is to manage multiple Brain objects. If a BrainManager is needed, some of the DisplaySettings will be moved into the BrainManager.


Scenes save "the state" of caret so that it can be reproduced at a later time (Apple Lion calls this "Resume", Java calls it serialization). When the user requests the creation of a scene, the Brain (or BrainManager) will determine the names of all loaded files and add them to the scene. Next, all of the DisplaySettings are directed to add their state to the scene. Lastly, the surface and volume overlay assignments are added to the scene. Additional logic in the GUI will save the contents and positions of the windows and the orientations of the models.

Surface Overlays/Volume Overlays

A SurfaceOverlay object contains a data type (label, metric, etc), an opacity, and a 'column selection. A SurfaceOverlaySet contain an array of SurfaceOverlay objects with the number of elements set to the number of overlays. Since each window pane has its own overlay assignements, the Brain maintains an array of SurfaceOverlaySets with the number of elements set to the maximum number of Window Panes (30?).

Volume Overlay operate in a similar manner.

Viewers, Controllers, and Window Panes

A viewer provides a view of brain data. In the prototype, their are five types of viewers Whole Brain, Surface, Slices, Slices Montage, and Slices Oblique. A ModelController contains parameters that control the view of the data which includes, panning, zooming, rotation, slice selection, etc. As the user alters selections in the toolbar or alters the view of the surface/volume model using the mouse, the ModelController is updated with the parameters. Each of the ModelController contains one set of these parameters for each Window Pane which allows alternative views of a model in different Window Panes. Each of the types of ModelControllers has one instance with the exception SurfaceModelControllers that are contained in each surface. The other ModelControllers are stored in the brain since the validity of these ModelControllers is dependent upon the files that are loaded and that the Brain manages the files.

Surface Coloring

A unique set of surface overlays (SurfaceOverlaySet) are assigned to each window. Since all surfaces in a single brain structure use the same node coloring, the node colors are maintained by BrainStructure. This avoids duplication of the node colors in each surface.

Drawing Models

When drawing of a surface is requested, a ViewerControllerSurface and a Window Pane identifier are sent to the OpenGL rendering object. First, the necessary transforms (panning/zooming/rotation) are obtained from the ViewerControllerSurface for the WindowPane. Second, the Surface is obtained from the ViewerControllerSurface. Third, the coordinates and triangles are obtained from the Surface. Fourth, the BrainStructure is obtained from the Surface (Recall that BrainStructure is the parent of the surface). Fifth, the node coloring is requested from the BrainStructure. Lastly, OpenGL commands are issued to draw the surface.

When drawing volume slices, a ViewerControllerSlices and a WindowPane identifier are sent to the OpenGL rendering object. First, the panning an zooming transforms (rotation is not allowed) are obtained from the ViewerControllerSlices. Second, the Brain is obtained from the ViewerControllerSlices. Third, from the Brain, the VolumeOverlaySet is requested. Fourth, the overlays are examined to find the volume slices and the bottom-most volume slices. Fifth, for each voxel in the bottom-most volume slice, its stereotaxic coordinates are obtained. Sixth, using this stereotaxic coordinate, all of the volumes in the overlay set are examined and the coloring for the voxel from the top-most volume slice is used to draw the voxel.

GUI & Brain interaction

When the user changes an item on a Display Control page, the selections are read from the Display Control, sent to the Brain, and then the graphics are updated.

Example: if the user selects a focus name, DisplaySettingsFoci is requested from the Brain, DisplaySettingsFoci is updated with the new Focus Selection, and lastly the graphics windows are updated.

Example: The if the user changes a surface overlay for Window Pane X, the Surface in Window Pane X is obtained. From the Surface, its BrainStructure is obtained and the surface coloring for WindowPane X is invalidated. Next, redrawing of the surface is requested. In the OpenGL rendering code, it will request the node coloring from the BrainStructure. BrainStructure will see that the node coloring is invalid and then update the node coloring for Window Pane X. OpenGL rendering now has coloring and draws the surface.


When an identification operation is performed, the data types under the mouse cursor are reported. These data types include a surface triangle, surface node, volume voxels, foci, etc. This information is passed to a BrainIdentification object that uses the Brain and its children to generate text information that is displayed in the Identification Window. For some types of data, the Study or Vocabulary files are accessed to provide additional information. For example, a focus may link to a study and the information from that study is displayed. Another example is an identified node that links to label data. The labels in the Identification window will become hyperlinks that display vocabulary information when the hyperlinks are clicked.


WebCaret essentially replaces the GUI library with a web-based interface. Web-Caret is written in Java.

Brain Module

Composition of Brain Objects

  • Brain (Manages data loaded into Caret).
    • AnnotationFile
    • BorderProjectionFile
    • BrainIdentificationTextGenerator (Generates text of identified items for display in IdentifyWindow)
    • BrainStructure(s)
      • LabelFile
      • MetricFile
      • RGBA File
      • Surface(s)
      • SurfaceRegionOfInterestFile
      • SurfaceNodeAttributes (Attributes of nodes including identification status, morphing forces, and others).
      • SurfaceOverlayColoring (Colors nodes using surface overlay selections)
    • ConnectivitySelectionManager (Manages connectivity selectors).
      • ConnectivitySelector[number-of-selectors] (Loads connectivity data for display on surfaces, volumes, and in time chart).
        • ConnectivitySelectorDense (Loads Dense Connectivity Data)
        • ConnectivitySelectorDenseTimeOverlay (Loads Dense Time Series Data)
        • ConnectivitySelectorDenseTimeTimeCourse (Loads Dense Time Course Data).
      • ControllerSurface (was ViewerSurface)
      • ControllerVolumeSlice
      • ControllerAllStructures
    • DisplaySettingsAnnotations (controls display of annotations: on/off. Selections made on Display Control).
    • DisplaySettingsBorders (controls display of borders: on/off, line-width etc. Selections made on Display Control).
    • DisplaySettingsFoci
    • DisplaySettingsLabel
    • DisplaySettingsMetric
    • DisplaySettingsRecording
    • DisplaySettingsScene
    • DisplaySettingsStudyMetadata
    • DisplaySettingsSurface
    • DisplaySettingsVectors
    • DisplaySettingsVolume
    • FociProjectionFile
    • FociSearchFile
    • Palette File
    • Scene File
    • Study Metadata File
    • Study Collection File
    • SurfaceOverlaySet[number-of-windows]
      • SurfaceOverlay[number-of-surface-overlays]
    • Volume Files - Anatomy
    • Volume Files - Functional
    • Volume Files - Label
    • Volume Files - Probabilistic Atlas
    • Volume Files - RGBA
    • Volume Files - Segmentation
    • Volume Files - Vector
    • VolumeOverlaySet[number-of-windows]
      • VolumeOverlay[number-of-volume-overlays]
    • VolumeOverlayColoring
  • Algorithm (located in Common)
    • AlgorithmDataFileReader (reads data file into Brain or BrainStructure).
    • AlgorithmDataFileReaderInfo (Information about a file (structure, type, name for use by AlgorithmDataFileReader).
    • AlgorithmSpecFileDataFileReader (reads the files selected in a spec file).
    • AlgorithmSurfaceCurvature (computes surface curvature)
    • AlgorithmSurfaceSulcalDepth (computers surface sulcal depth).
    • Many others for implementation later.
  • MouseAndKeyboardProcessingInterface (Implemented for each mouse mode)


Main program for command line operations.


Contains classes for execution of commands on the command line.


Common contains classes that are essentially utility classes that may be used by any other project. Some examples include data compression, mathematical operations, etc.

Would Utilities be a better name for this library?

Common Objects

  • Algorithm (Base class for all algorithms)
  • Base64 (Performs base64 encoding/decoding)
  • BoundingBox
  • ByteOrderEnum (byte order operations)
  • ByteSwapping (performs byte swapping due to byte order differences).
  • CaretLogger (Logs messages in place of print statements)
  • CaretObject (base class for all classes not derived from a class)
  • CaretPreferences (Handles user preferences; foreground color, etc.)
  • CaretWindowEnum (Enumerated type for items that manage data on a per-window basis).
  • DataCompressZLib (Compression/decompression using ZLIB).
  • DataFile (Abstract class for all files)
  • HtmlStringBuilder (Simplifies construction of HTML for display in GUI).
  • MathFunctions (Various mathematical operations)
  • Plane (Operations related to Plane).
  • Polygon (Operations related to Polygons)
  • ProgramParameters (Simplifies processing of command line options)
  • SpeciesEnum (enumerated type for species)
  • StereotaxicSpaceEnum (enumerated type for stereotaxic space).
  • StringUtilities (Operations on String -- Replace with new String class.
  • SystemUtilities (Operating system operations)
  • TracksModificationInterface (Interface for objects whose modification status needs to be tracked such as files).


Desktop is a small main program that creates the desktop application.


Files contains classes for all data files that Caret supports. It may also contain some algorithms that operate on Caret classes. The class for each file is a descendant of DataFile or one of its descendants such as GiftiFile.

Files Objects

  • AlgorithmSurfaceGeodesicDistance
  • AnnotationFile
  • AnnotationFileSaxReader
  • CaretFileNameParser (Decomposes caret file names into components)
  • DataFileTypeEnum (Identifies file, spec file tag, extensions, etc).
  • GeodesicHelper
  • GiftiTypeFile (Encapsulates a GiftiFile).
  • LabelFile
  • MetricFile
  • Palette
  • PaletteFile
  • PaletteScaleAndColor
  • RGBA File
  • SpecFile
  • SurfaceFile
  • SurfaceRegionOfInterestFile
  • Volume (May have Sparse and Full)
  • VolumeFile

Files Objects Needed Later

  • BorderProjectionFile
  • BorderProjectionFileSaxReader
  • BorderProjection
  • FociProjectionFile
  • FociProjectionFileSaxReader
  • FociSearchFile
  • FocusProjection
  • SurfaceNodeLocator
  • SurfaceNodeLocatorBucketSearch
  • SurfaceProjector
  • Study...
  • SurfaceProjectedItem
  • Vocabulary...


CIFTI contains classes for manipulating CIFTI connectivity files.


GIFTI contains classes for manipulating GIFTI surface-based data files.

GIFTI Objects

  • GiftiArrayIndexingOrderEnum (Indicates row/column major order of data array)
  • GiftiDataArray (dimensions and data type may vary)
  • GiftiFile (Contains the data arrays)
  • GiftiFileSaxReader (Reads a GiftiFile).
  • GiftiEncodingEnum (Data encoding: Ascii/base64,gzip-base64,external binary)
  • GiftiEndianEnum (byte order of binary data)
  • GiftiException
  • GiftiLabel (Label name, color)
  • GiftiLabelTable (Organizes labels)
  • GiftiXmlElements (GIFTI File XML names)


GuiQt contains classes for constructing the graphical user-interface using Qt.

Gui Objects

  • Actions (Contains actions attached to menus and other GUI components).
  • AlgorithmExecutorDialog (Executes Algorithm subclasses in the background and allows cancellation).
  • BrainOpenGLWidget (Extends Qt widgets for OpenGL graphics)
  • CaptureImageDialog (Captures images of graphics)
  • ChartLineDialog (Displays charts such as time series)
  • ConnectivitySelectorDialog (Sets up connectivity selectors - Move to Display Control)
  • DataEntryDialog (Generic dialog for data entry).
  • DataFileOpenDialog (Dialogs for opening files).
  • DisplayControlDialog (Display Control Dialog)
  • DisplayControlPage (one or more for each data type).
  • Globals (Contains a few global variables and functions such as redrawing graphics)
  • IdentifyDialog Lists identification information.
  • ManageLoadedFilesDialog (Manage and save loaded files)
  • MultiPageDialog (Dialog with multiple pages subclasses by display control and operation dialogs).
  • MultiPageDialogPage (Page in multipage dialog).
  • NonModalDialogInterface (Interface implemented by non-modal windows so that they can be updated due changes in data).
  • NonModalDialogManager (Manages non-modal windows and issues updates to windows registered with this).
  • OpenGLMouseEvent (Mouse event, may belong in Brain or OpenGL projects).
  • PaletteColorMappingPanel (Widget for editing palettes used by connectivity, metric, shape).
  • SpecFileDialog (Select and load files from a SpecFile).
  • WindowMain (Main window, toolbar, status bar, menus)


NIFTI contains classes for manipulating NIFTI volume files. Both CIFTI and GIFTI use components from Nifti.

  • Matrix4x4 (4x4 matrix for viewing and coordinate transformation)
  • NiftiDataTypeEnum (enumerated type for nifti data type)
  • NiftiException
  • NIftiFile (extends BinaryFile, manages NIFTI file data, reads/writes header, extensions, and data. Also allows random access to data).
  • NiftiHeaderExtension (contains bytes and code for an extension)
  • NiftiIntentEnum (enumerated type for nifti intent)
  • NiftiSpacingUnitsEnum (enumerated type for spacing units)
  • NiftiTimeUnitsEnum (enumerated type for nifti time units)
  • NiftiTransformEnum (enumerated type for nifti transform)
  • NiftiUtilities
  • NiftiVersionEnum (enumerated type for nifti version)


This library may be split into OpenGL, OpenGLFixedPipeline, OpenGLProgrammablePipeline

  • BrainOpenGL (performs all OpenGL rendering).

Items below are probably OpenGL independent and can move to Brain:

  • BrainOpenGLDataSelectionManager (Processes raw selection data reported by BrainOpenGL).
  • BrainOpenGLSelectedItemAnnotation
  • BrainOpenGLSelectedItemSurface
  • BrainOpenGLSelectedItemSurfaceBorder
  • BrainOpenGLSelectedItemSurfaceFocus
  • BrainOpenGLSelectedItemSurfaceNode
  • BrainOpenGLSelectedItemSurfaceTriangle
  • BrainOpenGLSelectedItemVolumeBorder
  • BrainOpenGLSelectedItemVolumeFocus
  • BrainOpenGLSelectedItemVoxel


  • PaletteColoringMapping (palette color mapping used by functional volumes, metric, connectivity)
  • PaletteScaleModeEnum (enumerated type for scale mode)
  • PaletteThresholdTestEnum (enumerated type for threshold test)
  • PaletteThresholdTypeEnum (enumerated type for threshold type)


Statistics contains classes for statistical operations on Metric and Shape files.


Xml contains classes for SAX Parsing and writing XML formatted files.

Xml Objects

  • XmlAttributes (Contains attributes for an XML start element).
  • XmlException
  • XmlSaxParser (Abstract class for parsing XML files).
  • XmlSaxParserException
  • XmlSaxParserHandlerInterface (Delegate implemented by objects that read XML files).
  • XmlSaxParserWithQt (Concrete implementation of XmlSaxParser using QT).
  • XmlUtilities
  • XmlWriter (Writes XML files).
Personal tools
Sums Database