TOC PREV NEXT INDEX

The Annotation and Graphing Toolkit


2 Using AG Networks and Objects

This chapter describes how to construct networks that create and annotate graphs using the Annotation and Graphing (AG) Kit.

This chapter discusses:

2.1 Introduction

This chapter contains a number of examples that show you various features of the AG Kit. The chapter begins with an example that uses default data and describes how you add a title, add a legend, and annotate the axes. Other examples demonstrate how you change characteristics of the objects, select graph types, display your own data, and create contour maps.

Before Running the Examples

This chapter assumes that you read the AVS/Express Getting Started manual and you can create networks and change values of the objects in a network. You also must understand the concept of hierarchical data structures and the notion of inheritance.

For detailed information about the objects in the AG Kit, refer to the on-line reference pages.

Accessing the Example Networks and AG Kit Objects

You load the examples in this chapter by selecting Annotation_Graphing from the Examples page in the Network Editor and selecting the appropriate example file. For example, to load the simpleGraph network, open Annotation_Graphing from the Examples page and select the simpleGraph object.

Once you load the file, you can follow the example (labeled "Try this") and learn more about the AG Kit's features by experimenting on your own. To work with other AG objects, you access the AG Kit functionality via the Annotation_Graphing page in the Network Editor.

2.2 Creating a Simple Graph

This section shows an example of creating a simple graph using default data. It uses the example, Examples.Annotation_Graphing.simpleGraph. The following figure shows the graph that the example creates in the viewer.

Figure B-1


The graph contains a title, legend, axes, and ticklines. The Y axis has default values and the X axis has user-defined values.

In its simplest form, an AG network connects an AGGraph object to an AGGraphWorld object, then to an AGGraphViewportObj object, and finally, to a 2D viewer.

Figure B-2


AGGraph creates a graph. It has default data that the preceding configuration uses to display a curve in the viewer.

The graph appears in a rectangular area with a coordinate space. AGGraphWorld defines the world coordinate space. AGGraphViewportObj provides the rectangular area, known as a viewport, with a coordinate space for the graph. A 2D viewer constructs the screen image.

You can place several other elements in the viewport, for example, ticklines, axes, a legend, and a title. The example in this section shows you how to include these objects in the view.

Please note that AG objects must be connected to 2D viewers, or to the 2D input port of combined 2D and 3D viewers.

Adding Axes and Ticklines in the World Coordinate Space

Each AGGraphWorld object has its own world coordinate space that by default depends on all objects connected to its input port. The limits of the world coordinate space depend on the minimum and maximum X and Y values. The Y limits also depend on the baseValuesY and referenceValue parameters.

See also Y Base Values and Parameters that Determine World Coordinate Limits.

X and Y Axes

The X and Y axes show you the limits of the world coordinate space. The objects that create an X axis are AGXAxis and AGXUserAxis; the objects that create a Y axis are AGYAxis and AGYUserAxis.

Try this
Reference Ticklines

AGXAxis and AGYAxis objects lay out labels for the axes based on a reference value and a step size. By default, the reference and step size are based on the range of the data.

Try this
User Defined Labels

You create unique labels by instancing AGXUserAxis or AGYUserAxis. Both these objects have a labelStrings parameter that defines the text for the axes labels.

Try this

Adding a Title

You can create a title on a graph using AGTextObj. AGTextObj's position is relative to another object, for example, relative to a viewer or a viewport. To display a title positioned at the top center of the viewer, you connect the object directly to a viewer. In this case, the AGTextObj's position changes whenever the viewer's transformation matrix changes.

Try this
See Font Parameters for available font names.

Adding a Legend

AGGraphLegendObj is similar to AGTextObj in that its position and size depend on the object that references it. You set a legend's position by changing the geometry parameter in the graphLegend subobject. The position is relative to the limits set in the AGGraphViewportObj or a viewer, depending on which object references AGGraphLegendObj.

Before a legend appears in a viewer, you must supply data to the legend object's input port. This is done by connecting AGGraph's output to the input port of AGGraphLegendObj.

Try this

See also Setting Legend Text Strings, and Displaying a Contour Legend.

2.3 Common Annotation and Graphing Characteristics

A number of parameters in the AG Kit retrieve their values from other objects in the network hierarchy. Generally, these parameters describe the appearance and behavior of objects in which they are defined.

For more information on parameters, see Chapter 3, AG Structures and Concepts.

The example used in this section is Examples.Annotation_Graphing.graphChar.

Unset Parameters

Whenever AVS/Express needs a parameter's value, it traverses the network until it finds a setting for the parameter. This provides a mechanism to control parameter settings by setting only one occurrence of the parameter. With this in mind, you set the parameter in the appropriate place in the network.

Given the network in the following figure, you control the effect of a parameter for all instances of AGGraph by setting the parameter in AGGraphViewportObj. For example, to control the type of graph for all instances of AGGraph, you set graphType in AGGraphViewportObj.

Figure B-1


Alternatively, you can set the individual graphType parameters for each instance of an AGGraph object or for an instance of an AGGraphWorld object. The setting is not recursive at set time. To have the described effect, all children must have the graphType parameter unset, which is the default value.

Setting Color

All objects in the AG Kit have a variety of color parameters that set colors for different graphical objects. For example, you can set the color of the axes labels, axes text, or tickmarks.

Color of the Axes Labels

The textColor parameter determines the color of the text for the X axis and the Y axis. Independently setting this parameter in AGXAxis and AGYAxis controls the color of the X axis text and the Y axis text. Setting the textColor parameter in the object that references AGXAxis and AGYAxis controls the color of the text for both axes.

Try this
Color of a Graph

The AGGraph object's color parameter determines the color of the plotted graph. The graphColors parameter in AGGraphViewport sets the default colors of all AGGraph's connected to AGGraphViewport.

Try this

Changing the Size of Labels and Text Strings

A number of objects specify a distance, such as a height of a label or text object. The values of these parameters are measured as a percentage of the shortest side of a viewport or window size, whichever object references the object containing the parameter.

See the description for AGDistance on page

Try this

Setting the Drawing Order Using the Priority Parameter

All AG objects have a priority parameter that determines the drawing order. The priority has an effect only when an object references more than one other object. The settings of the priority parameters determine the order in which object's are drawn.

The AG Kit draws objects with higher priority values last, so these objects appear in front of graphics drawn in the same location. The priority parameter is initially 0, and if unchanged, the drawing order depends on the order in which you connected the objects-objects connected first are drawn first.

You increase the priority value if you want the object drawn after other objects, and decrease the priority if you want an object drawn before other objects. Negative values are acceptable.

Try this

2.4 Controlling Graph Type and Visibility

This section shows you how to set the graphType and the visibility parameters. The example used in this section (Examples.Annotation_Graphing.graphUI) generates the graph shown in the following figure.

Figure B-1


AG objects have a number of parameters that you may find easier to set from a user interface control panel. The graphType and visibility parameters fall into this category. This manual does not attempt to describe how you construct user interfaces. Please refer to Chapter 1, The User Interface ("UI") Toolkit for information on building user interfaces.

Selecting Graph Types and Setting Y Values

The AG Kit allows you to display your data using different graph types. These types are curve, bars, barlines, scatter, area, staircase, and stairarea.

Try this
Y Base Values

When you instance AGGraph, its first input port defines a Y base value. This value determines the minimum Y coordinate for bars, barlines, area, and stairarea graph types. Please note that in the example, an input port was added to the object named AGGraph, so the second input port connects to baseValuesY.

Try this
Y Reference Values

The referenceValue parameter has two functions. It provides a Y base value for the data when values are not supplied to baseValuesY. It also provides a value used to determine negative colors.

Try this

See also Adding Axes and Ticklines in the World Coordinate Space.

Positioning Bars and Staircase Plots

The AG Kit has default values that center bars, barlines, and staircase graphs. For bars and barlines, the center is set by the barOffsets parameter in the object AGGraphViewport or the object AGGraphViewportObj. For staircase graphs, the center is set by the shiftPosition parameter in an AGGraphViewport or AGGraphViewportObj. You can also set the center position in an AGGraph or AGGraphWorld object.

Bar Offsets

The default bar offsets were chosen so that when you display multiple bar graphs, the bars appear beside one another-rather than being drawn over one another. The default offsets are {0.4, 0.2, 0.0, -0.2, -0.4}. These values represent a relative offset between adjacent bars.

Try this
Staircase Position

By default, the centers of each plateau in a staircase graph align with the X values. Setting the shiftPosition parameter in AGGraph changes the center alignment.

Try this

Controlling Visibility

Each AG object has a visibility parameter. This parameter determines whether to render the AG object. A nonzero value makes the object visible; 0 makes the object invisible. The visibility parameter is initially set to 1, so an AG object is by default visible.

You can control the visibility parameter from a UI object, such as a menu item.

The Graph Editor

The Graph Editor is shown below. It includes two new options for contour plots: Iso Label Color and Iso Label Frequency. These new options allow you to change the isoline label color and to change the frequency of major isolines.

Figure B-2


Properties Page

The Properties page of the Graph Editor was updated to include two new toggles: Uniform Scale and Nice Limits.



Both toggles are associated with subobjects that were part of the AGWorldParams template and the AGGraphWorld object in earlier AVS/Express releases.

2.5 Displaying Your Own Data

Each instance of AGGraph contains the same default data, so you see a graph regardless of whether another module generates data for the graph. The example for this section (Examples.Annotation_Graphing.rainfall) overrides the default data by sending one of two datasets to separate instances of AGGraph. This example uses sample data and displays the following figure.

Figure B-1


AGGraph's Input Ports

To display your own data, you must provide Y data values and send these values to AGGraph's right-most input port. If you do not send data to the X data input port (in other words, the input port that is second from the right), AGGraph automatically generates X data from 1 to the number of Y values in steps of 1. For example, for five Y values, AGGraph generates the five X values {1, 2, 3, 4, 5}.

The remaining input ports are for Y base values and the legend text. The left-most input port expects Y base values, as described on page . The second input port from the left expects a text string for annotating the data in a legend.

The following figure shows the AGGraph object and describes its input ports.

Figure B-2


World Coordinate Systems

The AG Kit allows you to have different world coordinate systems displayed in the same viewport. This enables you to display datasets having widely differing ranges of data within the same viewport. The names of the two AGWorld objects in this section's example are TempWorld and RainWorld.

Try this

Axes References

The axes labels and tickmarks are automatically positioned to represent the world coordinate space. The X limits for the world coordinate space are increased to compensate for the width of bars in a bar graph and generates a nicer appearance when displaying a bar graph. For example, when data ranges from 1 to n, the default world limits are 0.5 to n+0.5.

Try this

Parameter Settings

Parameters that have the same name can have different default values. If you want them to have the same value, you set the value in an object that is downstream in the network.

Try this

Using Special Characters In Text Objects

The AG Kit provides special characters that you can use in text strings.

See String Parameters and the on-line reference for the Character and Font Tables. The PDF versions of the Character and Font Tables can also be viewed.

Try this

Positioning Text

When you position text inside the axes boundaries, you should consider the range of the world coordinate system. This makes text alignment easier to adjust because you can align a text object to the ticklines.

Try this

Annotating a Graph Using Arrows

Arrow objects are useful for drawing attention to specific parts of a graph. This example uses arrows to show you when the hurricane season begins and ends.

Try this

2.6 Creating Logarithmic Axes

The example in this section (Examples.Annotation_Graphing.logex2) draws the axes using a logarithmic scale. The data is a set of curves showing the absolute transmissibility of a simple spring-mass system as a function of the frequency ratio for various damping ratios. The following figure shows the View after you load the example file.

Figure B-1


Calculating X Data

AVS/Express can calculate values that you use as input data to a graph. In this example, AVS/Express calculates a series of floating-point values.

Try this

The following lines of code are in the V language. The code shows you the calculations produced by various objects in this example.

double ratios[] = {1e-06,0.05,0.1,0.2,0.5,1};
float ratios2[] => (2.0*ratios)*(2.0*ratios);
int numValues = 200;
float x[] => pow(10,init_array(numValues,-1,1));
float x2[] => x * x;
float x3[] => (1 - x2) * (1 - x2);
float y0[] => sqrt(1 + (ratios2[0] * x2)) / sqrt(x3 + (ratios2[0] * x2));
float y1[] => sqrt(1 + (ratios2[1] * x2)) / sqrt(x3 + (ratios2[1] * x2));
float y2[] => sqrt(1 + (ratios2[2] * x2)) / sqrt(x3 + (ratios2[2] * x2));
float y3[] => sqrt(1 + (ratios2[3] * x2)) / sqrt(x3 + (ratios2[3] * x2));
float y4[] => sqrt(1 + (ratios2[4] * x2)) / sqrt(x3 + (ratios2[4] * x2));
float y5[] => sqrt(1 + (ratios2[5] * x2)) / sqrt(x3 + (ratios2[5] * x2));

For more information on the V language, see Chapter 8, The V Command Processor, and the V Language in the Using AVS/Express manual.

Setting the Logarithmic Axis

The X and Y axes can have one of three scale types applied. By default, the axes have a linear scale. You can also change the scale of an axis to a logarithmic scale or a power scale.

Try this

Reversing the Axes Direction

The limitsX and limitsY parameters control the directions of the X and Y axes. By default, the origin of the axes are in the lower-left corner of the graph. Assigning the upper limit to the first element of the limitsX or limitsY array and the lower limit to the second element of the limitsX or limitsY array reverses the direction of the respective axis.

Try this

Setting Legend Text Strings

The legend in this example has six unique text strings that describe the individual curves. These strings are set in the AGGraph objects.

Try this

For a list of the meaning of characters preceded by "\", see String Parameters. For a list of special characters, see the on-line reference for Character and Font Tables.

2.7 Creating Contour Maps

The AG Kit allows you to display three types of contours-filled contours, isolines, and datamapped isolines. This section uses two contour examples (Examples.Annotation_Graphing.contour1 and contour2) to show you basic contour features. The following figure shows you the viewer displayed by the first contour example (contour1).

Figure B-1


Supplying Data to a Contour Plot

Contour objects do not have default data. Therefore, before you see a contour, you must send an appropriate dataset to the first input port. AGContour's and AGContourObj's first input ports accept a 2D scalar uniform, rectilinear, or structured field.

Try this

Selecting a Contour Type

You specify a contour type by setting the contourType parameter in the contour object. Acceptable strings are "filled contours", "isolines", and "datamapped isolines". The default type is "filled contours".

Try this

Specifying the Number of Contour Levels

Each contour level is depicted as an isoline. By default, the AG Kit calculates the number of contour levels by finding the minimum and maximum values, then dividing the range of values into ten equal classes.

Try this

See Setting Class Values.

Viewing Data as Datamapped Isolines

The second contouring example (Example.Annotation_Graphing.contour2) displays datamapped isolines. After you load the second contouring network, you must select a dataset because AGContour does not contain default data for generating contour plots. You must supply the network with a 2D scalar uniform, rectilinear, or structured AVS/Express field.

For sample data in this example, select "Read Field" in the module editor window and choose the dataset wind.fld. (wind.fld is located in the field directory within the data directory in your installation area.)

The following figure shows the view displayed by the second contouring example.

Figure B-2


Determining the Contour Colors

By default, each contour level maps to a color in the range from 0 to 255. You can adjust the color range to match the range of your data by sending the same data to AGContour and the second input port of AGDataObject. Once data arrives at the second input port, the datamapper object (see the Visualization Techniques manual) retains the data range.

Try this

Displaying a Contour Legend

The AGContourLegend creates a legend for a contour plot. The legend automatically lists the values of the contour levels and displays the color of the contour levels. Legends for filled contours show the colors as filled rectangles. Legends for isoline contours show the colors as color lines. You can only have one legend per contour object.

Try this

See also Adding a Legend and Setting Legend Text Strings.

Setting Class Values

By default, the AG Kit displays contour levels in equal intervals. It calculates the number of contours by finding the minimum and maximum values, then divides the range of values into ten equal classes.

Unequal intervals can show finer detail in specific areas of your plot while grouping less interesting data into areas having a wider variation of values. To override the default behavior and group contour levels into unequal intervals, you specify an array of class values. Setting classValues overrides any values for maxClass, minClass, and numClasses.

Try this

Positioning the Contour Labels

Only major isolines have labels. The position of the labels depends on the distance between the isolines and the angle at which they are displayed. The AG Kit never allows labels to overlap.

Try this

Choosing the Frequency Of Major Isolines

By default, all isolines are major isolines. However, you can control the frequency of major isolines by setting the majorIsoLineFrequency parameter.

Try this

TOC PREV NEXT INDEX