3

Programming JClass Chart 3D: Surfaces and Bars

Fifteen Basic Types of Surfaces and Bars  Chart Types  Bar Charts and Histograms

Contours and Zone Display  Mesh Controls   Surface Colors  Solid Surface

All elements mentioned in this chapter refer to both the Java 2 API and the Java 3D API, unless specifically noted.

---

3.1 Fifteen Basic Types of Surfaces and Bars

One of the types of data that can be attached to JClass Chart 3D is grid data. Grid data that has been attached to the chart can be displayed in a surface, bar, or scatter plot representation. Grid data is supplied to the chart via Chart3dDataView's elevationDataSource property. The chart then processes the data and stores it in an internal data object of type Chart3dGridData. For elevation data, this internal object can be referenced via the elevationData property. The user can retrieve this internal object, query it for data values, and set certain properties on it.

The chart uses elevation data to draw a surface plot, bar plot, or scatter plot, depending on the chartType, which will be SURFACE, BAR, or SCATTER.

An elevationDataSource must implement the Chart3dDataModel interface. To be grid data, it must also implement the Chart3dGridDataModel interface. This promises the chart that it can supply an xGrid array, a yGrid array, and a doubly indexed zValues array. If the datasource wants to provide X- and Y-data labels to the chart, it should implement the LabelledChart3dGridDataModel interface. Similarly, a hole value, other than the default, can be provided through the HoleValueChart3dDataModel. Data values can be edited through the EditableChart3dDataModel and data changes can be monitored if the datasource implements the Chart3dDataManager interface.

The elevationDataSource can also take points as its data type. This type of data can only be used for scatter plots.

Note that using a data set of type point with a chart type of SURFACE or BAR will produce a blank plot.

When grid data is used and the chart type is either SURFACE or BAR, JClass Chart 3D's four basic display Boolean properties - Meshed, Shaded, Contoured, and Zoned - combine to create 15 different basic surface and bar displays. No graph is displayed when all four Booleans are false.

3.1.1 JCElevation: Meshed, Shaded, and Transparent Plots

The JCElevation object determines whether surface and bar plots are Meshed, Shaded, or Transparent. The JCElevation constructor initializes the Meshed, Shaded, and Transparent properties (each of which takes a Boolean value). The defaults for each of these are Meshed=true, Shaded=false, and Transparent=false.

Meshed

Surfaces: When Meshed is true, JClass Chart 3D displays the X-Y grid projected onto the 3D surface in a 3D view with a Z-axis. You can use the xMeshShow and yMeshShow properties of JCSurface to individually control whether the X- and Y-mesh lines are showing.

The xMeshFilter and yMeshFilter properties of JCSurface allow every nth mesh line to be drawn. By default, the chart chooses a pleasing filtering. The meshTopColor and meshBottomColor properties allow the user to control the top and bottom colors of the mesh lines.

Bars: When Meshed is true, JClass Chart 3D will draw the outline of all the bars. All bars with a value greater than or equal to the origin of the Z-axis will be outlined using the meshTopColor, and all bars with a value less than the origin will be outlined using the meshBottomColor. When Transparent is true, all the lines of every bar will be visible.

Shaded

Surfaces: When Shaded is true, JClass Chart 3D displays the data as a flat shaded surface in a 3D view with a Z-axis. The surface color is controlled with the shadedTopColor and the shadedBottomColor properties (not currently available in the Java 3D API version of JClass Chart 3D).

Bars: When Shaded is true, JClass Chart 3D draws each bar as a solid bar. All bars with a value greater than or equal to the origin of Z-axis will be drawn using the shadedTopColor, while all bars with a value less than the origin will be drawn using the surfaceTopColor.

The following code snippet shows setting these properties:

  JCElevation elevation=c.getDataView(0).getElevation();
  elevation.setMeshed(true);
  elevation.setShaded(true);
  elevation.setTransparent(false);

3.1.2 JCContour: Contoured and Zoned Plots

The JCContour class deals with information about contours and zones. Two of its properties are Contoured and Zoned. Both default to false.

Contoured

Surfaces: When Contoured is true, JClass Chart 3D examines the distribution of the data, using the JCContourLevels class, and draws contour lines demarcating each of the contour levels. The contour line style, thickness, and color are controlled with the contourStyles property.

Bars: When Contoured is true, JClass Chart 3D examines the distribution of the data, using the JCContourLevels class, and draws contour lines around the bars, demarcating each of the contour levels. The contour line style, thickness, and color are controlled with the contourStyles property.

Zoned

Surfaces: When Zoned is true, JClass Chart 3D examines the distribution of the data, using the JCContourLevels class, and fills each level with a solid color. (Unless Meshed is true and Shaded is false, in which case the fill color is used to draw each level's mesh lines.) The color for each level is specified with the contourStyles property.

Bars: When Zoned is true, JClass Chart 3D examines the distribution of the data, using the JCContourLevels class, and fills each level within each bar with a solid color. (Unless Meshed is true and Shaded is false, in which case the fill color is used to draw each level's mesh lines.) The color for each level is specified with the contourStyles property. If zoneDataSource is supplied to the data view, each bar is filled with a solid color. Otherwise, the bar is segmented by height according to the contour levels.

---

3.2 Chart Types

The following table shows the 15 basic graph types:

GraphChart Type	Meshed	Shaded	Contoured	Zoned	Surface Example	Bar Example	Comments
1	T	F	F	F			Meshed. Displays surface as a mesh and bars in outline.
2	F	T	F	F			Shaded. Displays surface and bars in a flat shade. Top and bottom colors may be set.
3	F	F	T	F			Contoured. Contour lines are automatically drawn between distribution levels in the data.
4	F	F	F	T			Zoned1. Similar to Contoured, except that each distribution level is displayed in a solid color.
5	T	T	F	F			Meshed, Shaded. Draws surface as a mesh and bars in outline. Surface and bars are flat shaded.
6	T	F	T	F			Meshed, Contoured. Displays surface as a mesh and bars in outline. Also draws contour lines along borders between distribution levels in the data.
7	T	F	F	T			Meshed, Zoned. Displays surface as a mesh and bars in outline. Uses zoning colors for mesh and bar outlines.
8	F	T	T	F			Shaded, Contoured. Displays a flat-shaded surface or bars with contour lines superimposed.
9	F	T	F	T			Shaded, Zoned. Zone colors are used to flat shade the surface or bars.
10	F	F	T	T			Contoured, Zoneda. Displays contour lines and flat shaded zone colors to demarcate levels in the data.
11	T	T	F	T			Meshed, Shaded, Zoned. Similar to Shaded, Zoned, but with a mesh or bar outlines superimposed.
12	T	T	T	F			Meshed, Shaded, Contoured. Similar to Meshed, Shaded, but contour lines are superimposed.
13	F	T	T	T			Shaded, Contoured, Zoned. Similar to Shaded, Zoned, but contour lines are superimposed.
14	T	F	T	T			Meshed, Contoured, Zoned. Similar to Meshed, Zoned, but with contours superimposed.
15	T	T	T	T			Meshed, Shaded, Contoured, Zoned. The sum of all basic options.

1In this release, Zoned is the same as Zoned and Shaded for bar charts. Application developers are urged to use the Zoned and Shaded combination for this view, since the interpretation of the Zoned combination may change in a future release.

---

3.3 Bar Charts and Histograms

When chartType is BAR, the elevation data will be displayed as a bar chart (if grid data is supplied). Each data point will be represented by a single bar. The spacing between adjacent elements in the grid is honored.

Bar Z Origin

Bars start from the z Axis origin, which can be controlled through JCAxis' origin property. The default value of the origin is 0.0. When Shaded is true, bars that have values greater than the origin are rendered in the shadedTopColor property of the JCElevation class. Negative bars (that is, bars with values less than the origin) are rendered in the shadedBottomColor.

Bar Spacing

The amount of space occupied by a bar, as a percentage of the maximum amount possible, is controlled through the xSpacing and ySpacing properties of the JCBar class. The default is 80%. Setting it smaller results in thinner bars. Setting bar spacing to 100% (the maximum) results in bars that about one another.

Figure 11 :  Fixed Bar Chart with X-Spacing set to 1% and Y Spacing set to 100%.

Histograms

To display a histogram, set both the xFormat and yFormat properties of JCBar to HISTOGRAM (default is FIXED). Thus, the X-axis and Y-axis can be independently switched between fixed and histogram formats.

If the X-axis is switched to a histogram, each bar's left edge will be drawn aligned with corresponding X-values in the data. The width of each bar will be the distance between subsequent X-values in the data. Since the width of each bar is derived from the spacing between its neighbors, there is always one fewer bar along a histogram axis than there is if the same data is displayed along a fixed axis.

Histograms usually make good use of data whose grid values are not equally spaced. This gives control over spacing in the data grid.

Figure 12 :  Fixed versus Histogram Display of Identical Data.

Grid Colors

If Shaded is true and Zoned is false, the colors of the individual bars can be controlled. Normally, all bars with a value below the origin are colored with shadedBottomColor, and all others are colored with shadedTopColor. However, in some situations, it is useful to color a row, column, or individual bar in the chart with a distinct color.

The JCGridColor class is used to specify the fill color of a group of bars, or of an individual bar. The Chart3dDataView class' gridColors property stores a list of JCGridColor objects.

The JCGridColor class has a dataIndex property and a color property. The dataIndex is a reference to a JCData3dGridIndex object which stores an index to a bar or group of bars. The color property indicates what color to make the bars referenced by the dataIndex.

An individual bar can be colored by specifying its indices in the dataIndex object. For example, to set the bar in the third X-data line, second point to red, set the xIndex property of the dataIndex to 2, the yIndex to 1, and the color to Color.red.

To specify the color of an entire row of bars, set the other index to JCData3dIndex.ALL. For instance, the entire fifth X line of bars is set to green by setting the xIndex property of the dataIndex to 4, the yIndex to JCData3dIndex.ALL, and the color to Color.green. To set the color of all the bars, set both the xIndex and yIndex of the dataIndex to JCData3dIndex.ALL.

Chart3dDataView has several convenience methods for manipulating the list of JCGridColors. It has addGridColor() and removeGridColor() for adding and removing grid colors. It also has a findGridColor() method which retrieves the first grid color that matches a given (xIndex, yIndex) index starting from the end of the list; this is what the chart uses to determine the color of a given bar. If findGridColor() returns null, the bar color falls back to either the shadedTopColor or the ShadedBottomColor.

JClass Chart 3D's Chart3dDataView will only maintain one entry per (xIndex, yIndex) combination. Whenever a second entry for the same indices is supplied, the first entry is removed. Later entries take precedence over earlier entries.

The following code created the bar coloring in Figure 13:

dataView.addGridColor(JCData3dIndex.ALL, JCData3dIndex.ALL, new Color(255, 208, 0));
dataView.addGridColor(1, JCData3dIndex.ALL, Color.blue);
dataView.addGridColor(JCData3dIndex.ALL, 1, new Color(176, 32, 240));
dataView.addGridColor(1, 1, Color.red);

Figure 13 :  3D Chart demonstrating numerous grid colors.

Note that even though the index of the bar at (1, 1) matches every entry in the list, the bar is colored red because it matches the last entry in the list.

---

3.4 Contours and Zone Display

When Contoured or Zoned is true, JClass Chart 3D marks each contour level from an array of 100 built-in contour styles.

Each contour style contains information about the contour line style, width, pattern, color, and zone color (used to mark each level). Contour styles can be customized by an application. Please see Customizing Contour Styles, in Chapter 6 for details.

Contour Styles Used

JClass Chart 3D determines which contour style to use for a particular level automatically, evenly distributing the styles through the number of levels, as shown by Figure 14.

Figure 14 :  A Sampling of Supplied Contour Styles Used as Needed.

By implementing the JCContourMapping interface and using the setContour.Mapping() method of the JCContour class, you can override the default level to contour style mapping.

Also, by using the JCContourLevels class, you can specify your own contour levels (such as an array of doubles). You can also use your own contour styles by setting the contourStyles property of the JCContour class. For further information, please see Advanced JClass Chart 3D Programming, in Chapter 6.

Contour/Zone Projection

The JCProjection class specifies information about the Contoured and Zoned projections on the top and bottom of the plot cube. For instance, you can use the setContoured method to set the projection to be Contoured, and you can use the setZoned method to set the projection to be Zoned.

The JCPlotCube floor property is a JCProjection that indicates whether a projection should be drawn on the bottom of the plot cube. If either the Contoured or Zoned property of the floor projection is true, a projection is drawn. Similarly, the ceiling projection controls what type of projection is drawn on the top of the plot cube.

These properties do not depend on the values of Contoured and Zoned of the JCContour class. However, any other property that affects contour generation or rendering affects projected contours/zones. Floor and ceiling projections are ignored in 2D graphs, bar charts, and scatter plots.

Figure 15 :  Projecting Contours and Zones.

Zone Method

An application can control the method used to fill each zone region by leveraging the ZoneMethod property of the JCContour class. By default, JClass Chart 3D fills between each contour interval (ZONE_CONTOURS). When set to ZONE_CELLS_AVERAGE, JClass Chart 3D fills entire cells in the grid based on the average of the four corners of the cell. Figure 16 illustrates the difference visually. When set to ZONE_CELLS_CORNER, entire cells are filled using the value at the bottom left corner of the cell.

Cell zoning produces a coarser-looking surface, but offers significant performance advantages over contour zoning. However, the visual difference between the two types of zoning diminishes with larger grids.

Figure 16 :  Contour Zoning (left) and Cell Average Zoning (right).

---

3.5 Mesh Controls

Mesh Colors

Mesh colors are controlled by methods in the JCElevation class.

The bottom and top colors of the mesh drawn when Meshed is true can be set with setMeshTopColor and setMeshBottomColor. They are both "black" by default. See Chart Colors, in Chapter 1 for details on setting colors.

Mesh Filtering

Methods in the JCSurface class control mesh filtering. This class contains properties that pertain to surface plots.

The xMeshFilter and yMeshFilter properties specify how the mesh is filtered before being displayed. By default, no filtering is performed. When set to 0, JClass Chart 3D automatically filters the mesh to provide a pleasing display, and changes the filter as the graph is scaled or the data changes.

You can hard-code a mesh filter by setting these properties to any positive integer. For example, a value of 5 filters the mesh so that every 5th line is drawn.

Figure 17 :  Effect of Mesh Filtering.

Hidden Mesh Lines

When Meshed is true and Shaded is false, grid and contour lines that are obscured from view by intervening portions of the scene are not displayed by default. To display these lines, set the Transparent property of JCElevation is to true.

Figure 18 :  Hidden line removal.

---

3.6 Surface Colors

The bottom and top colors of the shaded surface drawn when Shaded is true can be set with shadedTopColor and shadedBottomColor of the JCElevation class. By default the bottom color is "dim grey" or RGB(112,112,112) and the top color is "light grey" or RGB(211,211,211). See Chart Colors, in Chapter 1 for details on setting colors. Please note that shadedTopColor and shadedBottomColor are currently not available for surfaces in the Java 3D API version of JClass Chart 3D.

---

3.7 Solid Surface

Setting the Solid property of JCSurface to true will cause JClass Chart 3D to draw a skirt around the data, thereby joining the edge of the surface to a plane at the minimum Z value, as shown in Figure 19.

Figure 19 :  Setting Solid Surface On and Off.