Graphics Methods and Templates

Question

What is a graphics method and template?

Answer

To make a plot in CDAT, you first create a VCS canvas:

import vcs
v = vcs.init()

Upon this canvas (object v), you "place" primary or secondary objects (or "elements"). There are three primary elements: data, a graphics method, and a template. The graphics method is what transforms your data into the type of plot (scatter, x-y, boxfill, isofill, etc.) you want; it "translates" your data into a specific type of plot with the plot command. Given your data, the graphics method calculates things like how to divide up the axes and what sort of plot symbols to use.

The template takes care of the "layout" of the plot. The template specifies things like how large the plot will be, the plot box, tick lengths, tick label locations, and what text and line elements are turned on or off.

Secondary elements are the building blocks for select attributes of the graphics method and template. Secondary elements include such things like blocks of text, lines, color maps, etc.

Graphics methods and templates are "named" either by instantiating an object or by reference to its name in a directory of graphics methods and templates. For instance, say I wanted to create my own x-y line plot graphics method which I could then change to suit my personal tastes:

xy_gm = v.createxvsy('myNewGraphicsMethod', 'default')

This creates the graphics method object xy_gm with the name myNewGraphicsMethod from the default x vs. y plot graphics method.

For assignment operations, when we change some attribute of the graphics method, we reference the graphics method by its object name (xy_gm). For instance, to change one of the attributes in the graphics method object, (like setting the symbol marker to a circle), the assignment would be:

xy_gm.marker = 4

In other cases, such as when we are copying the method to another graphics method, we can reference the graphics method by its name (myNewGraphicsMethod). For instance, when we created myNewGraphicsMethod, we referred to the default x vs. y graphics method by its name default.

You can see a directory of all graphics method names currently defined for this Python session with the show method of the canvas object. For instance, to see all x vs. y plot graphics methods:

>>> v.show('xvsy')
**************************XvsY Names List*************************
(   1):             default   myNewGraphicsMethod
**************************End XvsY Names List*********************

which tells us there are two x vs. y graphics methods available: a default method (which cannot be changed, though it can be copied) and the graphics method I just created. A list of the available isofill graphics methods is shown by v.show('isofill').

A template is created in a similar way as a graphics method:

my_template = v.createtemplate('myNewTemplate', 'default')

Here we create a new template from the default template. The v.show('template') command would give a list of all available templates, including our myNewTemplate template.

We can use our template to turn off the mean, maximum, and minimum fields that are in the default plot (see the simple line plot example) by setting their "priority" to zero:

my_template.mean.priority = 0
my_template.max.priority = 0
my_template.min.priority = 0

We use our custom graphics method and template in a plot by specifying the objects as arguments in a plot command:

import Numeric as N
x = N.arange(17)*N.pi/8.
y = N.sin(x)
v.plot(x, y, xy_gm, my_template, name='Sine Curve')

which gives us the following output:

Note that in the plot command, we can specify the template by its name instead of its object name. Thus:

v.plot(x, y, xy_gm, 'myNewTemplate', name='Sine Curve')

would have worked just fine. Since there are many predefined templates, this means you can use one of those templates without creating a template object. (This isn't generally true for graphics methods in plot calls.)


Notes: This discussion applies to CDAT 3.3.

Return to the Tips and Examples index page.

Updated: December 1, 2003 by Johnny Lin <email address>. License.