- 2.1. Overall System Concept
- 2.2. Operating Environment
- 2.3. High-Level Diagram
- 2.4. Miscellaneous
- 2.4.1. States and modes of execution
- 2.4.2. Configuration and initialization
- 2.4.3. Parallelization
- 2.4.4. File I/O
- 2.4.5. Supported grid types and resolutions
- 2.4.6. External interfaces and language support
- 2.4.7. Hardware requirements
- 2.4.8. Communication requirements
- 2.4.9. Specific packages, libraries or vendor support
- 3.1. Generalities
- 3.2. I/O
- 3.3. Visualization techniques
- 3.4. Visualization options
- 3.5. Data browsing
- 3.6. User interfaces
- 3.6.1. Graphical user interface
- 3.6.2. Command-line options (preliminary)
- 3.6.3. Run-time interaction, or API (preliminary)
1. Introduction
These requirements correspond to Milestone 3 (label O1) NCC5-613.1.1. Purpose
The purpose of this document is to describe the functional requirements of the ChomboVis visualization tool, as of milestone O1.1.2. Overview
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' capabilities.
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. Miscellaneous
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.2.4.3. Parallelization
ChomboVis makes no special efforts to exploit parallel computer hardware.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, tr).3. Requirements
3.1. Generalities
The following requirements all share a common priority, and are available in ChomboVis 3.6, released October 3, 2002.3.2. I/O
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 http://seesar.lbl.gov/anag/chombo/chomboVis/File_format.html.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 being displayed.
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 capability".3.3. Visualization techniques
3.3.1. Slices
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 at all.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.3.3.4. Streamlines
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 the rendering.3.3.6. Embedded boundaries
The user selects the particular embedded boundary, when there is more than one stored in the hdf5 dataset.3.3.7. Particles
When available in the HDF5 file, particles may be viewed. The user has control over selection of particles, their glyph shapes, sizes and orientations.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 visualization pipelines.3.4.3. Coloring
ChomboVis users can select a colormap from a file (see http://seesar.lbl.gov/anag/chombo/chomboVis/Visualization.html#3.2. User 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 values.)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.
3.4.4. Clipping
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 are possible.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 http://seesar.lbl.gov/anag/chombo/chomboVis/Menus.html3.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 http://seesar.lbl.gov/anag/chombo/chomboVis/chombovis.html). The ChomboVis API is suitable for bringing the system to any desired state, for example setting slice positions, toggling on three isosurfaces, etc.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.