3.6. User interfaces
These requirements correspond to Milestone 3 (label O1) NCC5-613.
The purpose of this document is to describe the functional
requirements of the ChomboVis visualization tool, as of milestone O1.
The previous version of ChomboVis was version 2.0, released April 3,
2001. ChomboVis 3 (the subject of this requirements document)
represents further evolution of ChomboVis -- translation from Tcl to
Python, and the addition of numerous new features.
1.3. Grammatical note
Even though these are requirements, for simplicity and readability, I
use the present tense and indicative mood.
2. General Description
2.1. Overall System Concept
ChomboVis is a visualization tool specialized for use on adaptive mesh
refinement (AMR) datasets such as those produced by Chombo. ChomboVis
and Chombo share no code. However, ChomboVis' input data format is
Chombo's output data format.
ChomboVis displays two- and three-dimensional datasets in a
variety of ways, most of them fairly familiar to users of other
visualization tools. See section 3 below for a complete list of
ChomboVis is written in Python and C++. It relies on VTK
(http://www.kitware.com) for most of its visualization algorithms. It
relies on the hdf5 libraries (http://hdf.ncsa.uiuc.edu/ HDF5) for most
I/O. Both VTK and HDF5 are open source software.
2.2. Operating Environment
ChomboVis is known to run on:
- PCs (Pentium III and IV) with Linux (kernels from 2.2 on up).
- SGI Onyx IRIX64 6.5
2.3. High-Level Diagram
The figure at right puts ChomboVis in context. An arrow indicates
that the component at the source of the arrow uses the component to
which the arrow points.
The yellow components are what we ship as ChomboVis. The grey
components are third-party software it is up to the user to obtain.
The pink component at the top -- "user script" -- is optional; it can
be any Python script that uses the ChomboVis API.
2.3.1. Data flows
The next figure
summarizes the data flows. An AMR application (INS or
something else) saves the results of its calculation to a file in HDF5
format. ChomboVis reads that file and produces visualization in two
or three dimensions. Additionally, ChomboVis saves a description of
its own state to a "state file". The second arrow between "ChomboVis"
and "state file" reflects the fact that ChomboVis can also load a
saved state from such a file.
2.4.1. States and modes of execution
ChomboVis can be controlled interactively in two ways -- through the
graphical user interface, and from the Python prompt. ChomboVis also
runs in batch mode; it accepts a Python program from the
command-line's user_script option.
ChomboVis has three visualization modes: it can render to an X
terminal; it can render "off-screen" (and then save the image to a
file); it can be run without any rendering whatsoever (in which case
its functionality is limited to reporting certain data summaries).
2.4.2. Configuration and initialization
ChomboVis configuration involves entering certain site-specific paths
in a file called user.make.
ChomboVis makes no special efforts to exploit parallel computer
2.4.4. File I/O
ChomboVis loads the data it is indended to visualize from a file in
our own specialization of hdf5 format. ChomboVis saves and restores
its own state, to/from ordinary Unix files.
2.4.5. Supported grid types and resolutions
ChomboVis works correctly with cell-centered data only.
ChomboVis can handle an arbitrary number of AMR levels.
2.4.6. External interfaces and language support
ChomboVis comes with a preliminary version of a Python API.
2.4.7. Hardware requirements
For satisfactory ChomboVis performance on small datasets, a PC needs
at least forty megabytes of memory.
2.4.8. Communication requirements
ChomboVis is a standalone program. It engages in no interprocess or
network communication. It has no web interface.
2.4.9. Specific packages, libraries or vendor support
The prerequisites for ChomboVis are Tcl/Tk, Python, HDF5, VTK, OpenGL,
Gnu C++, and the standard Unix text utilities (sh, awk, sed, grep,
The following requirements all share a common priority, and are
available in ChomboVis 3.6, released October 3, 2002.
3.2.1. AMR data for visualization
ChomboVis uses the HDF5 library to read AMR data stored in Chombo
output format (and output there by a program like AMR INS). The
format is described at
ChomboVis can create new data components, and store them back to
an hdf5 file.
ChomboVis does not load the entire dataset (or, in the case of
generated components, compute all the values at once), but rather only
those components at those levels of refinement currently
Ghost cell values, when available, are loaded from HDF5. When not
available there, ghost cell values can be generated.
3.2.2. ChomboVis state
ChomboVis saves (and, later, possibly in another session, restores)
its own state. ChomboVis' state includes the camera viewing position,
the colorization parameters, whether things such as isosurfaces,
slices and grid lines are displayed, which auxiliary dialogs (control
windows) are open, etc. Restoration of ChomboVis' state corresponds
to what the milestones document describes as "session restart
3.3. Visualization techniques
Slices are cross-sections of a 3D dataset. The user can orient a
slice so that it is perpendicular to any of the three coordinate axes,
and placed at any location along that axis.
3.3.2. Grid lines
Lines indicate the outlines of the overall domain, of Chombo boxes,
and of individual cells. The user can choose to display all the
cells, or just the boxes, or just the overall domain, or no outlines
3.3.3. Isosurfaces and isocontours
ChomboVis can display isosurfaces of 3D datasets, and isocontours of
2D datasets. The user is in control of the number of
isosurfaces/contours and the values to which they correspond.
Streamlines are paths of massless particles in a (2D or 3D) vector
field. The user selects the two (or three) components of the field,
the levels of refinement, and the parameters of a rake of seed points.
3.3.5. Volume rendering (preliminary)
The user controls the component to render, the levels of refinement,
and a function that maps from the component's values to opaqueness of
3.3.6. Embedded boundaries
The user selects the particular embedded boundary, when there is more
than one stored in the hdf5 dataset.
When available in the HDF5 file, particles may be viewed. The user
has control over selection of particles, their glyph shapes, sizes and
3.4. Visualization options
3.4.1. Component selection
A typical Chombo hdf5 dataset includes information on more than one
data component. ChomboVis users can select the particular component
whose slices and isosurfaces/contours to display. (Streamlines,
volume rendering and embedded boundaries have their own, independent,
component selection control.)
3.4.2. Level selection
Users can indicate the minimum and maximum levels of refinement to be
reflected in the rendering. A common level control applies to slices,
grids lines, isosurfaces/contours and embedded boundaries.
Streamlines and volume rendering have their own, independent, controls
over visible levels (as well as component). From the Python command
line, it is possible to exert independent control over all
ChomboVis users can select a colormap from a file (see
colormap for the format). Users may, furthermore, choose the
values to associate with the ends of the colormap range. (By default,
those ends are the extremes of the currently displayed component's
Isosurfaces may be colored in three different ways: by a constant
color, by the value of the component whose isosurface is being viewed,
and by the value of any other component. Isocontour coloring includes
only the first two of these modes.
In 3D, the user can clip away grid lines, isosurfaces and embedded
boundaries. The user controls the position and orientation of a
plane; on one side of the plane, nothing is rendered, while on the
other side of the plane, everything is rendered normally.
3.4.5. Camera position and orientation
By means of mouse motions, the user can rotate, zoom and pan the
camera around a 3D dataset. For 2D datasets, only zooming and panning
3.4.6. Off-screen rendering
The image is "rendered" in a memory buffer and not shown on the
screen. The image can, however, be saved to ppm format. Off-screen
mode is useful when producing a large number of related images, for
example when making a movie.
3.5. Data browsing
Using keyboard and mouse, the user can highlight any cell and cause
its coordinates and value (for any component) to appear in a dialog.
To see the cell values in context, a spreadsheet is available to show
all the cell values within a box.
3.6. User interfaces
3.6.1. Graphical user interface
A system of pull-down menus and dialogs enable the user to select from
ChomboVis' visalization techniques, visualization options, and other
features. The graphical user interface is described in more detail at
3.6.2. Command-line options (preliminary)
- -i : leaves Python prompt (>>>) up (analogous to "python -i").
- slice_axis : axis perpendicular to a desired 2D slice
- axis_position : position along slice_axis (required if slice_axis is used)
- ignore_rc : if 1, then don't load .chombovisrc (default=0)
- state_file : saved state of a previous ChomboVis session, loaded
before execution of any user_script.
- user_script : Python script, typical employing the ChomboVis API.
- cmd : Python command to execute
- texture : if 0, then don't use texture mapping (default=1)
- slices_off : if 1, then come up with no slices displayed (default=0)
- off_screen : if 1, then render off-screen, rather than to monitor
- debug_level : 0=nothing, 1=fatal, 2=error, 3=warning, 4=info, 5=trace (default=2)
- --help : prints usage and command-line options summary
3.6.3. Run-time interaction, or API (preliminary)
As mentioned above, starting ChomboVis with the -i
command-line option leaves a Python prompt up on the terminal. Along
with the standard Python libraries, the user has available the
ChomboVis API (documented at
ChomboVis API is suitable for bringing the system to any desired
state, for example setting slice positions, toggling on three
As expected for a Python command-line, entire files of ChomboVis
API commands (i.e. Python programs) may be executed at run-time, by
means of Python's "import" command.