ChomboVis Data API Specification

ChomboVis Data API Specification by Ted Sternberg June 28, 2002 Previous version: April 16, 2003 This version: April 28, 2003

1. Introduction
- 1.1. Conventions
- 1.2. Correspondence to Brian's 'ChomboVis 4.0' document
2. Class ReaderAPI
3. Class VisualizableDataset
- 3.1. Interface
- 3.2. Notes
4. Class BoxLayout
- 4.1. Interface
- 4.2. Notes
5. Class BoxLayoutData
6. Class Box
- 6.1. Interface
7. More examples
1. Introduction
This document describes a proposed extension to that part of the ChomboVis application programming interface that involves data but not necessarily visualization.
ChomboVis already exposes a data API. It falls far short of our full goals for this sort of thing, but everyone should be aware of its existence. Go here and scan down to "class ReaderAPI".
The current ReaderAPI is limited in that it can deal with only one HDF5 dataset at a time. Where we want to go is a ChomboVis that can deal with HDF5 datasets, and subsets of them, as first-class objects. All that remains of class ReaderAPI is those methods that deal with data-specific settings current in the graphics subsystem. All other data operations go into standalone classes called VisualizableDataset, BoxLayoutData and BoxLayout, which are defined in the chombovis module.
1.1. Conventions
Everything here is about a proposed Python API. However, I present class interfaces in C++ style. The reason is that C++ function prototypes and class definitions are more expressive than their Python counterparts. Unlike Python, C++ lets me indicate argument and return value types, and I can say const. But I don't bother with const references; I write function prototypes to take instances of user-defined classes, and in those cases imagine I'm actually passing const references.
I present class definitions without intertextual comments. But a "notes" section comes right afterward. Some readers will not be interested in knowing more than is already apparent from the function prototypes. All the rest will appreciate the lack of clutter, when they come back to this document on second and subsequent reads. Only non-obvious methods are commented.
Wherever it says real, understand that to mean Python's native floating-point type.
Intvect means list in Python.
The classes are presented in a more or less top-down order. This is so the reader sees the most important things first. Therefore, if you see an unfamiliar class mentioned (as a return type or function argument perhaps), it's probably defined further down.
1.2. Correspondence to Brian's 'ChomboVis 4.0' document

1.2.1. Nomenclature
- My VisualizableDataset class corresponds, roughly, to Brian's FileHandle class.
- My BoxLayoutData class corresponds, roughly, to Brian's Scalar class.
1.2.2. Coverage and emphasis
Brian advocated a Python interface autogenerated from the existing Chombo code. Here, the proposal is for an interface custom-made for Python and ChomboVis. Therefore I can't refer you to the Chombo documentation; I spell out all the interfaces right here.
Brian proposed a new visualization feature, a facility to render objects smaller than entire hdf5 datasets. I don't take that up here, as this document is about data, as distinct from rendering. In any case, nothing I propose here rules out that sort of new visualization feature.
I do not take up coarse-fine interpolation.
2. Class ReaderAPI
Class ReaderAPI is a subclass of the ChomboVis class (whose other subclasses -- see http://seesar.lbl.gov/anag/chombo/chomboVis/API.txt -- deal with strictly visualization functionality). Comparing to the current ReaderAPI, the new ReaderAPI can be seen to have given up some of its methods to the VisualizableDataset class. The methods left in ReaderAPI are those specific to the one "active" dataset, that is the one connected up with the VTK pipelines.
A user who is not interested in visualization need have nothing to do with class ReaderAPI; all non-visualization functionality can be found on the other classes (discussed below).
2.1. Interface
```
class ReaderAPI
{
  public:
    // Operations involving entire dataset.
    void          setVTKData( VisualizableDataset );
    VisualizableDataset & getVTKData();

    // Information about the state of the graphics subsystem.
    string      getCurrentComponent()    const;
    pair<real>  getCurrentVisibleRange() const;
    int         getVisibleLevelMin()     const;
    int         getVisibleLevelMax()     const;
    bool        is2DMode()               const;
    bool        isResliceMode()          const;

    // Manipulation of the graphics subsystem.
    void   setCurrentComponent( string name );
    void   setVisibleLevelMin( int level );
    void   setVisibleLevelMax( int level );
    void   showGUI() const;
};
```
2.2. Notes

2.2.1. void setVTKData( VisualizableDataset )
Makes the indicated VisualizableDataset the active one, i.e. the one displayable by ChomboVis' graphics subsystem.
2.2.2. VisualizableDataset & getVTKData()
Access to the dataset active in the graphics subsystem.
2.2.3. string getCurrentComponent() const
Returns the name of the component whose isocontours, slice planes, etc are currently displayable by ChomboVis' graphics subsystem.
Note that even if we move toward a situation where every pipeline (isocontours, slices) can select its component independently (the way volume and streamlines already do), we still will not eliminate this method because there will always be a "default" component to go into those pipelines where another component was not selected explicitly.
2.2.4. pair getCurrentVisibleRange() const
Returns the low and high value for the current component at its currently visible levels.
2.2.5. int getVisibleLevelMin|Max() const
Returns the minimum (maximum) levels of data displayed.
2.2.6. int is2DMode() const
Returns 1 if the dataset is intrinsically 2D, or if ChomboVis' graphics subsystem is in reslice mode.
2.2.7. showGUI() const
Pops up the data control dialog.
2.3. Example
Here is a program that causes the graphics subsystem to display all levels of a loaded dataset.
```
import chombovis
c = chombovis.this()           # Obtains active instance of class ChomboVis.
hdf5data = c.reader.getVTKData() # c.reader is the instance of class ReaderAPI.
c.reader.setVisibleLevelMin( 0 )
c.reader.setVisibleLevelMax( hdf5data.getNumLevels() - 1 ) # See VisualizableDataset.
```
3. Class VisualizableDataset
An VisualizableDataset represents the entire contents of a Chombo hdf5 file, and it is the object that can be passed to ChomboVis' graphics subsystem, for display.
At this writing, a class like the proposed VisualizableDataset exists in ChomboVis' C++ layer (see pyChomboVis/utils/ChomboHDF5.h|cpp). The proposal here is to give this class a presence at the Python layer.
3.1. Interface
```
class VisualizableDataset
{
  public:
    VisualizableDataset( string infile_name );
    VisualizableDataset( vector<vector<BoxLayoutData> > );
    VisualizableDataset( vector<BoxLayoutData> );
    VisualizableDataset( BoxLayoutData );

    // Accessors for global data.
    int       getDimensionality()                      const;
    string    getComponentName( int component_num )    const;
    vector getComponentNames()                 const;
    int       getComponentNum( string component_name ) const;
    int       getNumLevels()                           const;
    int       getNumComponents()                       const;

    // Accessors for by-level data.
    Box              getProbDomain( int level )           const;
    Realvect         getDx( int level )                   const;
    Realvect         getOrigin()                          const;
    Intvect          getOutputGhost( int level )          const;
    int              getNumBoxes( int level )             const;
    BoxLayout        getBoxes( int level )                const;
    BoxLayoutData const & getData(  int level, string component ) const;

    // I/O
    void write( string outfile_name );

    // Data creation.
    VisualizableDataset make2DSlice( char axis, real axis_position,
                             int min_level, int max_level ) const;
    void defineNewComponent( string new_component_name,
                             real (*function)(vector<real>),
                             vector<string> arg_component_names );
    void defineNewComponent( string new_component_name,
                             real (*function)(vector<real>),
                             vector<int> arg_component_numbers );
    void importNewComponent( string new_component_name,
                             VisualizableDataset other_dataset,
                             string component_name_in_other_dataset );
};
```
3.2. Notes

3.2.1. VisualizableDataset( string infile_name )
Constructs from an hdf5 file in Chombo format.
3.2.2. VisualizableDataset( vector > )
The argument is by level, by component.
The argument is not copied, unless and until this instance of VisualizableDataset is left holding the only reference to it, or we modify it.
3.2.3. VisualizableDataset( vector )
The argument is by component (and represents the data of a single level).
The argument is not copied, unless and until this instance of VisualizableDataset is left holding the only reference to it, or we modify it.
3.2.4. VisualizableDataset( BoxLayoutData )
The argument contains data for a single component on a single level.
The argument is not copied, unless and until this instance of VisualizableDataset is left holding the only reference to it, or we modify it.
3.2.5. getDx()
Returns a triple -- dx, dy, dz.
3.2.6. getOrigin()
No matter what the data centering, the origin is the spatial location of the lower corner of the [0,0,0] cell.
3.2.7. getBoxes()
Returns all the boxes at the indicated level.
3.2.8. getData()
Class BoxLayoutData (see below) can hold only scalar-valued data.
3.2.9. void write( string outfile_name )
Creates an hdf5 file in Chombo format.
3.2.10. VisualizableDataset make2DSlice(...) const
Returns a new VisualizableDataset that is a slice of this dataset at the indicated position and covering the indicated range of levels.
The box numbering is not preserved; the new, two-dimensional VisualizableDataset's boxes are numbered in order 0, 1, 2, ....
3.2.11. void defineNewComponent(...)
Creates a new data component. The function argument is a Python function that describes how to calculate every cell value of the new component, from corresponding cell values of the existing components enumerated in the arg_component_names argument. New data not generated at the time this function is called, but rather as needed by-level by-box.
The new component's status becomes equal in every way to that of the existing components: the graphics subsystem can display the new component; write() dumps it to file along with all the other components; getData() can return the new data; etc.
The box numbering is preserved.
Example:
```
import chombovis
c = chombovis.this()        # Obtains the active ChomboVis instance.
hdf5_data = c.reader.getVTKData() # c.reader is the instance of class ReaderAPI.

def norm( x, y ): return pow( x*x + y*y, 0.5 )
hdf5_data.defineNewComponent( 'momentum_norm', norm,
                              ('momentum_x', 'momentum_y') )
```
3.2.12. void importNewComponent(...)
Like defineNewComponent(), this creates a new data component. But rather than than computing new values, this function just takes a component from another VisualizableDataset.
The two VisualizableDatasets' BoxLayoutData's must be identical -- same number of levels, same number of boxes, of the same size, at the same locations.
No data is actually copied unless and until the other VisualizableDataset is deleted. Until then, the calling instance of VisualizableDataset just creates a pointer to the data in the other VisualizableDataset.
The box numbering is preserved.
Example: Here is how we would augment one VisualizableDataset by all the components of another.
```
import chombovis
c = chombovis.this()
data1 = VisualizableDataset( 'greg01.hdf5' )
data2 = VisualizableDataset( 'greg02.hdf5' )
for i in range(0, data2.getNumComponents()):
    data1.importNewComponent( 'new'+str(i), data2, data2.getComponentName(i) )
```
4. Class BoxLayout
Although I'm using an official Chombo BoxTools term, a BoxLayout here is little more than a collection of nonintersecting boxes. There is no notion of allocation to processors, nor do we care if the boxes are disjoint.
4.1. Interface
```
class BoxLayout
{
  public:
    BoxLayout();
    BoxLayout( vector<Box> );

    int getNumBoxes() const;
    Box getBox( int ) const;

    Intvect getDx() const;
};

BoxLayout union( vector<BoxLayout> );
BoxLayout intersection( vector<BoxLayout> );
BoxLayout difference( pair<BoxLayout> );
```
4.2. Notes

4.2.1. BoxLayout() and BoxLayout( vector<Box> )
Constructors. With no argument, we obtain a BoxLayout with no boxes in it. I expect that users will obtain new BoxLayouts mostly from other methods -- set algebra, BoxLayoutData::GetBoxes(), etc.
4.2.2. getDx()
Returns a triple -- dx, dy, dz.
4.2.3. union, intersection, difference
Set algebra. The argument to union() and intersection() is an arbitrary number of BoxLayouts (in Python that means a list). The two or more BoxLayout arguments must be made up of Boxes that are either identical or distinct; if A and B are BoxLayouts, then for every Box a in A and every Box b in B, either a is identical to b, or they touch along a common edge, or their intersection is the null set.
The return values are new BoxLayouts.
5. Class BoxLayoutData
This is a BoxLayout plus cell data. Cell data can be only scalar-valued.
5.1. Interface
```
class BoxLayoutData
{
  public:
    BoxLayoutData( BoxLayout );

    int copyTo();
    int exchange();
    Intvect getGhost( int level ) const;
    void    setGhost( Intvect );

    int  getCentering() const;
    void setCentering( int );

    void crop( BoxLayout );
    
    void clamp( BoxLayout );
    void clamp( real lo, real hi );
    void unclamp()

    void setDatum( int box_num, Intvect coordinates, real value );
    real getDatum( int box_num, Intvect coordinates ) const;

    real const * getFArray( int box_num ) const;

    BoxLayout const & getBoxes() const;
    int getDimensionality() const;

    real getMin() const;
    real getMax() const;
    real getQuantile( real ) const;
    real getSum() const;
    real getSumSqr() const;
    real getNumCells() const;

    [In-place versions of operators below, e.g. +=, -=, etc.]
};

BoxLayoutData crop( BoxLayoutData, BoxLayout );

BoxLayoutData operator+( BoxLayoutData, real );
BoxLayoutData operator+( BoxLayoutData, BoxLayoutData );
BoxLayoutData operator-( BoxLayoutData, real );
BoxLayoutData operator-( real, BoxLayoutData );
BoxLayoutData operator-( BoxLayoutData, BoxLayoutData );
BoxLayoutData operator*( BoxLayoutData, real );
BoxLayoutData operator*( BoxLayoutData, BoxLayoutData );
BoxLayoutData operator/( BoxLayoutData, real );
BoxLayoutData operator/( real, BoxLayoutData );
BoxLayoutData operator/( BoxLayoutData, BoxLayoutData );
BoxLayoutData exp( BoxLayoutData );
BoxLayoutData log( BoxLayoutData );
BoxLayoutData sin( BoxLayoutData );
BoxLayoutData cos( BoxLayoutData );
BoxLayoutData tan( BoxLayoutData );
BoxLayoutData asin( BoxLayoutData );
BoxLayoutData acos( BoxLayoutData );
BoxLayoutData atan( BoxLayoutData );
BoxLayoutData abs( BoxLayoutData );
BoxLayoutData pow( BoxLayoutData, real );
BoxLayoutData pow( real, BoxLayoutData );
```
5.2. Notes

5.2.1. BoxLayoutData( BoxLayout )
This constructor leaves all the cell values at None. This is how one would build a BoxLayoutData from scratch. I anticipate that the more common way of obtaining a BoxLayoutData will be from VisualizableDataset::getData().
5.2.2. copyTo() and exchange()
These operations generate ghost cells. The integers both functions return is a status code. 0 means OK. 1 means the box layout is not disjoint.
All the existing data gets copied; this can be an expensive operation.
The box numbering is preserved.
5.2.3. crop()
The member-function version of crop() discards all boxes (or parts of boxes) outside the interior of the BoxLayout argument. The free-function version does not modify its arguments, instead returning a new -- cropped -- BoxLayoutData instance.
The box numbering is preserved as long as no boxes end up entirely outside the cropped zone. Otherwise, the box numbering is not preserved.
5.2.4. clamp() and unclamp()
The clamp( BoxLayout ) version acts as a sort of reversible crop(). Following the call to clamp(), and until the next call to unclamp(), all regions outside the BoxLayout argument are invisible to all other methods.
The clamp(real lo, real hi) version makes all cells whose values fall outside the indicated range "invisible" to the reduction methods getMin(), getMax(), etc.
The box numbering is preserved.
5.2.5. getDatum() and setDatum()
Access to individual values.
5.2.6. getBoxes()
Returns a constant reference to this object's associated BoxLayout.
5.2.7. getDimensionality()
Returns the number of spatial dimensions, of which we can handle an arbitrary number.
5.2.8. getMin(), etc.
These reduction operators return the minimum and maximum cell values, the sum and sum of squares of the cell values, and the number of cells in the entire BoxLayoutData or, if clamp() is in effect, a subset of it. getQuantile(real p) returns the smallest cell value that is greater than 100p% of all the cell values.
5.2.9. Pointwise operators and functions (operator+, exp, log, etc)
These functions operate cell-by-cell. For example, operator+ adds the indicated real to every cell of the indicated BoxLayoutData, returning a BoxLayoutData of the same size as the one passed in the argument. The operators that take two BoxLayoutData arguments require that those BoxLayoutDatas match up cell for cell; their associated BoxLayouts must be equal, i.e. the set difference of their BoxLayouts, taken in either order, must be the empty set.
The in-place versions modify all the data. The global versions create new BoxLayoutData instances.
If you need an operation not listed here, use VisualizableDataset::defineNewComponent() followed by VisualizableDataset::getData(). In fact, defineNewComponent() is advisable for efficiency reasons, whenever you need to do something that involves the composition of more than a few operations, and your BoxLayoutData object is close to an entire VisualizableDataset level in size. This is because the pointwise operators and functions construct a new BoxLayoutData on each invocation, whereas VisualizableDataset::defineNewComponent() does not create even one BoxLayoutData (until you call getData(), and that creates a single BoxLayoutData).
5.3. Example
Here is a program that loads an hdf5 file and prints the data range of all its components. The program uses methods from several of the classes discussed above.
```
import chombovis
data = chombovis.VisualizableDataset( 'vortex.3d.hdf5' )
n_levels = data.getNumLevels()
for i in range( 0, data.getNumComponents() ):
    comp_name = data.getComponentName( i )
    lo, hi = 10E5000, -10E5000
    for l in range( 0, n_levels ):
        boxdata = data.getData( l, comp_name )
        lo = min( lo, boxdata.getMin() )
        hi = max( hi, boxdata.getMax() )
    print "range of", comp_name, "=", [lo,hi]
```
6. Class Box

6.1. Interface
```
class Box
{
  public:
    Box( Intvect lo_corner, Intvect hi_corner );
    Intvect getLoCorner() const;
    Intvect getHiCorner() const;
};
```
7. More examples
Now that I've introduced all the classes, here are some more code examples. I'd like to encourage everyone to submit requests for other examples; the process of writing them will help identify important missing or ill-specified functionality.
7.1. Average value on a disk
```
def findAverageOnDisk( a_hdf5, a_component, a_level,
                       a_center, a_radius ):
    """
    Return the average cell value over all boxes that intersect
    the disk of specified center and radius (in units of dx).

    Input data must be 2D.

    Arg a_hdf5 can be either the name of a file, or an VisualizableDataset instance.
    """

    if   type(a_hdf5) == type('string'):
        hdf5 = chombovis.VisualizableDataset( a_hdf5 )
    elif isinstance( a_hdf5, chombovis.VisualizableDataset ):
        hdf5 = a_hdf5
    else:
        assert(0)
    assert( hdf5.getDimensionality() == 2 )

    all_boxes = hdf5.getBoxes()
    dx = hdf5.getDx( a_level )
    boxes_on_disk = []

    for b in range( 0, all_boxes.getNumBoxes() ):
        box = all_boxes.getBox( b )

        x_lo, y_lo = box.getLoCorner()[0]*dx, box.getLoCorner()[1]*dx
        x_hi, y_hi = box.getHiCorner()[0]*dx, box.getHiCorner()[1]*dx
        radius_sqr = pow(a_radius*dx, 2)
        
        corner_status = (  # 1 if corner is inside disk.
            (  pow(x_lo - a_center[0]*dx, 2) + pow(y_lo - a_center[1]*dx, 2 )
                < radius_sqr ),
            (  pow(x_lo - a_center[0]*dx, 2) + pow(y_hi - a_center[1]*dx, 2 )
                < radius_sqr ),
            (  pow(x_hi - a_center[0]*dx, 2) + pow(y_lo - a_center[1]*dx, 2 )
                < radius_sqr ),
            (  pow(x_hi - a_center[0]*dx, 2) + pow(y_hi - a_center[1]*dx, 2 )
                < radius_sqr ) )
        # Can replace "or" with "and", to define "within disk" more strictly:
        if reduce( lambda corner1, corner2: corner1 or corner2, corner_status ):
            boxes_on_disk.append( box )

    boxdata = hdf5.getData( a_level, a_component )
    boxdata.clamp( chombovis.BoxLayout( boxes_on_disk ) )

    return boxdata.getSum() / boxdata.getNumCells()
```
7.2. Same, with GUI control
With a little more work, this function can be the core of a little interactive widget with a scale for the disk radius.
```
def diskAverageGUI( a_component, a_level, a_center ):
    """
    GUI over findAverageOnDisk().
    Intended for invocation at the Python prompt of a running ChomboVis.
    """

    # Grab the dataset currently loaded by the graphics subsystem.
    hdf5 = c.reader.getVTKData()
    
    # Open a root Tk window.
    root = Tkinter.Tk()

    # Create a scale widget for controlling the radius.
    max_radius = pow( pow(hdf5.getProbDomain().getHiCorner()[0] -
                          hdf5.getProbDomain().getLoCorner()[0], 2.0)
                    + pow(hdf5.getProbDomain().getHiCorner()[1] -
                          hdf5.getProbDomain().getLoCorner()[1], 2.0),
                    0.5 )
    def scaleHandler( radius ):
        print findAverageOnDisk( hdf5, a_component, a_level, a_center,
                                 radius )
    scale = Tkinter.Scale( root, from = 0.0, to = max_radius,
                           command = scaleHandler )

    # Label and pack.
    Tkinter.Label( root, text="Radius:" ).pack()
    scale.pack()
```
7.3. Sample interactive session
Here is what an interactive session with the ChomboVis data API might look like. The $ is the Unix shell's prompt. The >>> string is the Python interpreter's prompt. The above functions findAverageOnDisk() and diskAverageGUI are assumed to be defined in a file myutils.py.
```
$ chombovis infile=data/ebtest.2d.hdf5
>>> import chombovis
>>> hdf5_data = c.reader.getVTKData()
>>> def normFunc( x, y ): return pow( x*x + y*y, 0.5 )
>>> defineNewComponent( 'norm', normFunc, ('xnormal-0','ynormal-0'))
>>> print hdf5_data.getData( level=0, component='norm' ).getMin()
0.0478249110
>>> print hdf5_data.getData( level=0, component='norm' ).getMax()
0.0706233977
>>> print c.reader.getDomainBounds()
{'z': (0.0, 0.03125), 'x': (0.0, 1.0), 'y': (0.0, 1.0)}
>>> import myutils
>>> myutils.diskAverageGUI( 'norm', a_level=0, a_center=(0.5,0.5) )
>>> hdf5_data.write( 'eb_with_norm.2d.hdf5' )
>>> ^d
$
```

1. Introduction

1.1. Conventions

1.2. Correspondence to Brian's 'ChomboVis 4.0' document

1.2.1. Nomenclature

1.2.2. Coverage and emphasis

2. Class ReaderAPI

2.1. Interface

2.2. Notes

2.2.1. void setVTKData( VisualizableDataset )

2.2.2. VisualizableDataset & getVTKData()

2.2.3. string getCurrentComponent() const

2.2.4. pair getCurrentVisibleRange() const

2.2.5. int getVisibleLevelMin|Max() const

2.2.6. int is2DMode() const

2.2.7. showGUI() const

2.3. Example

3. Class VisualizableDataset

3.1. Interface

3.2. Notes

3.2.1. VisualizableDataset( string infile_name )

3.2.2. VisualizableDataset( vector > )

3.2.3. VisualizableDataset( vector )

3.2.4. VisualizableDataset( BoxLayoutData )

3.2.5. getDx()

3.2.6. getOrigin()

3.2.7. getBoxes()

3.2.8. getData()

3.2.9. void write( string outfile_name )

3.2.10. VisualizableDataset make2DSlice(...) const

3.2.11. void defineNewComponent(...)

3.2.12. void importNewComponent(...)

4. Class BoxLayout

4.1. Interface

4.2. Notes

4.2.1. BoxLayout() and BoxLayout( vector<Box> )

4.2.2. getDx()

4.2.3. union, intersection, difference

5. Class BoxLayoutData

5.1. Interface

5.2. Notes

5.2.1. BoxLayoutData( BoxLayout )

5.2.2. copyTo() and exchange()

5.2.3. crop()

5.2.4. clamp() and unclamp()

5.2.5. getDatum() and setDatum()

5.2.6. getBoxes()

5.2.7. getDimensionality()

5.2.8. getMin(), etc.

5.2.9. Pointwise operators and functions (operator+, exp, log, etc)

5.3. Example

6. Class Box

6.1. Interface

7. More examples

7.1. Average value on a disk

7.2. Same, with GUI control

7.3. Sample interactive session

2.2.1. `void setVTKData( VisualizableDataset )`

2.2.2. `VisualizableDataset & getVTKData()`

2.2.3. `string getCurrentComponent() const`

2.2.4. `pair getCurrentVisibleRange() const`

2.2.5. `int getVisibleLevelMin|Max() const`

2.2.6. `int is2DMode() const`

2.2.7. `showGUI() const`

3.2.1. `VisualizableDataset( string infile_name )`

3.2.2. `VisualizableDataset( vector > )`

3.2.3. `VisualizableDataset( vector )`

3.2.4. `VisualizableDataset( BoxLayoutData )`

3.2.5. `getDx()`

3.2.6. `getOrigin()`

3.2.7. `getBoxes()`

3.2.8. `getData()`

3.2.9. `void write( string outfile_name )`

3.2.10. `VisualizableDataset make2DSlice(...) const`

3.2.11. `void defineNewComponent(...)`

3.2.12. `void importNewComponent(...)`

4.2.1. `BoxLayout() and BoxLayout( vector<Box> )`

4.2.2. `getDx()`

4.2.3. `union, intersection, difference`

5.2.1. `BoxLayoutData( BoxLayout )`

5.2.2. `copyTo() and exchange()`

5.2.3. `crop()`

5.2.4. `clamp() and unclamp()`

5.2.5. `getDatum() and setDatum()`

5.2.6. `getBoxes()`

5.2.7. `getDimensionality()`

5.2.8. `getMin(), etc.`