This is the tutorial of VisAD, a Java Component Library for interactive analysis
and visualization of numerical data. We will start by describing
how to write a simple VisAD program to visualize some points as a single
line and will, in section 2, continuously extend the program to show how
to use some VisAD features. In section 3 we will turn our attention to
2-D Sets, which are the basis of images and 3-D surfaces.
VisAD's Displays classes help you to construct displays of those data. These may be 2-D or 3-D, they may be animated, and they may be interactive.
VisAD defines classes for computational Cells that can also be linked to Data objects via DataReference objects (see below). Like Displays, Cells are updated whenever values of linked Data change. Cells take their name from spread sheet cells, because of the way spread sheet cells update when input values change.
VisAD also defines a variety of classes for User Interface objects. Many of these are based on the Java Swing® user interface toolkit, and they can all be easily embedded in a Swing GUI (Display objects are also easily embedded in Swing GUIs). The VisAD user interface classes are designed to help you design user interfaces for interactive control of VisAD Displays.
VisAD also provides a helper class, called DataReference, that is used for linking a Data object to a Display object. Once Data are linked to a Display object, the display will update whenever Data values change. In fact, Displays and Cells both extend Action, the general class for objects whose actions are triggered by changing Data values.
To summarize, VisAD applications are constructed with the following objects:
The VisAD data model defines a set of classes that can be used to build any hierachical numerical data structure. These complex hierarchical Data objects reflect the structure of the actual data. The primitive Data classes are the subclasses of Scalar: Real and Text, which contain a Java double and a text string, respectively. Data structure is achieved by using Tuple, Set and Function classes and their subclasses.
All Data objects have a MathType, which indicates the type of mathematical object that it approximates. Examples of MathTypes are: ScalarType (and its subclasses RealType or TextType), TupleType (and its subclass RealTupleType), SetType, and FunctionType.
Subclasses of Data are Scalar, Tuple, Set and Function. Subclasses of MathType are ScalarType, TupleType, SetType, and FunctionType. In a sense, the Data hierarchy reflects that of MathType.
Most applications include large Data objects that define some RealTypes as functions of other RealTypes. The starting point for any new application of VisAD is the definition of a set of MathTypes. For example, a simple function such as height = f(time), where time and height are RealTypes, is denoted in the VisAD documentation as
and is defined with the FunctionType ( time -> height ). (Remeber: FunctionType is a subclass of MathType.)( time -> height )
A more complex data structure, like that of an image, might be defined with the MathType:
The output of a weather model may be described using the MathType:( ( row, column ) -> ( red, green, blue ) )
( time -> ( (latitude, longitude, altitude) -> (temperature, pressure, dew_point, wind_u, wind_v, wind _w ) ) )
So we move on to talk about a few aspects to consider when designing a VisAD application.
Let us assume we have some data, and we want to build a VisAD application to visualize those data. For example, we have a cube, and we have calculated and/or measured the temperature inside it. So let us consider the above steps in more detail.
This is the first and most important step in designing a VisAD application. Although the display and its objects define to a great extent how data is to be drawn, the depiction also depends on the data structure. You might, for example, create a data structure, a MathType, to draw a one-dimensional function as a line:
and then force the display to draw the individual points, rather than to connect them to make a line. On the other hand, your MathType might describe a set of (x,y) points indexed by some variable, or in VisAD notation:(x -> y)
With the MathType above you're saying, that you have a set of disconnected points. In this case, there is no way to force the display to connect the points. You'd have to create a new MathType.( index -> (x,y) )
The Domain
The first step in creating data with VisAD Data Objects is to identify the basic quantities, or scalars. For example, if we have a cube, we identify three scalars: height, width and length. In VisAD, those would be ScalarTypes. As you know, ScalarTypes has two subclasses: RealType and TextType. The latter is for use with text, whereas the former is for use with "real" numbers ("real" in mathematical sense). So our three cube dimensions are RealTypes. RealTypes are static within a VisAD application. That means in practice, you can reuse them without the need to recreate them. They are generally constructed with a Java String, that is, their name, and with a VisAD unit. The units will be considered, for example, in calculations. Say, to create a RealType h, for "height", you do:
RealType height = RealType.getRealType("Height");RealType height = RealType.getRealType("Height", SI.meter, null);So we have identified our cube dimensions as RealTypes. Together, the three of them form a tuple, or, in VisAD, a RealTupleType. There are many ways to create a RealTupleType, and we are going to come across them later on in the tutorial. For now it suffices to say that we have created the basic "cube structure" with:
RealTupleType cubeTuple = new RealTupleType( height, width, length);
But what about the cube itself? How big is it? To answer these questions we have to know "how" you're defining your cube. Are you measuring height, width and length at constant intervals or not? Are you measuring the vertices only, or are you measuring some random points inside the cube? VisAD has a collection of data objects, Sets, to represent different kinds of samplings. We assume our cube is 1 meter high, 2 meters wide and 3 meters long. Furthermore we assume we measure height and width every 10 cm, but, for lazyness' sake, we measure length every 50 cm, only. And for freedom's sake, we decide to put the cube's width in the middle of our reference system. That is, the extreme values for the width are -1 and 1. (OK, to be precise about it, it's a parallelepiped rather than a cube, but let's call it "cube"). All this information, together with the tuple of the cube dimensions, are defined in a three-dimensional Set:
cubeSet = new Linear3DSet(cubeTuple, // basic quantities given by height, width and length
0.0, 1.0, 11, // height starts at 0.0 m, ends at 1.0 m, and has 11 samples
-1.0, 1.0, 21, // width starts at -1.0 m, ends at 1.0 m, and has 21 samples
0.0, 3.0, 7 ); // length starts at 0.0 m, ends at 3.0 m, and has 7 samples, one value every 50 cm
The word "Linear" means that sampling is regular. If the sampling is regular, and they occur at integer values, say, from 0 to N, than consider using an "Integer" set. If you were to sample the cube in a grid whose points are not regularly spaced, but they nevertheless form a grid, than you'd use a "Gridded" Set, and provide the Set with the individual height, width and length values. Should you know nothing about the topology of your sampling, that is, whether they form a grid or whether they are just randomly spread inside the cube, than you might want to use an "Irregular" Set, and let VisAD figure the topology out. you may have already guessed, that VisAD has 1-D and 2-D, as well an N-D and other Sets. Please refer to the VisAD Java Component Library Developers Guide for more details.
The Range
Ok, we've already got some data, and we could create a display and add the cube to it. But most certainly you are trying to visualize how some quantity (or quantities), a RealType (or a RealTupleType) vary according to some other quantity. Like in maths, you have one or more dependent variables as functions of independent variables. What we do in VisAD is precisely that. We create the independent variable(s), create the dependent variable(s) and then use an object to establish the mathematical function between them. In VisAD one often refers to the independent variables as "domain" and to the dependent variables as "range". So far, we've created the domain. Our domain is the cube given by the RealTupleType and its set is the Linear3DSet, which we call "domain set". So what about the range? We assume we are measuring the temperature inside the cube. We need to create the corresponding RealType:
RealType temperature = new RealType("Temperature");
cubeTempFunc = new FunctionType(cubeTuple, temperature);
That is, "temperature" is a function of height, width and length. You create a FunctionType with two MathTypes (remember, MathType is the superclass of RealTupleType, RealTupleType, FunctionType, etc). The first MathType is the domain, and the second, the range.
The FunctionType creates the relation between the MathTypes of the domain and the range, but it says nothing about "the data" itself. Furthermore, how do you link the cube given by the Linear3DSet, with the function given by the FunctionType, and those with the "temperature" values, which you are measuring and/or computing? The answer is a Field object, or more especifically a FlatField.
A FlatField is a subclass of Field, which is a subclass of Function (but not of FunctionType!), which is a subclass of Data, and thus a Visad data object. A Field represents a mathematical function. Inside it there's information about the domain, the domain set, the range and the range values. A FlatField is an extension of Field, and has been designed with computational efficiency in mind. Inside a FlatField you pack the FunctionType, the domain Set and then you "feed" it with with range ("temperature") values. The FlatField has quite a few useful methods and in the first few tutorial chapters we're going to make good use of it.
A FlatField is created with
FlatField tempInCube_ff = new FlatField( cubeTempFunc, cubeSet)
That is, the first parameter is the FunctionType and the second parameter is the domain Set. We have called our FlatField tempInCubeFF, note the "ff" at the end to denote its type. Of course, you don't need to do so, but it'll be done throughout this tutorial. As said, the FlatField holds not only the "temperature" values you'll provide, it also includes the FunctionType, with its domain and range types, and the domain Set. That is, quite a few things to fit in a short name, so therefore the "ff" at the end. In the tutorial, whenever you come across an object with "ff" at the end, remember, it's a FlatField and expect a lot from it.
Well, we are almost done with the creation of a not-so-simple data object. The only two things missing is to feed the FlatField with actual "temperature" values and to add the whole data to a display. Note that the FlatField above will be waiting for an array of floats (or doubles) with the shape float[ range_dimension ][ number_of_samples ]. The first dimension corresponds to the dimension of the range, in our case it's 1, as we have "temperature", only. The second dimension is the total number of temperature values, which is 10 x 20 x 6, as given by the domain Set. You'd set the values with a call
FlatField.setSamples( float[][] temperValues );
Now we've got some complex data ready to be displayed, so we move on to consider the display of data.
The first question you might ask yourself is whether to use of a 2D or of a 3D display. Luckily, in VisAD the choice of display is independent of the data. Whether it makes sense to use a 2D or 3D is up to you to decide. There are a variety of displays constructors and display renderers. In the tutorial, we will come across some of them. For now it's important to understand how VisAD displays data.
When building up the data structure, we identified basic quantities as RealTypes. When thinking of the cube of the previous example, it would be obvious to map each one of the dimensions to an axis of a 3D display. The object responsible for the mapping is a ScalarMap. When creating a ScalarMap you consider two things: 1. Which ScalarType will you map and 2. Where will you map it to. The first point is clear, but remember that ScalarType is the superclass of RealType and of TextType. The "where will you map it to" implies not only the axes of a display, but also color, animation, iso-contours, text, shape and many others. These are known in VisAD as DisplayRealTypes, and they define how RealTypes are to be displayed. Let us look closer at such a ScalarMap by constructing a few:
ScalarMap heightZMap = new ScalarMap( height, Display.ZAxis ); ScalarMap widthXMap = new ScalarMap( width, Display.XAxis ); ScalarMap lengthYMap = new ScalarMap( length, Display.YAxis );
This should be pretty clear: we are mapping "height" to the z-axis, width to the x-axis and length to the y-axis. We haven't said anything yet about the display. If the display has such a map, then it'll map "height" data to the z-axis. Suppose we do the same for the other cube dimensions, then we have the whole cube in a 3D display.
To color the cube according to temperature values, you'd do
ScalarMap temperRgbMap = new ScalarMap( temperature, Display.RGB );
and you'd obtain a cube colored according to the "temperature" values. (The actual color table is predefined, but you can redefine it. See Section 4 for some examples of colored cubes und user-defined color-tables.)
ScalarMaps have a boring but helpful relative, the ConstantMaps. ConstantMaps extend ScalarMaps, but take no ScalarType as a parameter in the constructor. Instead, they take a (constant) Java double or a VisAD Real (Real is a subclass of Data). With a ConstantMap map you may add a constant shade of red, say 40%, to a display:
ConstantMap constRedMap = new ScalarMap( 0.4, Display.Red );
or you can put some data at some constant place in a display and/or give it a constant color. For example, you could give a constant green color to a line, or put a surface at some z-value.
After choosing how to depict your data by choosing the right types of ScalarMaps and ConstantMaps, you add them to the display (you will see in the next section how this is done).
Having added all ScalarMaps of your choice, you have to tell the display which data to draw. For that, you use a DataReference. You feed a DataReference with the data you want, like, for example, with a FlatField, and then you add the DataReference to the display. At this step, you might add the data with an array of ConstantMaps, to give your data some different properties.
This step might not seem so important as the previous two, but, in fact, you only reach the desired usability of your application with a proper user interface. Apart from the standard Java UI, which you can use in your application, VisAD provides a number of special UIs. Interaction in VisAD generally occurs with the help of a Control. Control is a class which is implemented by GraphicsModeControl, ColorControl, AnimationControl and others. In particular, you'll find that most VisAD Controls have a corresponding UI. The choice of UIs depends not only on your data, but also on how interactive your application can and should be. One thing to notice, though, is that in VisAD the display is the main user interface. Not only does it provide the user with information about the data, but it supports interactive rotation, pan and zoom. It can also have, for example, DirectManipulationRenderers, so that user input occurs directly through the display. By using widgets not only can you change data depiction, but you can also change data values. This might trigger calculations, which, in turn, might change data. As we move along the tutorial, we'll get to know the VisAD widgets.
Before we start with our first VisAD application, we recap the main steps. When building the data structure, identify the basic quantities as ScalarTypes, that is RealTypes or TextTypes. Pack RealTypes in a RealTupleType. Use a Set (1D, 2D, 3D or N-D and Linear, Gridded, Integer, Irregular or other) as the domain Set. Build the range with the RealTypes identified as the independent variables. If there are more than one RealType, create a RealTupleType for the range. Create a FunctionType with the domain and the range. Create a FlatField based on the function and on the domain set. Put the range values in the FlatField.
For visualization, start with a display. Create the ScalarMaps you find necessary and add them to the display. Create a DataReference, feed it with data, add it to display. The display will be added to a Java Frame or other Java Component to be shown.
Use Controls to set parameters and customize your display. Refine your application with widgets.
We are then ready to write our first VisAD application, which will have a very simple MathType (just a RealType, called height, as a function of the RealType time, that is a FunctionType ( time -> height )), as well as a Field and a Set, a DataReference and a Display.
We assume time to be our independent variable and are given some values for height. We define time and height as RealTypes. Data for time is organized in an Integer1DSet (a subclass of Set, which is a subclass of Data). This Set is our domain Set. As the name says, this Set is a one-dimensional set of (consecutive) integers. We will also need a FunctionType (function our height = f(time) ), a FlatField (another Data object), a DataReference (to link our Data to the display), a 2D display and two ScalarMaps to be included in the display.( time -> height )
ScalarMaps are objects which determine how Data objects are depicted. They define mappings from RealTypes (such as our time and height) to DisplayRealTypes, which are, for example, the x-, y- and z-axis, or the color components, or animation, etc.
We will then use a Java Frame to show our display.
// Import needed classes
import visad.*;
import visad.java2d.DisplayImplJ2D;
import java.rmi.RemoteException;
import java.awt.*;
import javax.swing.*;
/**
Java Tutorial Example 1_01
The first tutorial example. A function height = f(time), represented by the
MathType ( time -> height ), is plotted as a simple line.
this function is actually the parabola height = 45 - 5 * time^2,
We have the height values and time is the continuous independent variable, with
data values given by a Set.
Run program with "java P1_01"
*/
public class P1_01{
// Declare variables
// The quantities to be displayed in x- and y-axis
private RealType time, height;
// The function height = f(time), represented by ( time -> height )
private FunctionType func_time_height;
// Our Data values for time are represented by the set
private Set time_set;
// The Data class FlatField, which will hold time and height data.
// time data are implicitely given by the Set time_set
private FlatField vals_ff;
// The DataReference from the data to display
private DataReferenceImpl data_ref;
// The 2D display, and its the maps
private DisplayImpl display;
private ScalarMap timeMap, heightMap;
// The constructor for our example class
public P1_01 (String []args)
throws RemoteException, VisADException {
// Create the quantities
// Use RealType(String name)
time = new RealType("time");
height = new RealType("height");
// Create a FunctionType, that is the class which represents our function
// This is the MathType ( time -> height )
// Use FunctionType(MathType domain, MathType range)
func_time_height = new FunctionType(time, height);
// Create the time_set, with 5 integer values, ranging from 0 to 4.
// That means, that there should be 5 values for height.
// Use Integer1DSet(MathType type, int length)
time_set = new Integer1DSet(time, 5);
// Those are our actual height values
// Note the dimensions of the array:
// float[ number_of_range_components ][ number_of_range_samples]
float[][] h_vals = new float[][]{{0.0f, 33.75f, 45.0f, 33.75f, 0.0f,} };
// Create a FlatField, that is the class for the samples
// Use FlatField(FunctionType type, Set domain_set)
vals_ff = new FlatField( func_time_height, time_set);
// and put the height values above in it
vals_ff.setSamples( h_vals );
// Create Display and its maps
// A 2D display
display = new DisplayImplJ2D("display1");
// Create the ScalarMaps: quantity time is to be displayed along x-axis
// and height along y-axis
// Use ScalarMap(ScalarType scalar, DisplayRealType display_scalar)
timeMap = new ScalarMap( time, Display.XAxis );
heightMap = new ScalarMap( height, Display.YAxis );
// Add maps to display
display.addMap( timeMap );
display.addMap( heightMap );
// Create a data reference and set the FlatField as our data
data_ref = new DataReferenceImpl("data_ref");
data_ref.setData( vals_ff );
// Add reference to display
display.addReference( data_ref );
// Create application window, put display into it
JFrame jframe = new JFrame("My first VisAD application");
jframe.getContentPane().add(display.getComponent());
// Set window size and make it visible
jframe.setSize(300, 300);
jframe.setVisible(true);
}
public static void main(String[] args)
throws RemoteException, VisADException
{
new P1_01(args);
}
}
The source code is available here. If you compile
it with "javac P1_01.java" and run with "java tutorial.s1.P1_01" you should be able to see the following window.
By pressing and dragging with the left mouse button on the display you can move the graph around. By shift-clicking and moving the mouse up and down you can zoom in and out. Pressing and dragging the middle mouse button (on two-button mouse emulated by simultaneously clicking both buttons) shows a cross cursor that moves with the mouse. The values of the RealTypes at the cursor's position are shown on the upper left corner of the display.
In the following section we will look further into 2D graphs and show how to control color, axes properties, and show how a different MathType structure can lead to a different rendering.