A surface object represents a shaded or vector representation of a mesh grid.

An IDLgrSurface object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects.

Superclasses


IDLitComponent

Creation


See IDLgrSurface::Init.

Properties


Objects of this class have the following properties. See IDLgrSurface Properties for details on individual properties.

ALL

 

ALPHA_CHANNEL

AMBIENT

ANTIALIAS

BOTTOM

CLIP_PLANES

COLOR

DATA

DATAX

DATAY

DATAZ

DEPTH_OFFSET

DEPTH_TEST_DISABLE

DEPTH_TEST_FUNCTION

DEPTH_WRITE_DISABLE

DIFFUSE

DOUBLE

EMISSION

EXTENDED_LEGO

HIDDEN_LINES

HIDE

LINESTYLE

MAX_VALUE

MIN_VALUE

PALETTE

PARENT

REGISTER_PROPERTIES

RESET_DATA

SHADE_RANGE

SHADER

SHADING

SHARE_DATA

SHININESS

SHOW_SKIRT

SKIRT

SPECULAR

STYLE

TEXTURE_COORD

TEXTURE_HIGHRES

TEXTURE_INTERP

TEXTURE_MAP

THICK

USE_TRIANGLES

VERT_COLORS

XCOORD_CONV

XRANGE

YCOORD_CONV

YRANGE

ZCOORD_CONV

ZERO_OPACITY_SKIP

ZRANGE

In addition, objects of this class inherit the properties of all superclasses of this class.

Methods


This class has the following methods:

In addition, this class inherits the methods of its superclasses (if any).

Examples


Creating Surface Objects

To create a surface object, provide a two-dimensional array of surface values (Z values) to the IDLgrSurface::Init method. Optionally, you can supply two vectors or arrays X and Y that specify the locations in the XY plane of the Z values provided. If X and Y are not provided, the surface is generated as a function of the array indices of each element of the Z array.

For example, the following statements create a surface object from the two-dimensional array created by the IDL command DIST, as a function of the Z data array indices:

zdata = DIST(40)
mysurf = OBJ_NEW('IDLgrSurface', zdata)

Similarly, if xdata and ydata are either 40-element vectors or 40x40 element arrays specifying the X and Y values which, when evaluated by some function, result in the zdata array, you would create the surface object with the following statement:

mysurf = OBJ_NEW('IDLgrSurface', zdata, xdata, ydata)

Using Surface Objects

Surface objects have numerous properties controlling how they are rendered. You can set these properties when creating the surface object, or use the SetProperty method to the surface object to change these properties after creation.

Style

Set the STYLE property to an integer value that controls how the surface is rendered. Set the STYLE property equal to one of the following integer values:

  • 0 = Display a single pixel for each data point.
  • 1 = Display the surface as a wire mesh. (This is the default.)
  • 2 = Display the surface as a solid.
  • 3 = Display the surface using only lines drawn parallel to the x-axis.
  • 4 = Display the surface using only lines drawn parallel to the y-axis.
  • 5 = Display a wire mesh lego-type surface (similar to a histogram plot).
  • 6 = Display a solid lego-type surface (similar to a histogram plot).

For example, the following statement changes the surface object to display the surface as a wire mesh, with the lines drawn in blue:

mysurf->SetProperty, STYLE=1, COLOR=[0,0,255]

The following statement draws the surface as a solid lego-type surface in green:

mysurf->SetProperty, STYLE=6, COLOR=[0,255,0]

Vertex Colors

You can supply a vector of vertex colors via the VERT_COLORS property. The colors in the vector will be applied to each vertex in turn. If there are more vertices than colors supplied for the VERT_COLORS property, IDL will cycle through the colors. For example, the following statements color each vertex and connecting line one of four colors:

vcolors =[[0,100,200],[200,150,200],[150,200,250],[250,0,100]]
mysurf->SetProperty, STYLE=1, VERT_COLORS=vcolors

Shading

IDL provides two types of shading for surfaces. In Flat shading, the color of the first vertex in the surface is used to define the color for the entire surface. The color has a constant intensity. In Gouraud shading, the colors along each line are interpolated between vertex colors, and then along scanlines from each of the edge intensities.

Note: By default, only ambient lighting is provided for surfaces. If you do not supply a light source for your object hierarchy, solid surface objects will appear flat with either Flat or Gouraud shading.

Set the SHADING property of the surface object equal to 0 (zero) to use flat shading (this is the default), or equal to 1 (one) to use Gouraud shading. In the above example using vertex colors, adding the following statement:

mysurf->SetProperty, STYLE=2, SHADING=1

creates a surface in which the color values are interpolated between the vertex colors.

An Interactive Surface Example

With a little programming, we can create an application that allows the user to display a surface object and transform its model tree interactively using the mouse.

Example code is located in surf_track.pro in the examples/doc/objects subdirectory of the IDL distribution. Run the example procedure by entering surf_track at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT surf_track.pro.

This example uses IDL widgets to create a graphical user interface to an object tree. The SURF_TRACK procedure creates a surface object from user-specified data (or from default data, if none is specified), and places the surface object in an IDL draw widget. The SURF_TRACK interface allows the user to specify several attributes of the object hierarchy via pull-down menus. Finally, the SURF_TRACK procedure uses the example trackball object to allow the user to rotate the surface in three dimensions.

Call the SURF_TRACK procedure without an argument to use the default surface (a Bessel function) or with a two-dimensional array as its argument:

; Make up some data:
zdata = DIST(40)
SURF_TRACK, zdata

We encourage you to inspect the code in surf_track.pro for hints on how to create a widget application around a draw widget that uses Object Graphics.

Version History


5.0

Introduced

5.6

Added CLIP_PLANES property

6.1

Added ALPHA_CHANNEL, AMBIENT, DIFFUSE, EMISSION, SHININESS, and SPECULAR properties

6.4

Added SHADER property

Added GetVertexAttributeData, SetVertexAttributeData, Get MultiTextureCoord, and SetMultiTextureCoord methods

8.2.1

Added ANTIALIAS property