Copyright: OOG 4Feb97


Objects and Object Graphics TOC
IDL Objects and Object Graphics

This help file contains documentation for IDL Objects and Object Graphics.

NOTE:

This is beta-test documentation. Both the text and the hypertext coding are still in flux. Feel free to make comments on the current contents, but realize that it is not yet complete and will change significantly before the final release of IDL 5.0.

Examples of Object Grahpics


Object Graphics Reference
IDL Object Graphics Reference

Select "Contents," "Keyword Search," or "Text Search" from the

Navigate menu, or click the "Help Topics" button, for more

navigational aids. Click "Main Help File" to return to the main IDL

online help file.


Examples of Object Graphics
Examples of Object Grahpics

Example code included in this volume is currently incomplete. There are, however, a number of files containing example code located in the object subdirectory of the examples directory of your IDL installation.


Overview of Objects and Object Graphics
Overview

This chapter includes information about IDL, the IDL documentation set, and about contacting Research Systems regarding problems with IDL.


About This Volume

This volume was written concurrently with the development of the IDL Object Graphics system. As a result, sections of Objects and Object Graphics may lack the depth of discussion or quantity of examples evidenced by the other volumes in the IDL documentation set.

As with all aspects of IDL, development and enhancement of Objects and Object Graphics is an ongoing process. And while we encourage you to contact us with suggestions for improvement of any of IDL's documentation, we especially encourage you to send us your comments on this book. Reports of inconsistencies or errors, suggestions for expanded explanations or examples, or any other comments that come to mind are welcome. Submit your comments by electronic mail to doc-comments@rsinc.com, or by fax to (303) 786-9909.


About IDL

IDL is a complete computing environment for the interactive analysis and visualization of data. IDL integrates a powerful, array-oriented language with numerous mathematical analysis and graphical display techniques. Programming in IDL is a time-saving alternative to programming in FORTRAN or C—using IDL, tasks which require days or weeks of programming with traditional languages can be accomplished in hours. You can explore data interactively using IDL commands and then create complete applications by writing IDL programs.

Advantages of IDL include:

•	IDL is a complete, structured language that can be used both interactively and to create sophisticated functions, procedures, and applications.

•	Operators and functions work on entire arrays (without using loops), simplifying interactive analysis and reducing programming time.

•	Immediate compilation and execution of IDL commands provides instant feedback and "hands-on" interaction.

•	Rapid 2D plotting, multi-dimensional plotting, volume visualization, image display, and animation allow you to observe the results of your computations immediately.

•	Many numerical and statistical analysis routines—including Numerical Recipes routines—are provided for analysis and simulation of data.

•	IDL's flexible input/output facilities allow you to read any type of custom data format. Support is also provided for common image standards (including BMP, GIF, JPEG, and XWD) and scientific data formats (CDF, HDF, and NetCDF).

•	IDL widgets can be used to quickly create multi-platform graphical user interfaces to your IDL programs.

•	IDL programs run the same across all supported platforms (Unix, VMS, Microsoft Windows, and Macintosh systems) with little or no modification. This application portability allows you to easily support a variety of computers.

•	Existing FORTRAN and C routines can be dynamically-linked into IDL to add specialized functionality. Alternatively, C and FORTRAN programs can call IDL routines as a subroutine library or display "engine".


IDL Documentation

IDL's Online Help system gives you access to the complete IDL documentation set in electronic, hypertext-linked format. You can enter the Online Help system by entering ? at the IDL command prompt or by selecting "Online Help" from the Help menu of the IDL Development Environment user interface.

Research Systems provides a subset of the complete IDL documentation set in printed form along with your copy of the IDL software. We do not ship the full printed documentation set because some volumes cover specialized topics, which are of limited interest to some of our customers. Shipping only the volumes of greatest general interest in printed form allows us to provide the highest quality documentation set possible while minimizing the impact of our documentation on the environment. In addtion to being available on-line, volumes not automatically shipped with new or upgrade orders are available for purchase; use the order sheet included with your shipment or consult your sales representative or distributor for details.

The IDL documentation set consists of the following volumes:

Using IDL

Using IDL explains IDL from an interactive user's point of view. It contains information about the IDL environment, the structure of IDL, and how to use IDL Direct Graphics to analyze your data.

Building IDL Applications

Building IDL Applications explains how to use the IDL language to write programs — from simple procedures to large, complex applications. It contains information on the structure of the IDL language, programming techniques, IDL Direct Graphics, and IDL's user-interface toolkit.

IDL Reference Guide

The Reference Guide is a two-volume set that contains detailed information about all of IDL's non-object oriented procedures, functions, system variables, and commands. Information on IDL's object-oriented features and IDL Object Graphics is contained in IDL Objects and Object Graphics.

Note	Each of the above books includes a comprehensive index that covers all four volumes.

IDL Objects and Object Graphics

Objects and Object Graphics (this volume) contains information on IDL's object-oriented features, including a complete discussion of IDL Object Graphics. This volume also contains the complete reference to IDL's object class libraries.

Using Insight

Using Insight contains information on IDL Insight, the graphical interface to IDL's analysis capabilities. Insight allows you to import, analyze, and visualize data without programming in the IDL language.

IDL Advanced Development Guide

The Advanced Development Guide explains how to use IDL in concert your computer's operating system or with programs written in other programming languages.

IDL Scientific Data Formats

Scientific Data Formats contains detailed information about IDL's routines for dealing with Common Data Format (CDF), Heirarchical Data Format (HDF), and Network Common Data Format (NetCDF) files.

IDL DataMiner Guide

The DataMiner Guide contains information on using IDL to interact with databases using the Open Database Connectivity (ODBC) interface.

Note	The DataMiner option must be purchased separately.

IDL HandiGuide

The HandiGuide is a handy quick reference that contains calling-sequence information on all IDL routines.


Typographical Conventions

The following typographical conventions are used throughout the IDL documentation set:

•	UPPER CASE
IDL functions, procedures, and keywords are displayed in UPPER CASE type. For example, the calling sequence for an IDL procedure looks like this:

CONTOUR, Z [, X, Y]

•	Mixed Case
IDL object class and method names are displayed in Mixed Case type. For example, the calling sequence to create an object and call a method looks like this:

object = OBJ_NEW('IDLgrPlot')

object -> GetProperty, ALL=properties

•	Italic type
Arguments to IDL procedures and functions — data or variables you must provide — are displayed in italic type. In the above example, Z, X, and Y are all arguments.

•	Square brackets ( [ ] )
Square brackets used in calling sequences indicate that the enclosed arguments are optional. Do not type the brackets. In the above CONTOUR example, X and Y are optional arguments. Square brackets are also used to specify array elements.

•	Courier type
In examples or program listings, things that you must enter at the command line or in a file are displayed in courier type. Results or data that IDL displays on your computer screen are shown in courier bold type. An example might direct you to enter the following at the IDL command prompt:

array = INDGEN(5)

PRINT, array

In this case, the results are shown like this:

      0       1       2       3       4


Reporting Problems

We strive to make IDL as reliable and bug free as possible. However, no program with the size and complexity of IDL is perfect, and bugs do surface. When you encounter a problem with IDL, the manner in which you report it has a large bearing on how well and quickly we can fix it. This section is intended to help you report problems in a way that will help us correct the problem rapidly.

Background Information

When a bug is reported and verified, we correct it in a later release. Sometimes, a bug only occurs when running on a certain machine, operating system, or graphics device. For these reasons, we need to know the following facts when you report a bug:

•	Your IDL installation number.

•	The version of IDL you are running.

•	The type of machine it is running on.

•	The operating system version it is running under.

•	The type and version of your windowing system.

•	The graphics device, if the problem involves graphics.

The installation number is assigned by us when you purchase IDL. The IDL version, site number, and type of machine are printed when IDL is started. For example:

IDL. Version 4.0.1c (sunos sparc).
Copyright 1989-1996, Research Systems, Inc.
All rights reserved.  Unauthorized reproduction prohibited.
Installation number: 177.
Licensed for use by: ACME Datawhack Corp.

is the startup announcement from IDL version 4.0.1c under SunOS on a Sun Sparc workstation at installation number 177.

Under Unix, the version of the operating system can usually be found in the file /etc/motd. It is also printed when the machine boots. In any event, your system administrator should know.

Under VMS, the DCL statement:

write sys$output f$getsyi("version")

will give you the operating system version.

Under Windows 95 and Windows NT version 4, select "About" from the Help menu in the Windows Explorer. Under Windows 3.11 and Windows NT version 3.5, select "About" from the Help menu in the File Manager.

On the Macintosh, select "About this Macintosh" from the apple menu.

Double Check

Before reporting a problem, you should always ask yourself "Is it really a bug?" Sometimes, it is a simple matter of misinterpreting what is supposed to happen. Double check with the manual or a local expert.

If you cannot determine what should happen in a given situation by consulting the reference manual, the manual needs to be improved on that topic. Please let us know if you feel that the manual was vague or unclear on a subject.

It is often obvious whether something is a bug or not. If IDL crashes, it is a genuine bug. If however, it draws a plot differently than you would expect or desire, it might be a bug, but it is certainly less obvious. Another question to ask is whether the problem lies within IDL, or with the system running IDL. Is your system properly configured with enough virtual memory and sufficient operating system quotas? Does the system seem stable and is everything else working normally?

Describing The Problem

When describing the problem, it is important to use precise language. Vague terms like "crashes", "blows up", and "fails" are open to many interpretations. Does it really crash IDL and leave you looking at an operating system prompt? This would be our interpretation of "crash." Perhaps, however, it just issues an unexpected error message and gives another prompt. What is really meant by a term like "fails?"

It is also important to separate concrete facts from conjecture about underlying causes. For example, a statement such as "IDL dumps core when allocating dynamic memory." is not nearly as useful as one like "IDL dumps core when I execute the following statements. I think it might be trying to get dynamic memory". The second version tells us exactly what happened. The opinion about what was going on when the problem surfaced is also useful to us, but it helps to have it clearly labeled as such.

Reproducibility

Intermittent bugs are by far the hardest kind to fix. In general, if we can't make it happen on our machine, we can't fix it. It is therefore far more likely that we can help you if you can tell us a sequence of IDL statements that cause the problem to happen. Naturally, there are degrees of reproducibility. Situations where a certain sequence of statements causes the bug 1 time in 3 tries are fairly likely to be fixable. Situations where the bug happens once every few months and no one is sure what triggered it are almost hopeless.

Simplify the Problem

When reporting a bug, it is important to give us the shortest possible series of IDL statements that cause it. The longer and more intricate an example, the less likely it is that we can help. Sometimes a single statement triggers the bug. Often though, the problem surfaces when writing a larger system of inter-related procedures and functions. Such a situation must be simplified before we can tackle it. Take the following steps to simplify your problem:

•	Copy the procedure and function files that are involved to a scratch second copy. Never modify your only copy!

•	Eliminate everything that is not involved in demonstrating the bug. Don't do this all at once. Instead, do it in a series of slow careful steps. Between each step, stop and run IDL on the result to ensure that the bug still appears.

•	If a simplification causes the bug to disappear, restore the statements involved and look for other things to eliminate.

•	If the problem does not involve file Input/Output, strive to eliminate all file I/O statements. Use IDL routines to generate a dummy data set, rather than including your own data. If your bug report does not involve I/O, it will be much easier for us to reproduce. If you have to provide us with a copy of your data, things become more complicated.

On the other hand, if the bug involves file Input/Output, attempt to determine if the problem only happens with a certain file, or with any data. If you are running under VMS, check the file organization using the DCL DIRECTORY/FULL command, and include this information in your report.

The end result of such simplification should be a small number of IDL statements that demonstrate the problem.

Bugs with Dynamic Loading

Under some operating systems, the CALL_EXTERNAL and LINKIMAGE system routines allow you to dynamically load routines written in other languages into IDL. This is a very powerful technique for extending IDL, but it is considerably more difficult than simply writing IDL statements. At this level, the programmer is underneath the user level shell of IDL and is not protected from small programming errors that can corrupt data, give incorrect results, or even crash IDL. In such situations, the burden of proving that a bug is within IDL and not the dynamically loaded code is entirely the programmer's.

Although it is certainly true that a bug in this situation can be within IDL, it is very important that you exhaust all other possibilities before reporting a bug. If you decide that you need to report a bug, the comments above on simplifying things are even more important than usual. If you send us a small example that tickles the bug, we can respond quickly with a correction or advice. Otherwise, we may not even know where to begin.

Sending Data with Your Bug Report

If the statements required to reproduce the bug are more than a few lines or require data files, we will need you to send them to us on magnetic media or via email. Call us for details.

Contact Us

To report a problem, contact us at the following addresses.

Mail

Research Systems, Inc.
2995 Wilderness Place
Boulder, Colorado 80301

Telephone

(303) 786-9900 (Voice)
(303) 786-9909 (Fax)
(303) 413-3920 (IDL technical support direct line)

Electronic Mail

support@rsinc.com


Overview of Objects and Object Graphics

About This Volume

About IDL

IDL Documentation

Typographical Conventions

Reporting Problems

Jump forward to Object Basics

Select "Contents," "Index Search," or "Text Search" from the

Navigate menu, or click the "Help Topics" button,

for more navigational aids.


Object Graphics

This chapter discusses the difference between IDL Direct Graphics and IDL Object Graphics, and provides an overview of the IDL Object Graphics classes.


Direct vs. Object Graphics
Direct versus Object Graphics

Beginning with version 5, IDL supports two types of graphics—IDL Direct Graphics and IDL Object Graphics.


Overview of Object Graphics Classes

The following sections provide an overview of the different types of objects included in the IDL Object Graphics class library. In order to describe the attributes of the IDL's Object Graphics classes, we have grouped the objects into functional categories: Container objects, Structure objects, Atomic Graphic objects, Attribute objects, "Helper" objects, and Destination objects.

Note	These category names are purely descriptive; for example, the category of "structure objects" contains the IDLgrModel, IDLgrScene, and IDLgrView classes, but no class named "structure." There is one exception to this rule: the category of "container objects" includes the IDLContainer class.

This chapter does not describe the relationships between object classes. See "The Graphics Object Hierarchy" on page 25 for a discussion of the object tree.

Naming Conventions

In general, object classes shipped with IDL have names of the form:

IDLxxYyyy

where xx represents the broad functional grouping ("gr" for graphics objects, and "db" for database objects, for example).Yyyy is the class name itself ("Axis" or "Plot," for example). Object classes that are useful in more than one functional context (container objects, for example) omit the functional grouping "code" entirely (IDL_Container). All object classes shipped with IDL are prepended with the letters "IDL"—we strongly suggest that you do not use this prefix when writing your own object classes, as we will continue to add new object classes using this convention.

The typographical convention used to describe IDL objects is slightly different from that used for non-object functions and procedures. Whereas non-object procedures are presented in upper case letters, object classes and methods use mixed case. For example, we refer to the PLOT routine, but to the IDLgrPlot object. Method names are also presented in mixed case (IDLgrAxis::GetProperty).

Common Methods

In addition to their own specific methods, all object classes shipped with IDL have four methods in common: Cleanup, Init, GetProperty, and SetProperty. The Cleanup and Init methods are lifecycle methods, and cannot be called directly except within a subclass' Cleanup or Init method. (See "The Object Lifecycle" on page 7.) The GetProperty and SetProperty methods allow you to inspect (get) or change (set) the various properties associated with a given object. Properties associated with graphics objects include things like color, location, line style, or data.


Container Object

IDL's container object, realized in the IDL_Container class, provides a way to group disparate IDL objects into single object. Container objects provide a convenient way to move or destroy groups of objects; when a container is destroyed, its Cleanup method automatically calls the Cleanup methods of all the objects in the container and destroys them as well.


Structure Objects

Structure objects create a hierarchy of graphic objects—an object tree. Structure objects also contain the information necessary to transform graphics objects in space. Building an object tree allows you to manipulate groups of graphic objects easily by transforming a single IDLgrModel object to which members of the group belong. (See "The Graphics Object Hierarchy" on page 25 for a discussion of the object tree.)

Model

Objects of the IDLgrModel class serve as containers for individual graphic objects (plot lines, axes, text, etc.) and for other model objects. Model objects include a three-dimensional transformation matrix that describes how the model and all of its components are positioned in space. Altering the model's transformation matrix changes the position and orientation of any objects the model contains. If a model object contains another model object, the contained model is positioned according to both its own transformation matrix and that of its container.

See "IDLgrModel" on page 125 for further details.

View

Objects of the IDLgrView class serve as containers for model objects. A view object can be supplied as the argument to a Draw method.

See "IDLgrView" on page 209 for further details.

Scene

Objects of the IDLgrScene class serve as containers for view objects. A scene object can be supplied as the agrument to a Draw method.

See "IDLgrScene" on page 177 for further details.


Atomic Graphic Objects

Atomic Graphic Objects, or graphics atoms, are the low-level objects used to create images. Graphics atoms have attributes such as size, color, width, or associated color palette. Graphics atoms do not include a transformation matrix and do not contain other objects.

Axis

Objects of the IDLgrAxis class are individual axes. One axis object is required for each axis line to be rendered.

See "IDLgrAxis" on page 71 for further details.

Image

Objects of the IDLgrImage class are two-dimensional arrays of data with an associated mapping of the data values to pixel values.

See "IDLgrImage" on page 109 for further details.

Light

Objects of the IDLgrLight class are light sources by which atomic graphic objects are illuminated. Light objects are not actually rendered, but are included as graphics atoms (meaning they must be contained in a model object) so that they can be positioned and transformed along with the graphic objects they illuminate. If no light object is included in a particular view, default lighting is supplied.

See "IDLgrLight" on page 118 for further details.

Plot

Objects of the IDLgrPlot class are individual plot lines, created from a user-supplied vector of dependent data values (and, optionally, a vector of independent data values). Plot objects do not include axes.

See "IDLgrPlot" on page 145 for further details.

Polygon

Objects of the IDLgrPolygon class are individual polygons, created from a user-supplied array of data values.

See "IDLgrPolygon" on page 153 for further details.

Polyline

Objects of the IDLgrPolygon class are individual polylines, created from a user-supplied array of data points. Locations of the data points supplied are connected by a single line.

See "IDLgrPolyline" on page 162 for further details.

Surface

Objects of the IDLgrSurface class are individual three-dimensional surfaces, created from a user-supplied array of data values.

See "IDLgrSurface" on page 183 for further details.

Text

Objects of the IDLgrText class are text strings that can be positioned within the rendering area.

See "IDLgrText" on page 202 for further details.

Volume

Objects of the IDLgrVolume class are map a three-dimensional array of data values to a three-dimensional array of voxel colors, which, when drawn, are projected to two dimensions.

See "IDLgrVolume" on page 216 for further details.


Attribute Objects

Attribute objects are used when rendering graphic objects, but exist outside the hierarchy of Model-View-Scene objects that are actually rendered.

Font

Objects of the IDLgrFont class define the typeface, size, weight, and style of text used when rendering a text object.

See "IDLgrFont" on page 98 for further details.

Palette

Objects of the IDLgrPalette class define a color lookup table that maps indices to red, green, blue, and potentially alpha values.

See "IDLgrPalette" on page 134 for further details.

Pattern

Objects of the IDLgrPattern class defines which pixels are filled and which are left blank when a graphic object is filled.

See "IDLgrPattern" on page 141 for further details.

Symbol

Objects of the IDLgrSymbol class define graphical element that can be used when plotting data.

See "IDLgrSymbol" on page 192 for further details.


Helper Objects

Helper objects alter data in useful ways. They exist outside the he hierarchy of Model-View-Scene objects that are actually rendered.

Tessellate

Objects of the IDLgrTessellator class convert a simple concave polygon (or a simple polygon with "holes") into a number of simple convex plygons (general triangles).

See "IDLgrTessellator" on page 197 for further details.


Destination Objects

Destination objects are objects on which object trees can be rendered (displayed on a screen or printed on a printer).

Printer

Objects of the IDLgrPrinter class represent a hardcopy graphics destination. By default, printer objects represent the default system printer; you can use the IDL routines DIALOG_PRINTJOB and DIALOG_PRINTSETUP to change the printer associated with a printer object.

See "IDLgrPrinter" on page 170 for further details.

Window

Objects of the IDLgrWindow class represent an on-screen area on a display device in which graphic objects can be rendered.

See "IDLgrWindow" on page 226 for further details.


Properties of Objects

IDL's graphics objects have a number of associated properties—things like color, line style, size, etc. Properties are set or changed via keywords; either to the object's Init method (specified when the object is created) or to the object's SetProperty method. If you are familiar with IDL Direct Graphics, many of the keywords used by IDL Object graphics will be familiar to you. Note, however, that unlike IDL Direct Graphics, the IDL Object Graphics system allows you to change the value of an object's properties without re-creating the entire object. (Objects must be redrawn, with a call to the destination object's Draw method, for the changes to become visible.)

Setting Properties at Initialization

Often, you will set an object's properties when creating the object for the first time. Do this by specifying any keywords to the object's Init method directly in the call of OBJ_NEW that creates the object. For example, suppose you are creating a plot and wish to use a red line to draw the plot line. You could specify the COLOR keyword to the IDLgrPlot::Init method directly in the call to OBJ_NEW:

myPlot = OBJ_NEW('IDLgrPlot', xdata, ydata, COLOR=[255, 0, 0])

Remember that in most cases, an object's Init method cannot be called directly. Arguments to OBJ_NEW are passed directly to the Init method when the object is created.

Setting Properties of Existing Objects

After you have created an object, you can set its properties using the object's SetProperty method. For example, the following two statements duplicate the single call to OBJ_NEW shown above:

myPlot = OBJ_NEW('IDLgrPlot', xdata, ydata)

myPlot -> SetProperty, COLOR=[255, 0, 0]

Note	Not all keywords available when the object is being initialized are necessarily available via the SetProperty method. Keywords available when using an object's SetProperty method are noted with the word "Set" in parentheses after the keyword name in the list of keywords to the object's Init method.)

Retrieving Properties Settings

You can retrieve the value of a particular property using an object's GetProperty method. The GetProperty method accepts a list of keyword-variable pairs and returns the value of the specified properties in the variables specified. For example, to return the value of the COLOR property of the plot object in our example, use the statement:

myPlot -> GetProperty, COLOR=plotcolor

This returns the value of the COLOR property in the IDL variable plotcolor.

You can retrieve the values of all of the properties associated with a graphics object by using the ALL keyword to the object's GetProperty method. The following statement:

myPlot -> GetProperty, ALL=allprops

returns an anonymous structure in the variable allprops; the structure contains the values of all of the retrieveable properties of the object.


The  Graphics Object  Hierarchy

Overview

In this chapter we will discuss the organization of a group of graphics objects into a hierarchy or tree. A graphics tree may have any number of branches, each of which in turn may have any number of sub-branches, etc.

For example, a graphics object tree with four graphics atoms might be contained in three separate model objects, which are in turn contained in two distinct view objects, both of which are contained in one scene object. In this example (shown in the figure below), the scene object is the root of the graphics tree.

The advantage of organizing graphic objects into a tree structure is that by manipulating any of the branches of the tree, all of the sub-branches of that branch can be altered simultaneously. In our example, changes to the spatial transformation associated with the model containing two graphics atoms will affect both of the atoms. Similarly, calling a window or printer object's Draw method on the scene object will render all of the objects in the tree to that window or printer.


Scenes

A scene, or instance of the IDLgrScene class, is the root-level object of most graphics trees. Instances of the IDLgrScene class have Add and Remove methods, which allow you to include or remove IDLgrView objects in a scene. A scene object is one of two possible arguments for a destination (window or printer) object's Draw method; the only other object that can be drawn directly is an instance of the IDLgrView class.

It is not necessary to create a scene object if your graphics tree contains only one view object; in that case, the view can serve as the root of the tree.


Views

A view, or instance of the IDLgrView class, can also serve as the root-level object of a graphics tree. Instances of the IDLgrView class have Add and Remove methods, which allow you to include or remove IDLgrModel objects in a view. A view object is one of two possible arguments for a destination (window or printer) object's Draw method; the only other object that can be drawn directly is an instance of the IDLgrScene class.

Every graphics tree must contain at least one view object. Often, it is convenient to divide the objects being rendered into separate views, which are then contained by a scene object.


Models

A model, or instance of the IDLgrModel class, is a container for atomic graphic objects. The model object incorporates a transformation matrix (see "Transformations" on page 29 for an in-depth discussion of transformation matrices) that applies to all of the graphics atoms it contains. In addition to Add and Remove methods, the model object has methods to Rotate, Scale, and Translate the model and its contents.


Graphic Atoms
Atomic Graphic Objects

An atomic graphic object, or graphic atom, is an instance of one of the following classes: IDLgrAxis, IDLgrImage, IDLgrLight, IDLgrPlot, IDLgrPolygon, IDLgrPolyline, IDLgrSurface, IDLgrText, or IDLgrVolume. Graphics atoms combined in a model object (using the model object's Add method) share the same transformation matrix and can be rotated, scaled, or translated together.


Attribute and Helper Objects

Attribute objects are used by atomic graphic objects to define how the graphics atom will be rendered; attribute objects themselves are not drawn, and thus do not need to be added to a model object. Attribute objects are instances of one of the following classes: IDLgrFont, IDLgrPalette, IDLgrPattern, or IDLgrSymbol. For example, a text object (a graphic atom) defines which type style it will be rendered in by setting its FONT property equal to an instance of the IDLgrFont object.

Helper objects are used to change or create data to make it suitable for a particular type of rendering. In IDL version 5.0, there is only one helper object: the tessellator object, which is an instance of the IDLgrTessellator class. The tessellator object changes a simple concave polygon (or a simple polygon with "holes") into a number of simple convex plygons (general triangles) suitable for use by objects of the IDLgrPolygon class.


Object Tree Examples
Examples

The following sections show the IDL code used to create some simple object trees. While you are free to enter the commands shown at the IDL command line, remember that the IDL Object Graphics API is designed as a programmer's interface, and is not as well suited for interactive, ad hoc work at the IDL command prompt as are IDL Direct Graphics.


Simple Plot Example
A Very Simple Plot

The following IDL commands construct a simple plot of an array containing the integers zero through nine, versus the integer indices of the array. The commands shown draw a white line against a the default black background. Note that no axes, title, or other annotations are included; the commands draw only the plot line itself. (This example is purposefully simple; it is meant to illustrate the skeleton of a graphics tree, not to produce a useful plot.)

view = OBJ_NEW('IDLgrView', VIEWPLANE_RECT=[0,-1,100,2])
;Create a view 2 units high by 100 units wide with its origin at (0,-1).

model = OBJ_NEW('IDLgrModel')	;Create a model.

plot = OBJ_NEW('IDLgrPlot', SIN(FINDGEN(100)/10))
;Create a plot line of a sine wave.

window = OBJ_NEW('IDLgrWindow')	;Create a window into which the plot line will be drawn.

model -> ADD, plot	;Add the plot line to the model object.

view -> ADD, model	;Add the model object to the view object.

window -> DRAW, view	;Render the contents of the view object in the window.

To destroy the window and remove the objects created from memory, use the following commands:

OBJ_DESTROY, window	;Note that simply closing a window using its system "close" mechanism does not remove the object from memory.

OBJ_DESTROY, view	;Destroying the view object destroys all of the objects contained in the view.


A More Complicated Tree

The following commands could be used to construct a tree like the one depicted in the figure above.


A Useful Plot


Transformations

Unlike IDL Direct Graphics, the IDL Object Graphics system does not automatically position and size the objects to be rendered. It is up to you, as a programmer, to properly define how your graphic elements will be positioned when rendered.

There are three aspects to this transformation from a "generic" depiction of your data to a representation that can be rendered to an output device (a graphics destination object, such as a window or printer) with the perspective, size, and location you want.

Viewport

The first aspect is the "view" of the graphics objects to be rendered; the size of the viewing area (the viewport), the type of projection used, the position of the viewer's eye as it looks at the graphics objects, and the particular view volume in three-dimensional space that will be rendered to the viewing area. These elements of the "view" of your grapics objecs are, appropriately, controlled by properties of the IDLgrView object being rendered.

Location

The second aspect of the transformation is the location and position of your graphics objects with respect to the viewing area. Graphics objects can be translated, rotated, or scaled by setting the appropriate properties of the IDLgrModel object that contains them.

Note	The two transformations are independent: It is possible, for example, to translate a graphic object so that it is no longer within the viewing area to that is rendered in a window or on a printer.

Coordinate Systems and Scaling

The third aspect of the transformation is the conversion between data, device, and normalized coordinates. The IDL Object Graphics system gives you full control over the which data values are used, which are displayed, and which coordinate systems are used. This means that you must explicitly ensure that the the objects to be rendered and the view object to which they belong use the same coordinate system and are scaled appropriately. The Object Graphics system gives you several ways to accomplish this synchronization.

This chapter discusses the properties and methods used to size and position both your viewing area and the graphics objects you wish to render.


Viewport

One of the first steps in determining how graphics objects will appear when rendered on a graphics destination object is to select the location and dimensions of the rectangular area—the viewport—on the destination in which the rendering will be displayed. Set the location and dimensions of the viewport using the LOCATION and DIMENSIONS keywords to the IDLgrView::Init method when creating the view object (or after creation using the SetProperty method). For example, the following statement creates a view object with a viewport that is 300 pixels square, with its lower left corner located 50 pixels up from the bottom of the destination object:

myView = OBJ_NEW('IDLgrView', LOCATION=[0,50], $

    DIMENSIONS=[300,300])

Both the LOCATION and DIMENSIONS properties of the view object honor the value of the UNITS property, which specifies the type of units in which measurements are made. (Pixels are the default units, so no specification of the UNITS keyword was necessary in the above example.)

The viewport of an existing view can be changed using the SetProperty method:

myView -> SetProperty, LOCATION=[0,0], DIMENSIONS=[200,200]

changes the location of the viewport to have its lower left corner at (0,0) and a size of 200 pixels by 200 pixels.


Projection

When three-dimensional graphics are displayed on a flat computer screen or printed on paper, they must be projected onto the viewing plane. A projection is a way of converting positions in 3D space into locations in the 2D viewing plane. IDL supports two types of projections—parallel and perspective—for each view.

Parallel Projections

A parallel projection projects objects in 3D space onto the 2D viewing plane along parallel rays:

View objects use a parallel projection by default. To explicitly set a view object to use a parallel projection, set the PROJECTION keyword to the IDLgrView::Init method equal to 1 (or use the SetProperty method to set the projection for an exiting view object):

myView -> SetProperty, PROJECTION = 1

Perspective Projections

A perspective projection projects objects in 3D space onto the 2D viewing plane along rays that converge at the eye positon:

Set the PROJECTION keyword to the IDLgrView::Init method equal to 2 (or use the SetProperty method to set the projection for an exiting view object) to use a perspective projection:

myView -> SetProperty, PROJECTION = 2


Eye Position

The eye position is the position along the Z axis from which a set of objects contained in a view object are "seen." Use the EYE keyword to the IDLgrView::Init method to specify the distance from the eye position to the viewing plane (or use the SetProperty method to alter the eye position of an existing view object). The eye position must be a Z value larger than the Z value of the near clipping plane (see "Near and Far Clipping Planes" below) or zero, which ever is greater. That is, the eye must always be located at a positive Z value, and must be outside the volume bounded by the near and far clipping planes.

For example, the following moves the eye position to Z=5:

myView -> SetProperty, EYE=5

Changing the position of the eye has no affect when you are using a parallel projection. Changing the eye position when you are using a perspective projection has a somewhat counter-intuitive affect: moving the eye closer to the near clipping plan causes objects in the volume being rendered to appear smaller rather than larger. To understand why this should be true, consider the following diagram:

In a perspective projection, rays from the graphic objects in the view volume converge at the eye position. When the eye is close to the viewing plane, the projected rays cross the viewing plane (where rendering actually occurs) in a relatively small area. When the eye moves farther from the viewing plane, the projected rays become more nearly parallel and occupy a larger area on the viewing plan when rendered.


View Volume

The view volume defines the three-dimensional volume in space that, once projected, is to fit within the viewport. There are two parts to the view volume: the viewplane rectangle and the near and far clipping planes.

Viewplane Rectangle

The viewplane rectangle defines the bounds in the X and Y directions that will be mapped into the viewport. Objects (or portions of objects) that lie outside the viewplane rectangle will not be rendered.

Use the VIEWPLANE_RECT keyword to the IDLgrView::Init method (or use the SetProperty method if you have already created the view object) to set the location and extent of the viewplane rectangle. Set the keyword equal to a four-element floating-point vector; the first two elements specify the X and Y location of the lower left corner of the rectangle, and the second two elements specify the width and height. The default rectangle is located at (0.0, 0.0) and is one unit wide and one unit high ([0.0, 0.0, 1.0, 1.0]). For example, the following command changes the viewplane rectangle to be located at (-1.0, -1.0) and to be two units square:

myView -> SetProperty, VIEWPLANE_RECT = [-1.0, -1.0, 2.0, 2.0]

Near and Far Clipping Planes

The near and far clipping planes define the bounds in the Z direction that will be mapped into the viewport. Objects (or portions of objects) that lie nearer to the eye than the near clipping plane or farther from the eye than the far clipping plane will not be rendered.

Use the ZCLIP keyword to the IDLgrView::Init method (or use the SetProperty method if you have already created the view object) to set the near and far clipping planes. Set the keyword equal to a two-element floating-point vector that defines the positions of the two clipping planes: [near, far]. The default clippling planes are at Z=1.0 and Z=-1.0 ([1.0, =-1.0]). For example, the following command changes the near and far clipping planes to be located at Z=2.0 and Z=-3.0, respectively:

myView -> SetProperty, ZCLIP = [2.0, -3.0]


Model Transformations

An IDLgrModel object is a container for any graphics atoms that are to be rotated, translated, or scaled. Each IDLgrModel object has a transformation property (set via the TRANSFORM keyword to the IDLgrModel::Init or SetProperty method), which is a 4 x 4 floating-point matrix. For a general discussion of transformation matrices and three-dimensional graphics, .

Note	A model object's transformation matrix is akin to the transformation matrix used by IDL Direct Graphics and stored in the !P.T system variable field. Transformation matrices associated with model object do not use the value of !P.T, however, and are not affected by the T3D procedure used in Direct Graphics.

By default, a model object's transformation matrix is set equal to a 4 x 4 identity matrix:

[[1.0, 0.0, 0.0, 0.0],

 [0.0, 1.0, 0.0, 0.0],

 [0.0, 0.0, 1.0, 0.0],

 [0.0, 0.0, 0.0, 1.0]]

You can change the transformation matrix of a model object directly, using the TRANSFORM keyword to to the IDLgrModel::Init or SetProperty method:

myModel = OBJ_NEW('IDLgrModel', TRANSFORM = tmatrix)

where tmatrix is a 4 x 4 transformation matrix. Alternatively, you can use the Translate, Rotate, and Scale methods to the IDLgrModel object to alter the model's transformation matrix.

Translation

The IDLgrModel::Translate method takes three arguments specifying the amount to translate the model object and its contents in the X, Y, and Z directions. For example, to translate a model and its contents by 1 unit in the X direction, you could use the following statements:

dx = 1 & dy = 0 & dz = 0

myModel -> Translate, dx, dy, dz

How does this affect the transformation matrix? Notice that we could change the transformation matrix in an identical way using the following statements:

dx = 1 & dy = 0 & dz = 0	;Define translation values.

myModel -> GetProperty, TRANSFORM = oldT
;Get existing transformation matrix.

transT = [[1.0, 0.0, 0.0, dx], $

          [0.0, 1.0, 0.0, dy], $

          [0.0, 0.0, 1.0, dz], $

          [0.0, 0.0, 0.0, 1.0]]	;Provide a transformation matrix that performs the translation.

newT = oldT # transT	;Multiply the existing transformation matrix by the matrix that performs the translation.

myModel -> SetProperty, TRANSFORM = newT
;Apply the new transformation matrix to the model object.

Rotation

The IDLgrModel::Rotate method takes two arguments specifying the axis about which to rotate and the number of degrees to rotate the model object and its contents. For example, to rotate a model and its contents by 90 degrees around the Y axis, you could use the following statements:

axis = [0,1,0] & angle = 90

myModel -> Rotate, axis, angle

How does this affect the transformation matrix? Notice that we could change the transformation matrix in an identical way using the following statements:

axis = [0,1,0] & angle = 90	;Define rotation values.

myModel -> GetProperty, TRANSFORM = oldT
;Get existing transformation matrix.

cosa = COS(!DTOR*angle)	;Define sine and cosine of angle.

sina = SIN(!DTOR*angle)

rotT = [[cosa, 0.0, sina, 0.0], $

        [0.0, 1.0, 0.0, 0.0], $

        [-sina, 0.0, cosa, 0.0], $

        [0.0, 0.0, 0.0, 1.0]]	;Provide a transformation matrix that performs the rotation.

newT = oldT # rotT	;Multiply the existing transformation matrix by the matrix that performs the rotation.

myModel -> SetProperty, TRANSFORM = newT
;Apply the new transformation matrix to the model object.

Scaling

The IDLgrModel::Scale method takes three arguments specifying the amount to scale the model object and its contents in the X, Y, and Z directions. For example, to scale a model and its contents by 2 units in the Y direction, you could use the following statements:

sx = 1 & sy = 2 & sz = 1

myModel -> Scale, sx, sy, sz

How does this affect the transformation matrix? Notice that we could change the transformation matrix in an identical way using the following statements:

sx = 1 & sy = 2 & sz = 1	;Define scaling values.

myModel -> GetProperty, TRANSFORM = oldT
;Get existing transformation matrix.

scaleT = [[sx, 0.0, 0.0, 0.0], $

          [0.0, sy, 0.0, 0.0], $

          [0.0, 0.0, sz, 0.0], $

          [0.0, 0.0, 0.0, 1.0]]	;Provide a transformation matrix that performs the scaling.

newT = oldT # scaleT	;Multiply the existing transformation matrix by the matrix that performs the scaling.

myModel -> SetProperty, TRANSFORM = newT
;Apply the new transformation matrix to the model object.

Combining Transformations

Note that model transformations are cumulative. That is, a model object contained in another model is subject to both its own transformation and to that of its container. All transformation matrices that apply to a given model object are multiplied together when the object is rendered. For example, consider a model that contains another model:

model1 = OBJ_NEW('IDLgrModel', TRANSFORM = trans1)

model2 = OBJ_NEW('IDLgrModel', TRANSFORM = trans2)

model2 -> Add, model1

The model1 object is now subject to both its own transformation matrix (trans1) and to that of its container (trans2). The result is that when model1 is rendered, it will be rendered with a transformation matrix = trans1 # trans2


Coordinate Conversion

Most transformations are handled by the transformation matrix of a model object. For convenience, however, graphic atoms may also have a simplified transformation applied to them. Coordinate transformations applied to individual graphic atoms allow you to change only the translation (position) and scale; this is useful when converting from one coordinate system to another. For example, you may build your view object using normalized coordinates, so that values range between zero and one. If you create a graphic object—a surface object, say—based on the range of data values, you would need to convert your surface object (built with a data coordinate system) to match the view object (built with a normal coordinate system). To do this, use the [XYZ]COORD_CONV keywords to the graphic object in question. The [XYZ]COORD_CONV keywords take as their argument a two-element vector that specifies, the translation and scale factor for each dimension.

For example, suppose you have a surface object whose data is specified in a range from [0, 0, zMin] to [xMax, yMax, zMax]. If you wanted to work with this surface as if it were in a normalized [-1, -1, -1] to [1, 1, 1] space, you could use the following coordinate conversions:

myZdata = DIST(60)	;Create some data.

sz = SIZE(myZdata)	;Use the IDL SIZE command to determine the size of each dimension of myZdata.

xs = 2.0/(sz(1)-1)	;Create a scale factor for the X dimension.

ys = 2.0/(sz(2)-1)	;Create a scale factor for the Y dimension.

zs = 2.0/(MAX(myZdata)	;Create a scale factor for the Z dimension.

Now, use the [XYZ]COORD_CONV keywords to the IDLgrSurface::Init method to translate the surface by minus one unit in each direction, and to scale the surface by the scale factors:

mySurface = OBJ_NEW('IDLgrSurface', myZdata, $

    XCOORD_CONV = [-1, xs], YCOORD_CONV = [-1, ys], $

    ZCOORD_CONV = [-1, zs]

Remember that using the [XYZ]COORD_CONV keywords is simply a convenience—the above example could also have been written as follows:

myZdata = DIST(60)	;Create some data.

sz = SIZE(myZdata)	;Use the IDL SIZE command to determine the size of each dimension of myZdata.

xs = 2.0/(sz(1)-1)	;Create a scale factor for the X dimension.

ys = 2.0/(sz(2)-1)	;Create a scale factor for the Y dimension.

zs = 2.0/(MAX(myZdata)	;Create a scale factor for the Z dimension.

myModel = OBJ_NEW('IDLgrModel')	;Create a model object.

myModel -> Scale, xs, ys, zs	;Apply scale factors.

myModel -> Translate, -1, -1, -1	;Translate.

mySurface = OBJ_NEW('IDLgrSurface', myZdata
;Create surface object.

myModel -> Add, mySurface	;Add surface object to model object.


A Simple Example

The following example steps through the process of creating a surface object and all of the supporting objects necessary to display it.

Add standard note on where example filess are stored in the IDL distribution and how to run them.

When creating this procedure, we allow the user to specify keywords that will return object references to the view, model, surface, and window objects. This allows us to manipulate the objects directly from the IDL command line after the procedure has been run.

PRO test_surface, VIEW=oView, MODEL=oModel, $

    SURFACE=oSurface, WINDOW=oWindow

zData = DIST(60)	;Create some data.

;Create a view object. We set the color of the view area to a light grey using the COLOR keyword, and set the viewplane to a square area occupying one unit in each quadrant of the XY plane—a normalized coordinate system—using the VIEWPLANE_RECT keyword.

oView = OBJ_NEW('IDLgrView', COLOR=[60,60,60], $

    VIEWPLANE_RECT=[-1,-1,2,2])

oModel = OBJ_NEW('IDLgrModel')	;Create a model object.

oView->Add, oModel	;Add the model object to the view object.

;Create a surface object. We set the color of the surface to pure red, using the COLOR keyword.

oSurface = OBJ_NEW('IDLgrSurface', zData, color=[255,0,0])

oModel->Add, oSurface	;Add the surface object to the model object.

;Next, we use the GetProperty method of the surface object to retrieve the data range of the surface:

oSurface->GetProperty,XRANGE=xrange,YRANGE=yrange,ZRANGE=zrange

; Scale surface to normalized units and center using the SetProperty method of the surface object to change the [XYZ]COORD_CONV properties.

xs = [-0.5, 1/(xrange[1]-xrange[0])]

ys = [-0.5, 1/(yrange[1]-yrange[0])]

zs = [-0.5, 1/(zrange[1]-zrange[0])]

oSurface->SetProperty,XCOORD_CONV=xs, YCOORD_CONV=ys,$

    ZCOORD_CONV=zs

; Now we rotate the model object to display a standard view.

oModel->Rotate,[1,0,0], -90

oModel->Rotate,[0,1,0], 30

oModel->Rotate,[1,0,0], 30

; Finally, we create a window (destination) object and draw the contents of the view object to it.

oWindow = OBJ_NEW('IDLgrWindow', retain=2  )

oWindow->Draw, oView

END

Play with the example to begin learn how object transformations work and interact. Try the following commands at the IDL prompt to observe what they do:

First, compile test_surface.pro:

.RUN test_surface.pro

Now, execute the procedure. The variables you supply via the SURFACE, MODEL, VIEW, and WINDOW keyword will contain object references you can manipulate from the command line:

test_surface, VIEW=myview, MODEL=mymodel, SURFACE=mysurf, WINDOW=mywin

This will create a window object and display the surface. Now try the following to translate the object to the right:

mymodel -> Translate, -0.2, 0, 0

The model transformation changes as soon as you issue this command. The window object, however, will not be updated to reflect the new position until you issue a Draw command:

mywin -> Draw, myview

Try a rotation inthe Y direction:

mymodel -> Rotate, [0,1,0], 45

mywin -> Draw, myview

Repeat the commands several times and observe what happens.

Try some of the following. Remember to issue a Draw command after each change in order to see what you have done.

mymodel -> Scale, 0.5, 0.5, 0.5

mymodel -> Scale, 1, 0.5, 1

mymodel -> Scale, 1, 2, 1

mymodel -> Rotate, [0,0,1], 45

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

myview -> SetProperty, PROJECTION = 2, EYE = 2

myview -> SetProperty, EYE = 1.1

myview -> SetProperty, EYE = 6


Working with Color

Color is often an integral part of the process of visualizing a dataset. The IDL Object Graphics system allows you to use color in a number of different ways; this chapter explains how to specify color when using Object Graphics and how IDL interacts with the destination devices on which graphics are finally displayed.


Color and Digital Data

Color is used in one of two ways when depicting digital data:

1.	Data values are used to determine color values explicitly. In this case, all data points with a given data value appear as the same color.

2.	Data values are independent of the color used. In this case, each data point must specify its color value independently of its data value, and data points with identical data values may have different color values.

In the first case, a color lookup table is generally used to assign data values to color values. For example, suppose a data set consists of temperature values. The explicit data (temperature) values could be mapped directly, one-to-one, with color values in a table. When displayed, all data points representing the same temperature would appear the same color. Color lookup tables are familiar, in concept, to users of IDL Direct Graphics—IDL's Direct Graphics color tables are implementations of the color lookup table.

In the second case, red, green, and glue (RGB) values are assigned explicitly to each data point. Image files generally use an RGB color scheme, where each pixel in an image has an associated color value that has no relationship to its data value.

The IDL Object Graphics system provides two color models for you to choose between when creating destination (window or printer) objects: an Indexed Color Model and an RGB Color Model. Indexed color allows you to map data values to color values using a color palette. RGB color allows you to specify color values explicitly, using an RGB triple. (See "Specifying RGB Values" on page 44 for more information on RGB triples.) You choose one of these two color models to associate with each destination object.

Finally, the devices on which graphics are rendered—computer displays, printers, plotters, frame buffers, etc.—support one or more color models. IDL performs any conversions necessary to support either the Indexed or RGB color model on any physical device. That is, the color model used by IDL is entirely independent of the color model used by the physical device. "How IDL Interprets Color Values" on page 45 explains how IDL's Object System color models interact with different device color models.

Note	You can specify the color of any graphic object using either a color index or an RGB value, regardless of the color model used by the destination object or the physical destination device. See "Using Color" on page 44 for details.


Indexed Color Mode
Indexed Color Model

In the Indexed color model, you have control over how colors are loaded into a color lookup table. You do this by specifying a palette, which maps color index values into RGB values, for the destination object. When the contents of your destination object are rendered on the physical device (that is, when you call the Draw method for the destination object), the RGB values from the palette are either:

•	passed directly through to the physical device (if it uses RGB values), or

•	loaded into the physical device's lookup table (if it uses Indexed values).

Specify that a destination object should use the Indexed color model by setting the COLORMODEL property of the object equal to 1 (one):

myWindow = OBJ_NEW('IDLgrWindow', COLORMODEL = 1)

Specify a palette object by setting the PALETTE property equal to an object of the IDLgrPalette class:

myWindow -> SetProperty, PALETTE=myPalette

If you do not specify a palette object for a destination object that uses the Indexed color model, a grayscale ramp palette is loaded automatically.

When you assign a color index to an object that is drawn on the destination device, the color index is used to look up an RGB value in the specified palette. When you assign an RGB value to an object that is drawn on the destination device, the nearest match within the destination object's palette is found and used to represent that color.


RGB Color Model

In the RGB color model, IDL takes responsibility for filling the color lookup table on the destination device (if necessary). When the contents of your destination object are rendered on the physical device (that is, when you call the Draw method for the destination object), the RGB values are either:

•	passed directly through to the physical device (if it uses RGB values), or

•	loaded into the physical device's lookup table (if it uses Indexed values).

Specify that a destination object should use the RGB color model by setting the COLORMODEL property of the object equal to 0 (zero):

myWindow = OBJ_NEW('IDLgrWindow', COLORMODEL = 0)

This is the default for newly-created destination objects.


Color and Destination Objects

Each destination object has a one of the two color models described above associated with it. Destination objects use the Indexed color model if the COLORMODEL property is set equal to 1 (one) or the RGB color model if the COLORMODEL property is set equal to 0 (zero, the default). Once a destination object has been created, you cannot change the associated color model.

You can, however, create destination objects that use different color models in the same IDL session. That is, it is possible to have two window objects—one using the Indexed color model and one using the RGB color model—on your computer screen at the same time.

Remember also that you can specify the color of any graphic object using either a color index or an RGB value, regardless of the color model used by the destination object or the physical destination device. The main distinction between the two color models lies in how IDL manages the color lookup table (if any) of the physical destination device. See "Using Color" on page 44 for details.


Palettes

Objects of the IDLgrPalette class are used to create color lookup tables. The following statements create a palette object that reverses a standard grayscale ramp palette:

rval = (gval = (bval = REVERSE(INDGEN(256))))

myPalette = OBJ_NEW('IDLgrPalette', rval, gval, bval)

Palettes can be associated either with graphics destination objects (windows or printers) or with individual graphic atoms:

myWindow -> SetProperty, PALETTE=myPalette

or

myImage -> SetProperty, PALETTE=myPalette

Note	Palettes associated with graphic atoms are only used when the destination object's uses an RGB color model; if the destination object uses an Indexed color model, the destination object's palette is always used.

See "IDLgrPalette" on page 134 for details on creating palette objects.


Using Color

The color of a graphic object is specified by the COLOR property of that object. You can set the color of an object either when the object is created or afterwards. For example, the following statement creates a view object and sets its color value to the RGB triple [60, 60, 60] (a dark grey).

myView = OBJ_NEW('IDLgrView', COLOR = [60, 60, 60])

The following statement changes the color value of an existing axis object to the color value specified for entry 100 in the color palette associated with the axis object.

myAxis -> SetProperty, COLOR=100

Remember that color palettes associated with individual graphic atoms are only used when the destination object uses an RGB color model.

Specifying RGB Values

RGB values are specified with RGB triples. An RGB triple is a three-element vector of integer values, [r, g, b], generally ranging between 0 and 255. A value of zero is the darkest possible value for each of the three channels—thus an RGB triple of [0, 0, 0] represents black, [0, 255, 0] represents bright green, and [255, 255, 255] represents white.

For example, suppose we create a plot line with the following statements:

myWindow = OBJ_NEW('IDLgrWindow')

myView = OBJ_NEW('IDLgrView', VIEWPLANE_RECT=[0, 0, 10, 10])

myModel = OBJ_NEW('IDLgrModel')

myPlot = OBJ_NEW('IDLgrPlot', FINDGEN(10), THICK = 5, $

     COLOR=[255, 255, 255])

myModel -> Add, myPlot

myView -> Add, myModel

myWindow -> Draw, myView

Notice the following aspects of the above example:

1.	The newly-created window (destination) object uses an RGB color mode (the default).

2.	The default color of the view object—the background against which the plot line is drawn—is black ([0, 0, 0]).

3.	The default color of the plot object (and all objects, for that matter) is also black. This means that it is necessary to specify a color other than black for the object if we wish it to show up against the black background.

Try changing the colors with the following statements:

myPlot -> SetProperty, COLOR = [150, 0, 150]

myView -> SetProperty, COLOR = [75, 250, 75]

myWindow -> Draw, myView


How IDL Interprets Color Values

IDL determines colors to display differently based on whether the destination object uses an Indexed or RGB color model, and on whether the physical destination device supports an Indexed or RGB color model.

Indexed Color Model

If the destination object uses an Indexed color model, the color displayed is calculated from the value specified by the object's COLOR property as follows:

If a Color Index is Specified

•	If the physical device uses an Indexed color model, the specified color index is used as an index into the physical device's lookup table. (Remember that the physical device's color lookup table is loaded via the PALETTE keyword to the destination object.)

•	If the physical device uses an RGB color model, the specified color index is used as an index into the destination object's palette. The RGB triple stored at the index's location in the palette is used as the physical device's color value.

If an RGB Triple is Specified

•	If the physical device uses an Indexed color model, the RGB triple is mapped to the index of the nearest match in the device's color lookup table.

•	If the physical device uses an RGB color model, the RGB triple is passed directly to the device.

RGB Color Model

If the destination object uses an RGB color model, the color displayed is calculated from the value specified by the object's COLOR property as follows:

If a Color Index is Specified

If the graphic object for which the color is being determined has a palette associated with it, the RGB triple at that palette's color index is retrieved. Otherwise, the RGB triple at the specified index in the destination object's palette is retrieved.

•	If the physical device uses an Indexed color model, the RGB triple retrieved is mapped to the index of the nearest match in the device's color lookup table.

•	If the physical device uses an RGB color model, the RGB triple retrieved is passed directly to the device.

If an RGB Triple is Specified

•	If the physical device uses an Indexed color model, the RGB triple is mapped to the index of the nearest match in the device's color lookup table.

•	If the physical device uses an RGB color model, the RGB triple is passed directly to the device.


Using Attributes and Helpers

Attribute objects are not rendered directly, but are used to determine how graphic objects will be rendered. There are four attribute object classes: IDLgrFont, IDLgrPalette, IDLgrPatter, and IDLgrSymbol.

Helper objects perform operations on object instance data. There is one helper object class: IDLgrTessellator.


Font Objects

Font objects allow you to specify the type style and size used when rendering objects of the IDLgrText class. You can use vector fonts (either PostScript or IDL's built-in Hershey vector fonts) or, in some cases, raster fonts.

Fonts used by font objects are specified in a string constant constructed from a font name and one or more optional modifiers. The font name is the name by which your computer system knows the font ("Times" for the Times Roman font, for example). Modifiers specify the weight, angle, and other attributes of the font ("Bold" specifies a weight, "italic" an angle). The font name string looks like this:

'fontname*weight*angle*other_modifiers'

For example, the font name string for Helvetica bold italic is:

'helvetica*bold*italic'

The font name string for Times Roman Regular is:

'times'

While the font name must come first in the font name string, the order in which the modifiers are specified is not important.

PostScript Fonts

IDL provides four PostScript fonts for use in font objects: Helvetica, Times, Courier, and Symbol.

Note	IDL for VMS does not support PostScript fonts. Fonts objects that use PostScript fonts will be converted to use Hershey fonts when rendered on a VMS system.

The four PostScript fonts provided by IDL support the following modifiers:

•	Helvetica: Bold, Italic

•	Times: Bold, Italic

•	Courier: none

•	Symbol: none

Hershey Fonts

IDL supplies a set of vector fonts designed by Dr. A.J. Hershey.

You can use Hershey fonts when creating font objects by specifying a fontname of the form: "Hershey*fontnum" to the IDLgrFont::Init method. See chapter 6 of the IDL Reference Guide for further information.

Raster Fonts

Some systems (notably those that use the X-Window System window manager) allow you to use raster fonts. Use the Unix command xlsfonts to display a list of raster fonts supported by your system. To use a raster font, specify the font name (as displayed by the xlsfonts command) as the font name string when creating an IDLgrFont object.

Creating Font Objects

Specify a font name string when you create a font object. You can also specify a size, in points, for the font upon creation. For example, the following statement creates a font object using a bold version of the Times Roman font, with a size of 20 points:

myFont = OBJ_NEW('IDLgrFont', 'times*bold', SIZE=20

Note	You cannot change the font name of an existing font object via the SetProperty method. You can, however, change the point size:

myFont -> SetProperty, SIZE=36

To create a font object using a Hershey font, omit the font name string and specify the Hershey font's index number with the HERSHEY keyword to the IDLgrFont::Init method. The following statement creates a font object using the Duplex Roman Hershey font, with a size of 14 points:

myHersheyFont = OBJ_NEW('IDLgrFont', HERSHEY=5, SIZE=14)

Using Font Objects

To use a font object, use the FONT keyword to the IDLgrText::Init method (or change the text object's font via the SetProperty method):

myText = OBJ_NEW('IDLgrText', 'Ay, Carumba', FONT = myFont)

or

myText -> SetProperty, FONT=myHersheyFont

If no font object is specified, IDL uses the Helvetica font with a size of 12 points.


Palette Objects

Objects of the IDLgrPalette class are used to create color lookup tables. Color lookup tables assign indivual numerical values to color values; this allows you to specify the color of a grahpic object with a single number (a color index) rather than explicitly providing the red, green, and blue color values (an RGB triple). Palettes are most useful when you want data values to correspond to color values—that is, if you want a data value of 200, for example, to always correspond to a single color. This correspondence is one of the main uses of the Indexed Color Model. See "Indexed Color Model" on page 42 for additional discussion of indexed color and its uses.

Creating Palette Objects

Specify three vectors representing the red, green, and blue values for the palette when you call the IDLgrPalette::Init method. The values in the red, green, and blue vectors must be integers between zero and 255, and the length of each vector must not exceed 256 elements. For example, the following statements create a palette object that reverses a standard grayscale ramp palette:

rval = (gval = (bval = REVERSE(INDGEN(256))))

myPalette = OBJ_NEW('IDLgrPalette', rval, gval, bval)

See "IDLgrPalette" on page 134 for details on creating palette objects.

Using Palette Objects

Palettes can be associated either with graphics destination objects (windows or printers) or with individual graphic atoms:

myWindow -> SetProperty, PALETTE=myPalette

or

myImage -> SetProperty, PALETTE=myPalette

Note	Palettes associated with graphic atoms are only used when the destination object's uses an RGB color model; if the destination object uses an Indexed color model, the destination object's palette is always used. See "How IDL Interprets Color Values" on page 45 for details.


Pattern Objects

Objects of the IDLgrPattern class are used to fill objects of the IDLgrPolygon class. Pattern objects can create a solid fill (the default), a line fill (with control over the orientation, spacing, and thickness of the lines used), or a pattern fill (using a byte pattern you specify). Pattern objects do not have a color of their own; patterns take their color from the COLOR property of the polygon they fill.

Creating Pattern Objects

Specify a fill-pattern style when you call the IDLgrPattern::Init method. Set the argument to the Init method equal to zero to create a line pattern, equal to one to create a solid fill, or equal to three to use a bitmap byte array as the fill pattern. For example, the following statment creates a pattern object with lines one centimeter apart, 5 pixels wide, at an angle of 30 degrees:

myPattern = OBJ_NEW('IDLgrPattern', 0, SPACING=1, THICK=5, $

    ORIENTATION=30)

The following statment creates a pattern object with a solid fill:

myPattern = OBJ_NEW('IDLgrPattern', 1)

To create a pattern fill, specify a 32 x 4 byte array via the PATTERN property of the pattern object. The byte array you specify will be tiled over the area of the polygon to be filled. For example, the following statements create a pattern fill with a random speckle. The first statement creates a 32 x 4 byte array with random values ranging between 0 and 255. The second statement creates the pattern object.

pattern = BYTE(RANDOMN(seed, 32, 4)*255)

myPattern = OBJ_NEW('IDLgrPattern', 2, PATTERN=pattern)

Using Pattern Objects

To fill a polygon with the pattern specified by a pattern object, set the FILL_PATTERN property equal to the pattern object reference:

myPolygon -> SetProperty, FILL_PATTERN = myPattern

The following statements create a triangle and fill it with the random speckle pattern:

pattern = BYTE(RANDOMN(seed, 32, 4)*255)

myPattern = OBJ_NEW('IDLgrPattern', 2, PATTERN=pattern)

myView = OBJ_NEW('IDLgrView', VIEWPLANE_RECT=[0,0,10,10])

myModel = OBJ_NEW('IDLgrModel')

myPolygon = OBJ_NEW('IDLgrPolygon', [4, 7, 3], [8, 6, 3],$

    color=[255,0,255], fill_pattern=myPattern)

myView -> Add, myModel

myModel -> Add, myPolygon

myWindow = OBJ_NEW('IDLgrWindow')

myWindow -> Draw, myView


Symbol Objects

Objects of the IDLgrSymbol class are used to display individual data points, either in an IDLgrPlot object or an IDLgrPolyline object. You can create symbol objects that display one of seven pre-defined symbols, any atomic graphic object, or any model object.

Creating Symbol Objects

Specify the type of symbol to use when you call the IDLgrSymbol::Init method.

To Use a Pre-defined Symbol

Specify one of the following values for the symbol type:

•	1 = Plus sign(the default)

•	2 = Asterisk

•	3 = Period

•	4 = Diamond

•	5 = Triangle

•	6 = Square

•	7 = X

For example, to create a symbol object using a red triangle for the symbol, use the following statement:

mySymbol = OBJ_NEW('IDLgrSymbol', 5, COLOR=[255,0,0])

To Use a Graphic Object as a Symbol

You can use an atomic graphic object or a model object as a symbol. For best results, create an object that fills the domain between -1 and 1 in all directions. For example, the following statements create a polygon object in the shape of a pentagon and define a symbol object to use the polygon:

pentagon=OBJ_NEW('IDLgrPolygon', [-0.8,0.0,0.8,0.4,-0.4], $

    [0.2,0.8,0.2,-0.8,-0.8], COLOR=[0,0,255])

mySymbol = OBJ_NEW('IDLgrSymbol', pentagon)

Note that we create the pentagon to fit in the plane between -1 and 1 in both the X and Y directions. We could also have created the pentagon to fit in a unit square and then scaled it to fit the domain between -1 and 1. For example:

pentagon=OBJ_NEW('IDLgrPolygon', [0.1,0.5,0.9,0.7,0.3], $

    [0.6,0.9,0.6,0.1,0.1], COLOR=[0,0,255])

symModel = OBJ_NEW('IDLgrModel')

symModel -> Add, pentagon

symModel -> Scale, 2, 2, 1

symModel -> Translate, -1, -1, 0

mySymbol = OBJ_NEW('IDLgrSymbol', symModel)

Note that we create the symbol object to use the model object rather than the polygon object. Using a model object as a symbol allows you to apply transformations to the symbol even after it has been created.

Setting Size

By default, symbols extend one unit to each side of the data point they represent. Set the SIZE property of the symbol object to a two-element vector that describes the scaling factor in X and Y to apply to the symbol to change the size of the symbols that are rendered. For example, to scale a symbol so that it extends one tenth of a unit to each side of the data point, use the statement:

mySymbol -> SetProperty, SIZE=[0.1, 0.1]

Setting Color

If you are using a pre-defined symbol, you can set its color using the COLOR property of the symbol object. If you are using a graphic object as a symbol, the symbol's color is determined by the color of the graphic object and the setting of the COLOR property of the symbol object itself is ignored. For example, the following statments create a symbol object that uses a red triangle:

mySymbol = OBJ_NEW('IDLgrSymbol', 5, COLOR=[255,0,0]

Using Symbol Objects

To use a symbol, set the SYMBOL property of an IDLgrPlot or IDLgrPolyline object equal to the symbol object reference:

myPlot -> SetProperty, SYMBOL=mySymbol

Suppose you wish to create a symbol object using the pentagon we created above. Suppose also that you wish to be able to use the pentagon code in more than one instance, and would like to be able to make changes to the pentagon object's color, size, and orientation. You might create a procedure like the following to define a pentagon object contained in a model object, and return the object references.

PRO penta, COLOR=color, SYMBOL=symbol, MODEL=model
;Allow user to set the color and retrieve the object references to the symbol, and model objects created.

IF KEYWORD_SET(color) THEN COLOR=color ELSE COLOR=[0,0,255]
;If the color keyword is set, use the specified color. Otherwise, use blue.

model = OBJ_NEW('IDLgrModel')	;Create a model object.

symbol = OBJ_NEW('IDLgrPolygon', [-0.8, 0.0, 0.8, 0.4, -0.4], $

    [0.2, 0.8, 0.2, -0.8, -0.8], COLOR=color)
;Create a polygon that takes up most of the domain between -1 and 1 in the X and Y directions. Set its color.

model -> ADD, symbol	;Add the polygon to the model.

END

Once you have compiled the penta procedure, call it with the SYMBOL and MODEL keywords set equal to named variables that will contain the object references of the model and polygon objects:

PENTA, SYMBOL=sym, MODEL=symmodel

Next, create a symbol object using the pentagon:

mySymbol = OBJ_NEW('IDLgrSymbol', symmodel)

Now, create a plot object using the pentagon as the plot symbol:

myPlot = OBJ_NEW('IDLgrPlot', FINDGEN(10), SYMBOL=mySymbol)

Next, display the plot:

myView = OBJ_NEW('IDLgrView', VIEWPLANE_RECT=[0,0,10,10])

myModel = OBJ_NEW('IDLgrModel')

myView->Add, myModel

myModel -> Add, myPlot

myWindow = OBJ_NEW('IDLgrWindow')

myWindow -> Draw, myView

Note that the plotting symbols are larger than you might wish. Try making them smaller:

mySymbol -> SetProperty, SIZE=[0.2,0.2]

myWindow -> Draw, myView

Or, create the following procedure to spin the pentagons around the Z axis (enter .RUN at the command prompt, followed by these statements):

PRO SPIN, model, view, window, steps

FOR i = 0, steps do begin

    model -> Rotate, [0,0,1], 10

    window -> Draw, view

END

END

After compiling the SPIN procedure, call it from the command line and watch the pentagons spin:

SPIN, symmodel, myView, myWindow, 100

While it is unlikely that you will wish to create spinning plot symbols, this example demonstrates one of the key advantages of IDL Object Graphics over IDL Direct Graphics—once created, graphics objects can be easily manipulated in a variety of ways without the need to recreate the entire graph or image after each change.


Tessellator Objects

The IDLgrTessellator class is a "helper" class that converts a simple concave polygon (or a simple polygon with "holes") into a number of simple convex polygons (general triangles). A polygon is simple if it includes no duplicate vertices, if the edges intersect only at vertices, and exactly two edges meet at any vertex.

Using Tesselator Objects


Working with Axes and Text

This chapter will describe the use of axis and text objects..


Working with Plots and Graphs

This chapter will describe the use of polygon, polyline, plot, and surface objects to create graphs.


Working with Volumes

This chapter will describe the process of creating and displaying volume objects..


Working with Images

This chapter will describe the use of image objects..


Selection and Direct Manipulation

This chapter will describe the IDL Object Graphics selection and direct manipulation features.


Source and Destination Objects

This chapter will describe the configuration and use of source and destination objects..


IDL Graphics
Class Library

This chapter describes IDL's built-in graphics class library. Conventions used in this chapter are described below.

How to Use this Chapter

The elements of IDL's graphics class library are documented alphabetically in this chapter. The page or pages describing each class include references to sub- and super-classes, and to the methods associated with the class. Class methods are documented alphabetically following the description of the class itself.

A description of each method follows its name. Beneath the general description of the method are a number of sections that describe the calling sequence for the method, its arguments (if any), its keywords (if any). These sections are described below.

Calling Sequence

The "Calling Sequence" section shows the proper syntax for calling the method.

Procedure Methods

IDL procedure methods have the calling sequence:

Obj -> PROCEDURE_NAME, Argument [, Optional_Arguments]

where Obj is a valid object reference, PROCEDURE_NAME is the name of the procedure method, Argument is a required parameter, and Optional_Argument is an optional parameter to the procedure method. Note that the square brackets around optional arguments are not used in the actual call to the procedure, they are simply used to denote the optional nature of the arguments within this document.

Function Methods

IDL function methods have the calling sequence:

Result = Obj -> FUNCTION_NAME(Argument [, Optional_Arguments])

where Obj is a valid object reference, Result is the returned value of the function method, FUNCTION_NAME is the name of the function method, Argument is a required parameter, and Optional_Argument is an optional parameter. Note that the square brackets around optional arguments are not used in the actual call to the function, they are simply used to denote the optional nature of the arguments within this document. Note also that all arguments and keyword arguments to functions should be supplied within the parentheses that follow the function's name.

Arguments

The "Arguments" section describes each valid argument to the method. Note that these arguments are positional parameters that must be supplied in the order indicated by the method's calling sequence.

Named Variables

Often, arguments that contain values upon return from the function or procedure method ("output arguments") are described as accepting "named variables". A named variable is simply a valid IDL variable name. This variable does not need to be defined before being used as an output argument. Note, however that when an argument calls for a named variable, only a named variable can be used—sending an expression causes an error.

Keywords

The "Keywords" section describes each valid keyword argument to the method. Note that keyword arguments are formal parameters that can be supplied in any order.

Keyword arguments are supplied to IDL methods by including the keyword name followed by an equal sign ("=") and the value to which the keyword should be set. Note that keywords can be abbreviated to their shortest unique length. For example, the XSTYLE keyword can be abbreviated to XST.

Setting Keywords

When the documentation for a keyword says something similar to, "Set this keyword to enable logarithmic plotting," the keyword is simply a switch that turns an option on and off. Usually, setting such keywords equal to 1 causes the option to be turned on. Explicitly setting the keyword to zero (or not including the keyword) turns the option off.

There is a "shortcut" that can be used to set a keyword equal to 1 without the usual syntax (i.e., KEYWORD=1). To "set" a keyword, simply preface it with a slash character ("/"). For example, to plot a wire mesh surface with a skirt around it, set the SKIRT keyword to the SURFACE routine as follows:

SURFACE, DIST(10), /SKIRT

Creating Objects from the Graphics Class Library

To create an object from the IDL Graphics Class Library, use the OBJ_NEW function (see "OBJ_NEW" on page 636 of the IDL Reference Guide). The Init method for each class describes the arguments and keywords available when you are creating a new graphics object. Note that in some cases, you can also use the Init method after the object has been created.

For example, to create a new graphics object from the IDLgrAxis class, use the following call to OBJ_NEW along with the arguments and keywords accepted by the IDLgrAxis::Init method:

myAxis = OBJ_NEW(IDLgrAxis, DIRECTION='X', RANGE=[0.0,40.0])


Navigational Aids
Documentation for IDL Graphics Class Library is arranged alphabetically. You can browse through the routines individually, or consult

one of the following indices:

Alphabetical List of Routines

List of Routines by Application

Alphabetical List of Objects

Select "Contents," "Keyword Search," or "Text Search" from the Navigate menu, or click the "Help Topics" button,

for more navigational aids.


IDL_Container

Doc for container object still to come.


IDLgrAxis

An axis object represents a single vector that may include a set of tick marks, tick labels, and a title.

An IDLgrAxis 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.

Note	An IDLgrAxis object can not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrAxis::Init (page 74).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrAxis::Cleanup (page 71)

•	IDLgrAxis::GetCTM (page 72)

•	IDLgrAxis::GetProperty (page 73)

•	IDLgrAxis::Init (page 74)

•	IDLgrAxis::SetProperty (page 78)


IDLgrAxis::Cleanup

The IDLgrAxis::Cleanup procedure method performs all cleanup on the object. IDLgrAxis is described on page 71.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrAxis::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrAxis::GetCTM

The IDLgrAxis::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrAxis is described on page 71.

Calling Sequence

Obj->[IDLgrAxis::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrAxis::GetProperty

The IDLgrAxis::GetProperty procedure method retrieves the value of a property or group of properties for the axis. IDLgrAxis is described on page 71.

Calling Sequence

Obj ->[IDLgrAxis::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrAxis::Init (page 74) followed by the word "Get" can be retrieved using IDLgrAxis::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

CRANGE

Set this keyword to a variable that will contain the actual full range of the axis as a vector of the form [minval, maxval]. This range may not exactly match the requested range provided via the RANGE keyword in the Init and Setproperty methods. Adjustments may have been made to round to the nearest even tick interval or to accommodate the EXTEND keyword.

PARENT

Set this keyword to return a reference to the parent of the object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by the graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrAxis::Init

The IDLgrAxis::Init function method initializes an axis object. IDLgrAxis is described on page 71.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrAxis' [, Direction])

or

Result = Obj -> [IDLgrAxis::]Init([Direction])         (In a subclass' Init method only.)

Arguments

Direction

An integer value specifying which axis is being created. Specify 0 (zero) to create an X axis, 1 (one) to create a Y axis, or 2 to create a Z axis.

Keywords

Properties retrievable via IDLgrAxis::GetProperty (page 73) are indicated by the word "Get" following the keyword. Properties settable via IDLgrAxis::SetProperty (page 78) are indicated by the word "Set" following the keyword.

COLOR (Get, Set)

Set this keyword to the color to be used as the foreground color for this axis.  The color may be specified as a color lookup table index (accepted by graphics destinations using either the Color Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).  The default is [255, 255, 255]

DIRECTION (Get, Set)

Set this keyword to a variable that will contain a string ("X", "Y", or "Z") that indicates the direction of the axis. This keyword is the same as the optional Direction argument.

EXACT (Get, Set)

Set this keyword to force the axis range to be exactly as specified.  If this keyword is not set, the range may be lengthened or shortened slightly to allow for evenly spaced tick marks.

EXTEND (Get, Set)

Set this keyword to a nonzero value to extend the axis beyond the range.

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

 The default is `Copy'.  Valid values include the following:

•	0 = Copy: Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

GRIDSTYLE (Get, Set)

Set this keyword to a long integer bitmask describing the linestyle pattern to be repeated over the length of the tickmark, which can extend the length of the orthogonal axis. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. An example of a valid value is '3F07'X, which describes a linestyle consisting of a long dash followed by a short dash. The default is a solid line, represented by 'ffffffff'X.

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

LOCATION (Get, Set)

Set this keyword to a two- or three-element vector of the form [x, y] or [x, y, z] to specify the coordinate through which the axis should pass. The default is [0, 0, 0].

LOG (Get, Set)

Set this keyword to indicate that the axis is logarithmic.

MAJOR (Get, Set)

Set this keyword to an integer representing the number of major tick marks.  The default is 0, specifying that IDL will compute the number of tickmarks. If the TICKVALUES keyword is provided, the vector of data values specified therein is used.

MINOR (Get, Set)

Set this keyword to an integer representing the number of minor tick marks.  Set this value to -1 to suppress minor tickmarks. The default is 0, specifying that IDL will compute the number of tickmarks.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

NOTEXT (Get, Set)

Set this keyword to prevent the tick labels and the axis title from being drawn.

RANGE (Get, Set)

Set this keyword to a two-element vector containing the minimum and maximum data values covered by the axis.  The default is [0.0, 1.0].

SUBTICKLEN (Get, Set)

Set this keyword to a scale ratio specifying the length of minor tick marks relative to the length of major tick marks. The default is 0.5, specifying that the minor tick mark is one-half the length of the major tick mark.

THICK (Get, Set)

Set this keyword to indicate the line thickness used to draw the axis, in pixels.  The default is 1.0 pixels.

TICKDIR (Get, Set)

Set this keyword to either zero or one to indicate the tick mark direction. For an X axis, setting TICKDIR=0 means the tick marks will be drawn above the X axis, in the direction of the positive Y axis (this is the default); setting TICKDIR=1 means the tick marks will be drawn below the X axis. For a Y axis, setting TICKDIR=0 means the tick marks will be drawn to the right of the Y axis, in the direction of the positive X axis (this is the default); setting TICKDIR=1 means the tick marks will be drawn to the left of the Y axis. For a Z axis, setting TICKDIR=0 means the tick marks will be drawn to the right the Z axis, in the direction of the positive X axis (this is the default); setting TICKDIR=1 means the tick marks will be drawn to the left of the Z axis.

TICKFORMAT (Get, Set)

Set this keyword to a format string or a string containing the name of a function that returns a string to be used to format the axis tick mark labels.  The default is "", the null string.

TICKLEN (Get, Set)

Set this keyword to the length of each major tick mark, measured in data units. The recommended, and default, tick mark length is 0.2.

TICKTEXT (Get, Set)

Set this keyword to either a single instance of the IDLgrText object class (with multiple strings) or to a vector of instances of the IDLgrText object class (one per major tick) to specify the annotations to be assigned to the tickmarks. By default, with TICKTEXT set to 0, IDL computes the tick labels based on major tick values. The positions of the provided text objects may be overwritten; position is determined according to tick mark location.

TICKVALUES (Get, Set)

Set this keyword to a vector of data values representing the values at each tick mark. If TICKVALUES set to 0, the default, IDL computes the tick values based on the axis range and the number of major ticks.

TITLE (Get, Set)

Set this keyword to an instance of the IDLgrText object class to specify the title for the axis.  The default is the null object, specifying that no title is drawn. The location may be overwritten if centered along the axis.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].


IDLgrAxis::SetProperty

The IDLgrAxis::SetProperty procedure method sets the value of a property or group of properties for the axis. IDLgrAxis is described on page 71.

Calling Sequence

Obj ->[IDLgrAxis::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrAxis::Init (page 74) followed by the word "Set" can be retrieved using IDLgrAxis::SetProperty.


IDLgrFont

A font object represents the typeface, style, weight, and size that may be associated with text objects.

Superclasses

This class has no superclass.

Subclasses

This class has no subclasses.

Creation

See IDLgrFont::Init (page 100).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrFont::Cleanup (page 98)

•	IDLgrFont::GetProperty (page 99)

•	IDLgrFont::Init (page 100)

•	IDLgrFont::SetProperty (page 102)


IDLgrFont::Cleanup

The IDLgrFont::Cleanup procedure method performs all cleanup on the object. IDLgrFont is described on page 98.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrFont::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrFont::GetProperty

The IDLgrFont::GetProperty procedure method retrieves the value of a property or group of properties for the font. IDLgrFont is described on page 98.

Calling Sequence

Obj->[IDLgrFont:]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrFont::Init (page 100) followed by the word "Get" can be retrieved using IDLgrFont::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.


IDLgrFont::Init

The IDLgrFont::Init function method initializes the font object. IDLgrFont is described on page 98.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrFont' [, Fontname])

or

Result = Obj -> [IDLgrFont::]Init([Fontname])         (In a subclass' Init method only.)

Arguments

Fontname

A string representing the name of the font to be used.  This string should take the form 'fontname*modifier1*modifier2*...*modifierN'.  All graphics destinations support the following fontnames: Helvetica, Courier, Times, Symbol.  Valid modifiers for each of these fonts (except Symbol) are:

•	Font weight: Bold

•	Font angle: Italic

To select a Hershey font, use a fontname of the form: "Hershey*fontnum". See chapter 6 of the IDL Reference Guide for further information.

Example	'Helvetica*Bold*Italic'

X Windows Only

X Windows users may use the xlsfonts Unix command to see a list of fonts supported by their system.  '8X13' might be a valid fontname.

Valid modifiers are:

•	Font weight: Bold, Medium, Demibold

•	Font angle: Italic, Oblique

•	Font width: Condensed, Narrow

Microsoft Windows Only

Valid modifiers are:

•	Font weight: Thin, Light, Bold, Heavy

•	Font quality: Draft, Proof

•	Font pitch: Fixed, Variable

•	Font angle: Italic

•	Font strikeouts: Strikeout

•	Font underlines: Underline

These modifiers are available for TrueType and Adobe Type Manager.  To see a list of fonts that you have installled under Microsoft Windows, open the "Control Panel" icon, located in the "Main" program group.  The control panel menu appears.  Double click on the "Fonts" icon to see a list of installed fonts.  Note that if you have a type scaling progrm (such as Adobe Type Manager) installed, there may be fonts that do not show up under the control panel.  For example, Adobe Type Manager has its own control panel icon that, when opened, displays a scrolling list of installed PostScript outline fonts.

Macintosh Only

Valid modifiers are:

•	Font weight: Bold

•	Font angle: Italic

•	Font width: Condensed, Extended

•	Font outlines: Outline, Shadow

•	Font underlines: Underline

Keywords

Properties retrievable via IDLgrFont::GetProperty (page 99) are indicated by the word "Get" following the keyword. Properties settable via IDLgrFont::SetProperty (page 102) are indicated by the word "Set" following the keyword.

NAME

Set this keyword to a variable that will contain the name of the font. NAME is the same as the Fontname argument described above.

SIZE (Get, Set)

Set this keyword to a scalar representing the point size of the font.  The default is 12.

SUBSTITUTE (Get, Set)

Set this keyword to a string that indicates the font to use as a substitute for this font if it is not available on the graphics destination.  Valid values are only those fonts that are available on all graphics destinations.  These are: 'Helvetica' (the default), 'Courier', 'Times', or 'Symbol'.

THICK (Get, Set)

Set this keyword to a value indicating the line thickness (measured in device units) to use for the Hershey vector fonts. The default 1.0 pixel.


IDLgrFont::SetProperty

The IDLgrFont::SetProperty procedure method sets the value of a property or group of properties for the font. IDLgrFont is described on page 98.

Calling Sequence

Obj->[IDLgrFont:]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrFont::Init (page 100) followed by the word "Set" can be retrieved using IDLgrFont::SetProperty.


IDLgrImage

An image object represents a mapping from a two-dimensional array of data values to a two dimensional array of pixel colors, resulting in a flat 2D-scaled version of the image, drawn at Z = 0.

The image object is drawn at Z =0 and is interpreted with two points:

p1 = [LOC(0), LOC(1), 0]

p2 = [LOC(0) + DIMENSION(0), LOC(1) + DIMENSION(1), 0].

These points are transformed in 3D, resulting in screen space points designated as p1' and p2'. The image data is then drawn in the 2D rectangle defined by [(p1'(0), p1'(1), p2'(0), p2'(1)] by scaling the image pixels to fit the rectangle.

Note	If a fully 3D-transformed image is desired, use the IDLgrPolygon object with texture mapping enabled.

An IDLgrImage 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

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrImage::Init (page 112).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrImage::Cleanup (page 110)

•	IDLgrImage::GetCTM (page 110)

•	IDLgrImage::GetProperty (page 111)

•	IDLgrImage::Init (page 112)

•	IDLgrImage::SetProperty (page 116)


IDLgrImage::Cleanup

The IDLgrImage::Cleanup procedure method performs all cleanup on the object. IDLgrImage is described on page 109.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrImage::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrImage::GetCTM

The IDLgrImage::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrImage is described on page 109.

Calling Sequence

Obj->[IDLgrImage::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrImage::GetProperty

The IDLgrImage::GetProperty procedure method retrieves the value of the property or group of properties for the image. IDLgrImage is described on page 109.

Calling Sequence

Obj->[IDLgrImage::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrImage::Init (page 112) followed by the word "Get" can be retrieved using IDLgrImage::GetProperty. In addition, the following keyword is available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the image object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrImage::Init

The IDLgrImage::Init function method initializes the image object. IDLgrImage is described on page 109.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrImage' [, ImageData])

or

Result = Obj -> [IDLgrImage::]Init([ImageData])         (In a subclass' Init method only.)

Arguments

ImageData

An array of data values to be displayed as an image.  If this argument is not already of byte type, it is converted prior to use.  The array may be an nxm array of color lookup table indices (accepted by graphics destinations using the Indexed or RGB color model), where n is the width of the image, and m is the height.  Alternatively, the image may be one of the following (accepted only by graphics destinations using the RGB color model), where the 3 represents the red, green, and blue channels: 3xnxm, nx3xm, nxmx3, or (if alpha channel is also included): 4xnxm, nx4xm, or nxmx4.  If the image argument is not provided, the SHARE_DATA keyword must be present.

Keywords

Properties retrievable via IDLgrImage::GetProperty (page 111) are indicated by the word "Get" following the keyword. Properties settable via IDLgrImage::SetProperty (page 116) are indicated by the word "Set" following the keyword.

BLEND_FUNCTION (Get, Set)

Set this keyword to a two-element array, [src, dest], to specify the source and destination blend functions for alpha blending. These are only valid for RGB model destinations. If no Alpha data are specified in an image, the image's Alpha value is assumed to be 1.0. Valid src and dst blend functions include:

•	0 = None: Alpha blending is disabled

•	1 = Zero:

•	2 = One:

•	3 = SrcAlpha:

•	4 = OneMinusSourceAlpha

CHANNEL (Get, Set)

Set this keyword to a long integer bitmask representing the RGB and CI color modes. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. For example, 'ff0000'X represents a Red channel write. The default is represented by 0xffffff.

COLOR (Get, Set)

Set this keyword to the color to be used as the foreground color for this image.  The color may be specified as a color lookup table index (accepted by graphics destinations using either the Color Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).  The default is [255, 255, 255]

DATA (Get, Set)

Set this keyword to a nxm, 2xnxm, 3xnxm, or 4xnxm array of image data for the object. The n and m values may be in any position as specified by the INTERLEAVE keyword. This keyword is equivalent to the optional argument, ImageData.

DIMENSIONS (Get, Set)

A two-element vector of the form [width, height] specifying the dimensions of the rectangle in which the image is to be drawn on the device. The image will be resampled as necessary to fit within this rectangle. The default is derived from the dimensions of the given image data and is measured in device units (see the UNITS keyword).

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

 The default is `Copy'.  Valid values include the following:

•	0 = Copy: Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

INTERLEAVE (Get, Set)

Set this keyword to indicate the dimension over which color is interleaved for true color images:

•	0 = Pixel interleaved: Images with dimensions (3, m, n)

•	1 = Scanline interleaved: (rwo interleaved)Images with dimensions (m, 3, n)

•	2 = Planar interleaved: (planar interImages with dimensions (m, n, 3).

Note	If alpha is present, the 3's should be replaced by 4's.

LOCATION (Get, Set)

A two- element vector of the form [x, y] specifying the position of the lower lefthand corner of the image.  The default is [0, 0], and is measured in device units (see the UNITS keyword).

LUMINANCE

Set this keyword to specify that the image not be drawn through a palette. For an RGB colormodel destination, if a palette is present in the image object, it is used. If there is no current destination palette, a grayscale palette is used. For a Color Index colormodel destination, the current destination palette is used.

Note	Only single band images (i.e. 1xnxm) are affected by this keyword. By default, LUMINANCE is disabled.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

NO_COPY (Get, Set)

Set this keyword to relocate the image data from the input variable to the image object, leaving the input variable undefined. Only the data argument is affected. If this keyword is omitted, the input image data will be duplicated and a copy will be stored in the object.

ORDER (Get, Set)

Set this keyword to force the rows of the image data to be drawn from top to bottom.  By default, image data is drawn from the bottom row up to the top row.

PALETTE (Get, Set)

Set this keyword to the palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values of the color lookup table to be associated with this image if it is indexed (not true color).

Note	This table is only used when the destination is an RGB model device. The CI model writes the indices directly to the device. In order to ensure that these colors are used when the image is displayed, this palette must be copied to the graphics destination's palette for any graphics destination that uses the Indexed color model.

SHARE_DATA (Get)

Set this keyword to an object with which data is to be shared by this image.  An image may only share data with another image.  The ImageData argument is ignored if this keyword is set.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].


IDLgrImage::SetProperty

The IDLgrImage::SetProperty procedure method sets the value of the property or group of properties for the image. IDLgrImage is described on page 109.

Calling Sequence

Obj->[IDLgrImage::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrImage::Init (page 112) followed by the word "Set" can be retrieved using IDLgrImage::SetProperty.


IDLgrLight

A light object represents a source of illumination for graphic models.  Lights may be either ambient, positional, directional, or spotlights. A maximum of 8 lights per view are allowed.

An IDLgrLight 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.

Note	An IDLgrLight object can not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrLight::Init (page 121).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrLight::Cleanup (page 118)

•	IDLgrLight::GetCTM (page 119)

•	IDLgrLight::GetProperty (page 120)

•	IDLgrLight::Init (page 121)

•	IDLgrLight::SetProperty (page 124)


IDLgrLight::Cleanup

The IDLgrLight::Cleanup procedure method performs all cleanup on the object. IDLgrLight is described on page 118.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrLight::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrLight::GetCTM

The IDLgrLight::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrLight is described on page 118.

Calling Sequence

Obj->[IDLgrLight::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrLight::GetProperty

The IDLgrLight::GetProperty procedure method retrieves the value of a property or group of properties for the light. IDLgrLight is described on page 118.

Calling Sequence

Obj->[IDLgrLight::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrLight::Init (page 121) followed by the word "Get" can be retrieved using IDLgrLight::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the light object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrLight::Init

The IDLgrLight::Init function method initializes the light object. IDLgrLight is described on page 118.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrLight')

or

Result = Obj -> [IDLgrLight::]Init( )         (In a subclass' Init method only.)

Arguments

There are no arguments for this method.

Keywords

Properties retrievable via IDLgrLight::GetProperty (page 120) are indicated by the word "Get" following the keyword. Properties settable via IDLgrLight::SetProperty (page 124) are indicated by the word "Set" following the keyword.

ATTENUATION (Get, Set)

Set this keyword to a 3-element floating point vector of the form [constant, linear, quadratic] that describes the factor by which light intensity is to fall with respect to distance from the light source.  ATTENTUATION applies only to Positional and Spot lights, as specified by the TYPE keyword. The overall attenuation factor is computed as follows:

attenuation = 1/(constant + linear * distance + quadratic * quadratic * distance)

By default, the values are [1, 0, 0].

COLOR (Get, Set)

Set this keyword to the color to be associated with this light.  Color may be specified as an RGB vector.  The default is [255, 255, 255].  The color of a light is ignored when graphics are sent to graphics destinations using the Indexed color model, in which case light intensities are scaled into the range of colors available on the graphics destination.

CONEANGLE (Get, Set)

Set this keyword to the angle (measured in degrees) of coverage for a spotlight.  The default is 60.

DIRECTION (Get, Set)

Set this keyword to the three-element vector representing the direction in which a spotlight is to be pointed.  The default is [0,0,-1].

Note	For directional lights, the light's parallel rays follow a vector beginning at the position specified by LOCATION and ending at [0, 0, 0].

FOCUS (Get, Set)

Set this keyword to a scalar floating point value that is used to describe the attenuation of intensity for spotlights as the distance from the center of the cone of coverage increases.  This factor is used as an exponent to the cosine of tha angle between the direction of the spotlight and the direction from the light to the vertex being lighted.  The default is 0.0.

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

INTENSITY (Get, Set)

Set this keyword to a floating point value between 0.0 (darkest) and 1.0 (brightest) indicating the intensity of the light.  The default is 1.0.

LOCATION (Get, Set)

Set this keyword to a vector of the form [x, y, z] describing the position of the light. By default, the position is [0, 0, 0] and is measured in the units specified by the UNITS keyword.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

TYPE (Get, Set)

Set this keyword to one of the following values, indicating the type of light. Valid values include:

•	0 = Ambient: Universal light source, has no direction or position; universally lights every surface in the scene, won't get edges, controlling overall brightness and color of the entire scene.

•	1 = Positional (default): Divergent light rays; the source can be located anywhere in the scene; it has positionin the scene.

•	2 = Directional: Parallel light rays; implication is that the light source is located at an infinite distance from scene.

•	3 = Spot: Has a position and a direction; cone

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].


IDLgrLight::SetProperty

The IDLgrLight::SetProperty procedure method sets the value of a property or group of properties for the light. IDLgrLight is described on page 118.

Calling Sequence

Obj->[IDLgrLight::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrLight::Init (page 121) followed by the word "Set" can be retrieved using IDLgrLight::SetProperty.


IDLgrModel

A model object represents a graphical item that may be transformed (rotated, scaled, and/or translated). It serves as a container of other IDLgrModel objects or atomic graphic objects. IDLgrModel applies a transform to the current view tree.

Superclasses

This class is a subclass of IDL_Container (page 70)

Subclasses

This class has no subclasses.

Creation

See IDLgrModel::Init (page 129).

Methods

Intrinsic Methods

This class has this following methods:

•	IDLgrModel::Add (page 125)

•	IDLgrModel::Cleanup (page 126)

•	IDLgrModel::GetByName (page 127)

•	IDLgrModel::GetProperty (page 128)

•	IDLgrModel::Init (page 129)

•	IDLgrModel::Remove (page 131)

•	IDLgrModel::Rotate (page 131)

•	IDLgrModel::Scale (page 132)

•	IDLgrModel::SetProperty (page 132)

•	IDLgrModel::Translate (page 133)


IDLgrModel::Add

The IDLgrModel::Add procedure method adds a child to this Model. It adjusts the internal 3D and depth buffer flags with respect to the addition. IDLgrModel is described on page 125.

Calling Sequence

Obj ->[IDLgrModel::]Add, View

Arguments

View

An instance of the IDLgrView (page 209) object class to be added to the model object.

Keywords

There are no keywords for this method.


IDLgrModel::Cleanup

The IDLgrModel::Cleanup procedure method performs all cleanup on the object. IDLgrModel is described on page 125.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrModel::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrModel::GetByName

The IDLgrModel::GetByName function method finds contained objects by name. IDLgrModel is described on page 125.

Calling Sequence

Result = Obj ->[IDLgrModel::]GetByName(Name)

Arguments

Name

The name of the object to be removed.

Keywords

There are no keywords for this method.


IDLgrAxis::GetCTM
IDLgrModel::GetCTM

The IDLgrModel::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrModel is described on page 125.

Calling Sequence

Obj->[IDLgrModel::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrModel::GetProperty

The IDLgrModel::GetProperty procedure method retrieves the value of a property or group of properties for the model. IDLgrModel is described on page 125.

Calling Sequence

Obj->[IDLgrModel::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrModel::Init (page 129) followed by the word "Get" can be retrieved using IDLgrModel::GetProperty (page 128). In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the model object.


IDLgrModel::GetProperty
IDLgrModel::GetCTM

The IDLgrModel::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrModel is described on page 125.

Calling Sequence

Obj->[IDLgrModel::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrModel::Init

The IDLgrModel::Init procedure method initializes the model object. IDLgrModel is described on page 125.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrModel')

or

Result = Obj -> [IDLgrModel::]Init( )         (In a subclass' Init method only.)

Arguments

There are no arguments for this method.

Keywords

Properties retrievable via IDLgrModel::GetProperty (page 128) are indicated by the word "Get" following the keyword. Properties settable via IDLgrModel::SetProperty (page 132) are indicated by the word "Set" following the keyword.

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

Note	HIDE only controls the display attributes of IDLgrModel children since the IDLgrModel object itself lacks geometry.

NAME

Set this keyword to a string to be associated with the current instance of the Model object. The default is 'IDLgrModel'.

SELECT_TARGET (Get, Set)

Set this keyword to tag this object as the target object to be returned when any object in its tree is selected. By default, an IDLgrModel object cannot be returned as the target of a SELECT since it doesn't contain any geometry. By setting SELECT_TARGET, this object will return only that it was selected, without including the presence of any children.

TRANSFORM (Get, Set)

Set this keyword to a 4x4 array representing the transformation matrix to be applied to this object.  This matrix will be multiplied by its parent's transformation matrix (if the parent has one).  The default is the identity transformation matrix.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".


IDLgrModel::Remove

The IDLgrModel::Remove procedure method removes an atomic graphic object from view from the model. IDLgrModel is described on page 125.

Calling Sequence

Obj ->[IDLgrModel::]Remove, View

Arguments

View

An instance of the IDLgrView (page 209) object to be removed from the model object.

Keywords

There are no keywords for this method.


IDLgrModel::Rotate

The IDLgrModel::Rotate procedure method rotates the model about the given axis by the given angle. IDLgrModel is described on page 125.

Calling Sequence

Obj->[IDLgrModel::]Rotate, Axis, Angle

Arguments

Axis

A three-element vector of the form [x, y, z] describing the axis about which the model is to be rotated.

Angle

The angle (measured in degrees) by which the rotation is to occur.

Keywords

PREMULTIPLY

Set the keyword to cause the resulting rotation matrix to be premultiplied to the model's transformation matrix.  By default, the rotation matrix is post-multiplied.


IDLgrModel::Scale

The IDLgrModel::Scale procedure method scales the model by the given scaling factors. IDLgrModel is described on page 125.

Calling Sequence

Obj->[IDLgrModel::]Scale, Sx, Sy, Sz

Arguments

Sx, Sy, Sz

The scaling factors in the x, y, and z dimensions by which the model is to be scaled.

Keywords

PREMULTIPLY

Set this keyword to cause the resulting scale matrix to be premultiplied to the model's transformation matrix.  By default, the scale matrix is post-multiplied.


IDLgrModel::SetProperty

The IDLgrModel::SetProperty procedure method sets the value of a property or group of properties for the model. IDLgrModel is described on page 125.

Calling Sequence

Obj->[IDLgrModel::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrModel::Init (page 129) followed by the word "Set" can be retrieved using IDLgrModel::SetProperty.


IDLgrModel::Translate

The IDLgrModel::Translate procedure method translates the model by the given translation offsets. IDLgrModel is described on page 125.

Calling Sequence

Obj->[IDLgrModel::]Translate, Tx, Ty, Tz

Arguments

Tx, Ty, Tz

The offsets in X, Y, and Z, respectively, by which the model is to be translated.

Keywords

PREMULTIPLY

Set this keyword to cause the resulting translation matrix to be premultiplied to the model's transformation matrix.  By default, the translation matrix is post-multiplied.


IDLgrPalette

A palette object represents a color lookup table that maps indices to red, green, blue, and potentially alpha values.

Superclasses

This class has no superclass.

Subclasses

This class has no subclasses.

Creation

See IDLgrPalette::Init (page 137).

Methods

Intrinsic Methods

This class has this following methods:

•	IDLgrPalette::Cleanup (page 134)

•	IDLgrPalette::GetRGB (page 135)

•	IDLgrPalette::GetProperty (page 136)

•	IDLgrPalette::Init (page 137)

•	IDLgrPalette::NearestColor (page 138)

•	IDLgrPalette::SetRGB (page 139)

•	IDLgrPalette::SetProperty (page 140)


IDLgrPalette::Cleanup

The IDLgrPalette::Cleanup procedure method performs all cleanup on the object. IDLgrPalette is described on page 134.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrPalette::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPalette::GetRGB

The IDLgrPalette::GetRGB function method returns the RGB values contained in the palette at the given index.  The returned value is a three-element vector of the form [red, green, blue]. IDLgrPalette is described on page 134.

Calling Sequence

Result = Obj->[IDLgrPalette::]GetRGB(Index)

Arguments

Index

The index whose RGB values are wanted. This value should be in the range of 0 ≤ Value < NCOLORS.

Keywords

There are no keywords for this method.


IDLgrPalette::GetProperty

The IDLgrPalette::GetProperty procedure method retrieves the value of a property or group of properties for the palette. IDLgrPalette is described on page 134.

Calling Sequence

Obj->[IDLgrPalette::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPalette::Init (page 137) followed by the word "Get" can be retrieved using IDLgrPalette::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure contianing the values of all the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

BOTTOM_STRETCH

Set this keyword to return the current bottom stretch value of the palette. This value is in the range of 0 ≤ Value ≤ 100.

GAMMA

Set this keyword to return the current gamma value of the palette. This value is in the range of  0.1 ≤ Value ≤ 10.0.

NCOLORS

Set this keyword to return the number of elements in the color palette.

PARENT

Set this keyword to return a reference to the parent of the object.

TOP_STRETCH

Set this keyword to return the current top stretch value of the palette. This value is in the range of 0 ≤ Value ≤ 100.


IDLgrPalette::Init

The IDLgrPalette::Init function method initializes a palette object. IDLgrPalette is described on page 134.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrPalette', [aRed, aGreen, aBlue])

or

Result = Obj -> [IDLgrPalette::]Init([aRed, aGreen, aBlue])
(In a subclass' Init method only.)

Arguments

aRed

A vector containing the red values for the color palette. These values should be within the range of 0 ≤ Value ≤ 255. The number of elements comprising the aRed vector must not exceed 256.

aGreen

A vector containing the green values for the color palette. These values should be within the range of 0 ≤ Value ≤ 255. The number of elements comprising the aGreen vector must not exceed 256.

aBlue

A vector containing the blue values for the color palette. These values should be within the range of 0 ≤ Value ≤ 255. The number of elements comprising the aBlue vector must not exceed 256.

Keywords

Properties retrievable via IDLgrPalette::GetProperty (page 136) are indicated by the word "Get" following the keyword. Properties settable via IDLgrPalette::SetProperty (page 140) are indicated by the word "Set" following the keyword.

BLUE_VALUES (Get, Set)

Set this keyword to return the current blue values contained in the color palette. The return value is an array of length N_COLORS. This keyword is the same as the aBlue argument described above.

BOTTOM_STRETCH (Get, Set)

Set this keyword to a requested value of the bottom parameter for stretching the colors in the palette. This value must be in the range of 0 ≤ Value ≤ 100. The default value is 0.

GAMMA (Get, Set)

Set this keyword to the gamma value to be applied to the color palette. This value should be in the range of 0.1 ≤ Gamma ≤ 10.0. The default is 1.0.

GREEN_VALUES (Get, Set)

Set this keyword to return the current green values contained in the color palette. The return value is an array of length N_COLORS. This keyword is the same as the aGreen argument described above.

N_COLORS (Get, Set)

Set this keyword to the number of color entered in the palette. The default is the number of colors provided in the arguments.

RED_VALUES (Get, Set)

Set this keyword to return the current red values contained in the color palette. The return value is an array of length N_COLORS. This keyword is the same as the aRed argument described above.

TOP_STRETCH (Get, Set)

Set this keyword to a requested value of the top parameter for stretching the colors in the palette. This value must be in the range of 0 ≤ Value ≤ 100. The default value is 100.


IDLgrPalette::NearestColor

The IDLgrPalette::NearestColor function method returns the index of the color in the palette that best matches the given RGB values. IDLgrPalette is described on page 134.

Calling Sequence

Result = Obj->[IDLgrPalette::]NearestColor(Red, Green, Blue)

Arguments

Red

The red value of the color that should be matched. This value should be within the range of 0 ≤ Value ≤ 255.

Green

The green value of the color that should be matched. This value should be within the range of 0 ≤ Value ≤ 255.

Blue

The blue value of the color that should be matched. This value should be within the range of 0 ≤ Value ≤ 255.

Keywords

There are no keywords for this method.


IDLgrPalette::SetRGB

The IDLgrPalette::SetRGB procedure method sets the color values at index in the palette to the passed in Red, Green and Blue values. IDLgrPalette is described on page 134.

Calling Sequence

Obj->[IDLgrPalette::]SetRGB, Index, Red, Green, Blue

Arguments

Index

The index to be set. This value should be in the range of  0 ≤ Value < NCOLORS.

Red

The red value to set in the color palette.

Green

The green value to set in the color palette.

Blue

The blue value to set in the color palette.

Keywords

There are no keywords for this method.


IDLgrPalette::SetProperty

The IDLgrPalette::SetProperty procedure method sets the value of a property or group of properties for the palette. IDLgrPalette is described on page 134.

Calling Sequence

Obj->[IDLgrPalette::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPalette::Init (page 137) followed by the word "Set" can be retrieved using IDLgrPalette::SetProperty.


IDLgrPattern

A pattern object represents a description of which pixels are filled and which are left blank when a graphic object is filled.

Superclasses

This class has no superclass.

Subclasses

This class has no subclasses.

Creation

See IDLgrPattern::Init (page 143).

Methods

Intrinsic Methods

This class has this following methods:

•	IDLgrPattern::Cleanup (page 141)

•	IDLgrPattern::GetProperty (page 142)

•	IDLgrPattern::Init (page 143)

•	IDLgrPattern:SetProperty (page 144)


IDLgrPattern::Cleanup

The IDLgrPattern::Cleanup procedure method performs all cleanup on the object. IDLgrPattern is described on page 141.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrPattern::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPattern::GetProperty

The IDLgrPattern::GetProperty procedure method retrieves the value of a property or group of properties for the pattern. IDLgrPattern is described on page 141.

Calling Sequence

Obj->[IDLgrPattern::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPattern::Init (page 143) followed by the word "Get" can be retrieved using IDLgrPattern::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.


IDLgrPattern::Init

The IDLgrPattern::Init function method initializes the pattern object. IDLgrPattern is described on page 141.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrPattern' [, Style])

or

Result = Obj -> [IDLgrPattern::]Init([Style] )         (In a subclass' Init method only.)

Arguments

Style

A scalar representing the type of pattern.  Valid values include:

•	0 = Solid (default)

•	1 = Linefill

•	2 = Pattern

Keywords

Properties retrievable via IDLgrPattern::GetProperty (page 142) are indicated by the word "Get" following the keyword. Properties settable via IDLgrPattern:SetProperty (page 144) are indicated by the word "Set" following the keyword.

ORIENTATION (Get, Set)

Set this keyword to a scalar representing the angle (measured in degrees counterclockwise from the horizontal) of the lines used for line fill.  This keyword is ignored unless the style is set to 1 (Linefill).

PATTERN (Get, Set)

A 32 x 4 byte array describing the pattern that may be tiled over a polygon.  Each bit that is a 1 is drawn, each bit that is 0 is not drawn.  This keyword is ignored unless the style is set to 2 (Pattern).

SPACING (Get, Set)

Set this keyword to a scalar representing the distance (measured in centimeters) between the lines used for line fill.  This keyword is ignored if style is not 1 (Linefill).

STYLE (Get, Set)

Set this keyword to specify the type of pattern to be used.  Valid values include:

•	0 = Solid (default)

•	1 = Linefill

•	2 = Pattern

This keyword is the same as the Style argument described above.

THICK

Set this keyword to the line thickness to be used to draw the pattern lines if the style is set to 1 (Linefill).


IDLgrPattern::SetProperty
IDLgrPattern:SetProperty

The IDLgrPattern::SetProperty procedure method sets the value of a property or group of properties for the pattern. IDLgrPattern is described on page 141.

Calling Sequence

Obj->[IDLgrPattern::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPattern::Init (page 143) followed by the word "Set" can be retrieved using IDLgrPattern::SetProperty.


IDLgrPlot

A plot object represents the mapping from abscissa values to ordinate values.

An IDLgrPlot 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.

Note	An IDLgrPlot object can not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrPlot::Init (page 148).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrPlot::Cleanup (page 145)

•	IDLgrPlot::GetCTM (page 146)

•	IDLgrPlot::GetProperty (page 147)

•	IDLgrPlot::Init (page 148)

•	IDLgrPlot::SetProperty (page 152)


IDLgrPlot::Cleanup

The IDLgrPlot::Cleanup procedure method performs all cleanup on the object. IDLgrPlot is described on page 145.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrPlot::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPlot::GetCTM

The IDLgrPlot::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrPlot is described on page 145.

Calling Sequence

Obj->[IDLgrPlot::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrPlot::GetProperty

The IDLgrPlot::GetProperty procedure method retrieves the value of the property or group of properties for the plot. IDLgrPlot is described on page 145.

Calling Sequence

Obj->[IDLgrPlot::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPlot::Init (page 148) followed by the word "Get" can be retrieved using IDLgrPlot::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

DATA

Set this keyword to retrieve the plot data.

PARENT

Set this keyword to return a reference to the parent of the object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrPlot::Init

The IDLgrPlot::Init function method initializes the plot object. IDLgrPlot is described on page 145.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrPlot' [, [X,] Y])

or

Result = Obj -> [IDLgrPlot::]Init([[X], Y] )         (In a subclass' Init method only.)

Arguments

X

A vector representing the abscissa values to be plotted.  If provided, Y is plotted as a function of X.  This argument is converted to single-precision floating-point values.  By default, X (and Y) is measured in data units (refer to the UNITS keyword).

Y

A vector representing the ordinate values to be plotted.  If X is not specified, Y is plotted as a function of the vector index of Y.  This argument is converted to single-precision floating point.  If neither the X or Y argument is provided, the SHARE_DATA keyword  must be present.

Keywords

Properties retrievable via IDLgrPlot::GetProperty (page 147) are indicated by the word "Get" following the keyword. Properties settable via IDLgrPlot::SetProperty (page 152) are indicated by the word "Set" following the keyword.

COLOR (Get, Set)

Set this keyword to the color to be used as the foreground color for this plot.  The color may be specified as a color lookup table index (accepted by graphics destinations using either the Color Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).  The default is [255, 255, 255]

DATAX (Set)

Set this keyword to a vector specifying the X values to be plotted. This keyword is the same as the X argument.

DATAY (Set)

Set this keyword to a vector specifying the Yvalues to be plotted. This keyword is the same as the Y argument.

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

 The default is `Copy'.  Valid values include the following:

•	0 = Copy: Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

HISTOGRAM (Get, Set)

Set this keyword to force only horizontal and vertical lines to be used to connect the plotted points. By default, the points are connected using a single straight line.

LINESTYLE (Get, Set)

Set this keyword to a long integer bitmask describing the linestyle pattern to be repeated over the length of the plotted line. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. An example of a valid value is '3F07'X, which describes a linestyle consisting of a long dash followed by a short dash. The default is a solid line, represented by 0xffffffff. LINESTYLE may be set to 0, in which case no line is drawn (only symbols are drawn at the plotted points).

MAX_VALUE (Get, Set)

The maximum value to be plotted.  If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing data and are not plotted.  Note that the IEEE floating-point value NaN is also treated as missing data.

MIN_VALUE (Get, Set)

The minimum value to be plotted.  If this keyword is present, data values less than the value of MIN_VALUE are treated as as missing data and are not plotted.  Note that the IEEE floating-point value NaN is also treated as missing data.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

NSUM (Get, Set)

Set this keyword to the number of data points to average when plotting.  If NSUM is larger than 1, every group of NSUM points is averaged to produce one plotted point.  If there are M data points, then M/NSUM points are plotted.  On logarithmic axes, a geometric average is preformed.

POLAR (Get, Set)

Set this keyword to create a polar plot.  The X and Y arguments must both be present.  The X argument represents the radius, and the Y argument represents the angle expressed in radians.

SHARE_DATA (Get)

Set this keyword to an object with which data is to be shared by this plot.  A plot may only share data with another plot.  The X and Y arguments are ignored if this keyword is set.

SYMBOL (Get, Set)

Set this keyword to a vector containing instances of the IDLgrSymbol object class.  Each symbol in the vector will be drawn at the corresponding plotted point.  If there are more points than elements in SYMBOL, the elements of the SYMBOL vector are cyclically repeated.  By default, no symbols are drawn. To remove symbols from a plot, set SYMBOL to a scalar.

THICK (Get, Set)

Set this keyword to the line thickness to be used to draw the plotted lines.  The default is 1.0 pixels.

USE_ZVALUE

Set this keyword to use the current ZVALUE. The plot is considered three-dimensional if this keyword is set.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

VERT_COLORS (Get, Set)

Set this keyword to a vector of colors to be used to draw at each vertex.  Color is interpolated between vertices.  If there are more plot points than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated.  By default, the plot is all drawn in the single color provided by the COLOR keyword.  If the VERT_COLORS is provided, the COLOR keyword is ignored.

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].

ZVALUE (Get, Set)

Set this keyword to a floating point value representing the constant Z value to be used for this plot.  The plotted lines and symbols are projected onto the plane specified by this value.  The default is 0.0.


IDLgrPlot::SetProperty

The IDLgrPlot::SetProperty procedure method sets the value of the property or group of properties for the plot. IDLgrPlot is described on page 145.

Calling Sequence

Obj->[IDLgrPlot::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPlot::Init (page 148) followed by the word "Set" can be retrieved using IDLgrPlot::SetProperty. In addition, the following keywords are available:

XRANGE

Set this keyword to override the default data bounding computation for XRANGE.

YRANGE

Set this keyword to override the default data bounding computation for YRANGE.


IDLgrPolygon

A polygon object represents one or more filled polygons that share a given set of vertices and rendering attributes. All polygons must be convex, i.e., all points must connect to form a single solid shape.

An IDLgrPolygon 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.

Note	An IDLgrPolygon object does not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrPolygon::Init (page 156).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrPolygon::Cleanup (page 153)

•	IDLgrPolygon::GetCTM (page 154)

•	IDLgrPolygon::GetProperty (page 155)

•	IDLgrPolygon::Init (page 156)

•	IDLgrPolygon::SetProperty (page 160)


IDLgrPolygon::Cleanup

The IDLgrPolygon::Cleanup procedure method performs all cleanup on the object. IDLgrPolygon is described on page 153.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrPolygon::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPolygon::GetCTM

The IDLgrPolygon::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrPolygon is described on page 153.

Calling Sequence

Obj->[IDLgrPolygon::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrPolygon::GetProperty

The IDLgrPolygon::GetProperty procedure method retrieves the value of the property or group of properties for the polygons. IDLgrPolygon is described on page 153.

Calling Sequence

Obj->[IDLgrPolygon::]GetProperty

Arguments

There are no arguments for this methods.

Keywords

Any keyword to IDLgrPolygon::Init (page 156) followed by the word "Get" can be retrieved using IDLgrPolygon::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrPolygon::Init

The IDLgrPolygon::Init function method initializes the polygons object. IDLgrPolygon is described on page 153.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrPolygon' [, X [, Y[, Z]]])

or

Result = Obj -> [IDLgrPolygon::]Init([X, [Y, [Z]]] )         (In a subclass' Init method only.)

Arguments

X

A vector argument providing the X coordinates of the vertices.  The vector must contain at least three elements.  If the Y and Z arguments are not provided, X must be an array of either two or three vectors (i.e., (2,*) or (3,*)), in which case, X(0,*) specifies the X values, X(1,*) specifies the Y values, and X(2,*) specifies the Z values.  If the POLYGONS keyword is not specified, the vertices should be specified in counterclockwise order.  If no arguments are provided, the SHARE_DATA keyword must be present.

Y

A vector providing the Y components of the vertices.  The vector must contain at least three elements.

Z

A vector providing the Z components of the vertices.  The vector must contain at least three elements.

Keywords

Properties retrievable via IDLgrPolygon::GetProperty (page 155) are indicated by the word "Get" following the keyword. Properties settable via IDLgrPolygon::SetProperty (page 160) are indicated by the word "Set" following the keyword.

BOTTOM (Get, Set)

Set this keyword to an RGB or CI color for drawing the backs of polygons (opposite side from the normal direction).

COLOR (Get, Set)

Set this keyword to an RGB or CI color for drawing polygons. Each color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model). The default is [255, 255, 255]. If TEXTURE_MAP is provided, the final color is modulated by the texture map pixel values. This keyword is ignored if the VERT_COLORS keyword is provided.

DATA (Get, Set)

Set this keyword to a 3 x n or 2 x n array which defines, respectively, the 2D or 3D vertex data. DATA is equivalent to the optional arguments, X, Y, and Z.

FILL_PATTERN (Get, Set)

Set this keyword to a long integer array of one or more instances of an IDLgrPattern object to indicate the fill pattern to use for filling the polygons.  By default, FILL_PATTERN is set to a scalar value, specifying a solid fill.

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

 The default is `Copy'.  Valid values include the following:

•	0 = Copy: Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

HIDDEN_LINES

Set this keyword to draw point and wireframe surfaces using hidden line (point) removal. By default, hidden line removal is disabled.

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

LINESTYLE

Set this keyword to a long integer bitmask describing the linestyle pattern to be used when STYLE is set to 1 (Lines). Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. An example of a valid value is '3F07'X, which describes a linestyle consisting of a long dash followed by a short dash. The default is a solid line, represented by 0xffffffff. LINESTYLE may be set to 0, in which case no line is drawn.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

NORMALS (Get, Set)

Set this keyword to a 3 x n array of unit surface normals at each vertex. If this keyword is not set, vertex normals are computed by averaging shared polygon normals at each vertex. To remove previously specified normals, set NORMALS to a scalar.

POLYGONS (Get, Set)

Set this keyword to an array of polygon descriptions.  A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0..in-1 are indices into the X, Y, and Z arguments that represent the polygon vertices. To ignore an entry in the POLYGONS array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single polygon will be generated.

Note	The connectivity array described by POLYGONS allows an individual object to contain more than one polygon. Vertex, normal and color information can be shared by the multiple polygons. Consequently, the polygon object can represent an entire mesh and compute reasonable normal estimates in most cases.

REJECT (Get, Set)

Set this keyword to reject polygons as being hidden if their vertices are ordered in a clockwise direction as seen by the viewer.  Select from one of the following values:

•	0: face culling disabled

•	1: backface culling enabled

•	2: frontface culling enabled

Set this keyword to zero to draw all polygons regardless of the order of vertices.

SHADE_RANGE (Get, Set)

Set this keyword to a two-element array that specifies the range of pixel values (color indices) to use for shading.  The first element is the color index for the darkest pixel.  The second element is the color element for the brightest pixel.  The default is [0, 255], [black, white]. This keyword is ignored when the polygons are drawn to a graphics destination that uses the RGB color model.

SHADING (Get, Set)

Set this keyword to a string representing the type of shading to use:

•	0 = Flat (default): The color of the first vertex in each polygon is used to define the color for the entire polygon. The color has a constant intensity based upon the normal vector.

•	1 = Gouraud: The colors along each line are interpolated between vertex colors, and then along scanlines from each of the edge intensities.

Gouraud shading may be slower than flat shading, but results in a smoother appearance.

SHARE_DATA (Get)

Set this keyword to an object with which data is to be shared by this polygon(s).  Polygons may only share data with another polygons object or a polyline.  The  X, Y, and Z arguments are ignored if this keyword is set.

STYLE

Set this keyword to specify how the polygon should be drawn:

•	0 = Points: Only vertices are drawn, using either COLOR or VERT_COLORS.

•	1 = Lines: Each polygon is outlined by connecting vertices as specified in counterclockwise order.

•	2 = Filled (default): Vertices are connected and the polygon faces are shaded.

Note	Texturing is in effect only when STYLE = 2 (Filled).

TEXTURE_COORD (Get, Set)

A 2 x n array containing the texture map subscripts for each of the n polygon vertices.  Use this keyword in conjunction with the TEXTURE_MAP keyword to wrap images over 2D and 3D polygons. Default coordinates are not provided.

TEXTURE_INTERP (Get, Set)

Set this keyword to indicate that bilinear sampling is to be used for texture mapping an image onto the polygon(s).  The default is nearest neighbor sampling.

TEXTURE_MAP (Get, Set)

Set this keyword to the image to be texture mapped onto the polygons.  The tiling or mapping of the texture is defined expressly by TEXTURE_COORD. If this keyword is omitted, polygons are filled with the color specified by the COLOR keyword.  The pattern array may be of any size; if it is smaller than the filled area, the pattern is tiled across the polygons. To remove a texture map, set TEXTURE_MAP to a scalar.

THICK

Se this keyword to the size of the points or the thickness of the lines to be drawn when STYLE is set to either 0 (Points) or 1 (Lines). The default is 1.0.

VERT_COLORS (Get, Set)

Set this keyword to a vector of colors to be used to draw at each vertex.  Color is interpolated between vertices if SHADING is set to 1 (Gouraud).  If there are more vertices than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated.  By default, the polygons are all drawn in the single color provided by the COLOR keyword. To remove vertex colors, set VERT_COLORS to a scalar.

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].


IDLgrPolygon::SetProperty

The IDLgrPolygon::SetProperty procedure method sets the value of the property or group of properties for the polygons. IDLgrPolygon is described on page 153.

Calling Sequence

Obj->[IDLgrPolygon::]SetProperty

Arguments

There are no arguments for this methods.

Keywords

Any keyword to IDLgrPolygon::Init (page 156) followed by the word "Set" can be retrieved using IDLgrPolygon::SetProperty (page 160). In addition, the following keywords are available:

PROPERTIES

Set this keyword equal to an anonymous structure with one or more tag names that match the settable properties for this object.


IDLgrPolyline

A polyline object represents one or more polylines that share a set of vertices and rendering attributes.

An IDLgrPolyline 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.

Note	An IDLgrPolyline object can not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrPolyline::Init (page 165).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrPolyline::Cleanup (page 162)

•	IDLgrPolyline::GetCTM (page 163)

•	IDLgrPolyline::GetProperty (page 164)

•	IDLgrPolyline::Init (page 165)

•	IDLgrPolyline::SetProperty (page 168)


IDLgrPolyline::Cleanup

The IDLgrPolyline::Cleanup procedure method performs all cleanup on the object. IDLgrPolyline is described on page 162.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrPolyline::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPolyline::GetCTM

The IDLgrPolyline::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrPolyline is described on page 162.

Calling Sequence

Obj->[IDLgrPolyline::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrPolyline::GetProperty

The IDLgrPolyline::GetProperty procedure method retrieves the value of a property or group of properties for the polylines. IDLgrPolyline is described on page 162.

Calling Sequence

Obj->[IDLgrPolyline::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPolyline::Init (page 165) followed by the word "Get" can be retrieved using IDLgrPolyline::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrPolyline::Init

The IDLgrPolyline::Init function method initializes the polylines object. IDLgrPolyline is described on page 162.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrPolyline' [, X [, Y[, Z]]])

or

Result = Obj -> [IDLgrPolyline::]Init([X, [Y, [Z]]] )         (In a subclass' Init method only.)

Arguments

X

A vector providing the X components of the points to be connected.  If the Y and Z arguments are not specified, X must be an array of either two or three vectors (i.e., (2,*) or (3,*)), in which case X(0,*) represent the X values, X(1,*) represent the Y values, and X(2,*) represent the Z values.  If no arguments are provided, the SHARE_DATA keyword must be present.

Y

A vector providing the Y components of the points to be connected.

Z

A vector providing the Z components of the points to be connected.

Keywords

Properties retrievable via IDLgrPolyline::GetProperty (page 164) are indicated by the word "Get" following the keyword. Properties settable via IDLgrPolyline::SetProperty (page 168) are indicated by the word "Set" following the keyword.

COLOR (Get, Set)

Set this keyword to the color to be used to draw the polyline. Each color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model). The default is [255, 255, 255]. This keyword is ignored if the VERT_COLORS keyword is provided.

DATA (Get, Set)

Set this keyword to a 3 x n or 2 x n array which defines, respectively, the 2D or 3D vertex data. DATA is equivalent to the optional arguments, X, Y, and Z.

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

 The default is `Copy'.  Valid values include the following:

•	0 = Copy: Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

LINESTYLE (Get, Set)

Set this keyword to a long integer bitmask describing the linestyle pattern with which to
draw the polyline. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. An example of a valid value is '3F07'X, which describes a linestyle consisting of a long dash followed by a short dash. The default is a solid line, represented by 0xffffffff. LINESTYLE may be set to 0, in which case no line is drawn (only symbols are drawn at the polyline vertices).

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

POLYLINES (Get, Set)

Set this keyword to an array of polyline descriptions.  A polyline description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polyline, and i0..in-1 are indices into the X, Y, and Z arguments that represent the vertices of the polyline(s). To ignore an entry in the POLYLINES array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single connected polyline will be generated from the X, Y, and Z arguments.

Note	The connectivity array described by POLYLINES allows an individual object to contain more than one polyline. Vertex, normal and color information can be shared by the multiple polylines. Consequently, the polyline object can represent an entire mesh and compute reasonable normal estimates in most cases.

SHADING (Get, Set)

Set this keyword to a string representing the type of shading to use:

•	0 = Flat (default): The color of the first vertex in a line segment is used to define the color for the entire line segment. The color has a constant intensity based upon the normal vector.

•	1 = Gouraud: The colors along each line are interpolated between vertex colors.

Gouraud shading may be slower than flat shading, but results in a smoother appearance.

SHARE_DATA (Set)

Set this keyword to an object whose data is to be shared by this polyline.  A polyline may only share data with a polygon object or another polyline.  The X, Y, and Z arguments are ignored if this keyword is set.

SYMBOL (Get, Set)

Set this keyword to a vector containing instances of the IDLgrSymbol object class to indicate the plotting symbols to be used at each vertex of the polyline.  If there are more vertices than elements in SYMBOL, the elements of the SYMBOL vector are cyclically repeated.  By default, no symbols are drawn. To remove symbols from a polyline, set SYMBOL to a scalar.

THICK (Get, Set)

Set this keyword to the line thickness to be used to draw the polyline.  The default is 1.0.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

VERT_COLORS (Get, Set)

Set this keyword to a vector of colors to be used to draw at each vertex.  Color is interpolated between vertices if SHADING is set to 1 (Gouraud).  If there are more vertices than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated.  By default, the polyline is drawn in the single color provided by the COLOR keyword. To remove vertex colors, set VERT_COLORS to a scalar.

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].


IDLgrPolyline::SetProperty

The IDLgrPolylines::SetProperty procedure method sets the value of a property or group of properties for the polylines. IDLgrPolylines is described on page 162.

Calling Sequence

Obj->[IDLgrPolylines::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPolyline::Init (page 165) followed by the word "Set" can be retrieved using IDLgrPolyline::SetProperty.


IDLgrPrinter

A printer object represents a hardcopy graphics destination. When a printer object is created, the printer device to which it refers is the default system printer. To change the printer, utilize the printer dialogs (see "DIALOG_PRINTJOB" on page 377 and "DIALOG_PRINTERSETUP" on page 378 of the IDL Reference Guide).

Note	Objects of IDLgrPrinter cannot be saved or restored.

Superclasses

This class has no superclass.

Subclasses

This class has no subclasses.

Creation

See IDLgrPrinter::Init (page 174).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrPrinter::Cleanup (page 170)

•	IDLgrPrinter::Draw (page 171)

•	IDLgrPrinter::Erase (page 172)

•	IDLgrPrinter::GetProperty (page 172)

•	IDLgrPrinter::Init (page 174)

•	IDLgrPrinter::NewDocument (page 175)

•	IDLgrPrinter::NewPage (page 176)

•	IDLgrPrinter::SetProperty (page 176)


IDLgrPrinter::Cleanup

The IDLgrPrinter::Cleanup procedure method performs all cleanup on the object. IDLgrPrinter is described on page 170.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrPrinter::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPrinter::Draw

The IDLgrPrinter::Draw procedure method draws the given picture to this graphics destination. IDLgrPrinter is described on page 170.

Calling Sequence

Obj->[IDLgrPrinter::]Draw, Picture

Arguments

Picture

The view (an instance of an IDLgrView object) or scene (an instance of an IDLgrScene object) to be drawn.

Keywords

NOERASE

Set this keyword to retain the previous contents of the printer bufferf. By default, the printer buffer is erased before drawing is initiated.


IDLgrPrinter::Erase

The IDLgrPrinter::Erase procedure method erases the entire contents of the printer buffer. IDLgrPrinter is described on page 170.

Calling Sequence

Obj->[IDLgrPrinter::]Erase[, View]

Arguments

There are no arguments for this method.

Keywords

COLOR

Set this keyword to the color to be used for the erase. The color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).


IDLgrPrinter::GetProperty

The IDLgrPrinter::GetProperty procedure method retrieves the value of a property or group of properties for the printer. IDLgrPrinter is described on page 170.

Calling Sequence

Obj->[IDLgrPrinter::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPrinter::Init (page 174) followed by the word "Get" can be retrieved using IDLgrPrinter::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

DIMENSIONS

Set this keyword to a variable that upon return will contain a two-element vector of the form [width, height] specifying the overall `drawable' area that may be printed on a page.  By default, the dimensions are measured in device units (refer to the UNITS keyword).

NAME

A string containing the operating system-specific name of the print stream. eg. '\\BORG\HpJet'.

PARENT

Set this keyword to return a reference to the parent of the object.

RESOLUTION

Set this keyword to a vector of the form [xres, yres] defining the pixel resolution measured in centimeters per pixel.

UNITS

Set this keyword to the units of measure to be used for the DIMENSIONS vector.  Valid values include:

•	0 = Device (default)

•	1 = Inches

•	2 = Centimeters

•	3 = Normal: relative to page size


IDLgrPrinter::Init

The IDLgrPrinter::Init function method initializes the printer object. IDLgrPrinter is described on page 170.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrPrinter')

or

Result = Obj -> [IDLgrPrinter::]Init( )         (In a subclass' Init method only.)

Arguments

There are no arguments for this method.

Keywords

Properties retrievable via IDLgrPrinter::GetProperty (page 172) are indicated by the word "Get" following the keyword. Properties settable via IDLgrPrinter::SetProperty (page 176) are indicated by the word "Set" following the keyword.

COLOR_MODEL (Get)

Set this keyword to the color model to be used for the buffer:

•	0 = RGB (default)

•	1 = Color Index

LANDSCAPE (Get, Set)

Set this keyword to produce hardcopy output in landscape mode . The default value of zero indicates Portrait mode.

Note	The driver may not support the LANDSCAPE option; use the printer dialogs to set orientation.

N_COLORS (Get)

Set this keyword to the number of colors (between 2 and 256) to be used if the COLOR_MODEL is set to Indexed.  This keyword is ignored if the COLOR_MODEL is set to RGB.

N_COPIES (Get, Set)

An integer that determines the number of copies of print data to be generated.  The default is 1 copy.

Note	The driver may not support the N_COPIES option; use the printer dialogs to set the number of copies.

PALETTE

Set this keyword to a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values that are to be loaded into the graphics destination's color lookup table, applicable if the Indexed color model is used.

QUALITY (Get, Set)

Set this keyword to a string indicating the quality at which graphics are to be drawn to this destination.  Valid values include:

•	0 = Low

•	1 = Medium

•	2 = High (default)

SCALE

Set this keyword to a scalar specifying the scale factor. The default value is 1.0.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".


IDLgrPrinter::NewDocument

The IDLgrPrinter::NewDocument function method terminates graphics output to the printer and initiates the actual print job. IDLgrPrinter is described on page 170.

Calling Sequence

Result = Obj->[IDLgrPrinter::]NewDocument

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPrinter::NewPage

The IDLgrPrinter::NewPage procedure method issues a new page command to the printer. IDLgrPrinter is described on page 170.

Calling Sequence

Obj->[IDLgrPrinter::]NewPage

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrPrinter::SetProperty

The IDLgrPrinter::SetProperty procedure method sets the value of a property or group of properties for the printer. IDLgrPrinter is described on page 170.

Calling Sequence

Obj->[IDLgrPrinter::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrPrinter::Init (page 174) followed by the word "Set" can be retrieved using IDLgrPrinter::SetProperty.


IDLgrScene

A scene object represents the entire scene to be drawn and serves as a container of IDLgrView objects.

Superclasses

This class is a subclass of IDL_Container (page 70).

Subclasses

This class has no subclasses.

Creation

See IDLgrScene::Init (page 180).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrScene::Add (page 177)

•	IDLgrScene::Cleanup (page 178)

•	IDLgrScene::GetByName (page 179)

•	IDLgrScene::GetProperty (page 179)

•	IDLgrScene::Init (page 180)

•	IDLgrScene::Remove (page 181)

•	IDLgrScene::SetProperty (page 181)


IDLgrScene::Add

The IDLgrScene::Add function method verifies that the added item is an instance of the IDLgrView object. If it is, IDLgrScene:Add adds the view to the specified scene. IDLgrScene is described on 177.

Calling Sequence

Obj ->[IDLgrScene::]Add, View

Arguments

View

An instance of the IDLgrView (page 209) object class.

Keywords

There are no keywords for this method.


IDLgrScene::Cleanup

The IDLgrScene::Cleanup procedure method performs all cleanup on the object. IDLgrScene is described on page 177.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrScene::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrScene::GetByName

The IDLgrScene::GetByName function method finds contained objects by name. IDLgrScene is described on page 177.

Calling Sequence

Result = Obj ->[IDLgrScene::]GetByName(Name)

Arguments

Name

The name of the object to be returned.

Keywords

There are no keywords for this method.


IDLgrScene::Draw


IDLgrScene::GetProperty

The IDLgrScene::GetProperty procedure method retrieves the value of a property or group of properties for the contour. IDLgrScene is described on page 177.

Calling Sequence

Obj->[IDLgrScene::]GetProperty

Keywords

Any keyword to IDLgrScene::Init (page 180) followed by the word "Get" can be retrieved using IDLgrScene::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.


IDLgrScene::Init

The IDLgrScene::Init function method initializes the scene object. IDLgrScene is described on page 177.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrScene')

or

Result = Obj -> [IDLgrScene::]Init( )         (In a subclass' Init method only.)

Arguments

There are no arguments for this method.

Keywords

Properties retrievable via IDLgrScene::GetProperty (page 179) are indicated by the word "Get" following the keyword. Properties settable via IDLgrScene::SetProperty (page 181) are indicated by the word "Set" following the keyword.

COLOR (Get, Set)

Set this keyword to the color to which the scene should be erased before drawing. The color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model), or an RGB vector (accepted only by graphics destinations using the RGB color model).  The default color is the color assigned to the plotted line.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".


IDLgrScene::Remove

The IDLgrScene::Remove function method removes a view from the scene object. IDLgrScene is described on page 177.

Calling Sequence

Obj ->[IDLgrScene::]Remove, View

Arguments

View

A reference to the IDLgrView (page 209) object to be removed from the scene.

Keywords

There are no keywords for this method.


IDLgrScene::SetProperty

The IDLgrScene::SetProperty procedure method sets the value of a property or group of properties for the buffer. IDLgrScene is described on page 177.

Calling Sequence

Obj->[IDLgrScene::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrScene::Init (page 180) followed by the word "Set" can be retrieved using IDLgrScene::SetProperty.


IDLgrSurface

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.

Note	An IDLgrSurface object can not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrSurface::Init (page 186).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrSurface::Cleanup (page 183)

•	IDLgrSurface::GetCTM (page 184)

•	IDLgrSurface::GetProperty (page 185)

•	IDLgrSurface::Init (page 186)

•	IDLgrSurface::SetProperty (page 191)


IDLgrSurface::Cleanup

The IDLgrSurface::Cleanup procedure method performs all cleanup on the object. IDLgrSurface is described on page 183.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrSurface::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrSurface::GetCTM

The IDLgrSurface::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrSurface is described on page 183.

Calling Sequence

Obj->[IDLgrSurface::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrSurface::GetProperty

The IDLgrSurface::GetProperty procedure method retrieves the value of a property or group of properties for the surface. IDLgrSurface is described on page 183.

Calling Sequence

Obj ->[IDLgrSurface::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrSurface::Init (page 186) followed by the word "Get" can be retrieved using IDLgrSurface::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrSurface::Init

The IDLgrSurface::Init function method initializes the surface object. IDLgrSurface is described on page 183.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrSurface' [, Z [, X, Y]])

or

Result = Obj -> [IDLgrSurface::]Init([Z, [X, Y]])         (In a subclass' Init method only.)

Arguments

Z

The two-dimensional array to be displayed. If X and Y are provided, the surface is defined as a function the (X, Y) locations specified by their contents.   Otherwise, the surface is generated as a function of the array indices of each element of Z.  This argument is converted to single-precision  floating-point.  If no arguments are provided, the SHARE_DATA keyword must be present.

X

A vector or two-dimensional array specifying the X coordinates of the grid. If this argument is a vector, each element of X specifies the X coordinate for a column of Z (e.g., X(0) specifies the X coordinate for Z(0,*)). If X is a two-dimensional array, each element of X specifies the X coordinate of the corresponding point in Z (Xij specifies the X coordinate for Zij). This argument is converted to single-precision floating-point.

Y

A vector or two-dimensional array specifying the Y coordinates of the grid. If this argument is a vector, each element of Y specifies the Y coordinate for a row of Z (e.g., Y(0) specifies the Y coordinate for Z(*,0)). If Y is a two-dimensional array, each element of Y specifies the Y coordinate of the corresponding point in Z (Yij specifies the Y coordinate for Zij).  This argument is converted to single-precision floating-point.

Keywords

Properties retrievable via IDLgrSurface::GetProperty (page 185) are indicated by the word "Get" following the keyword. Properties settable via IDLgrSurface::SetProperty (page 191) are indicated by the word "Set" following the keyword.

BOTTOM (Get, Set)

The color value used to draw the bottom surface. If not specified, or set to a negative scalar, the bottom is drawn with the same color as the top (refer to the COLOR keyword).

COLOR (Get, Set)

Set this keyword to the color to be used as the foreground color for this model.  The color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).  The default is [255, 255, 255]

DATAX (Set)

Set this keyword to a vector or a two-dimensional array specifying the X coordinates of the surface grid. This keyword is the same as the X argument described above.

DATAY (Set)

Set this keyword to a vector or a two-dimensional array specifying the Ycoordinates of the surface grid. This keyword is the same as the Y argument described above.

DATAZ (Set)

Set this keyword to the two-dimensional array to display as a surface. This keyword is the same as the Z argument described above.

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

Valid values include the following:

•	0 = Copy(default): Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

HIDDEN_LINES (Get, Set)

Set this keyword to draw point and wireframe surfaces using hidden line (point) removal. By default, hidden line removal is disabled.

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

LINESTYLE (Get, Set)

Set this keyword to a long integer bitmask describing the linestyle pattern to be repeated over the surface. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. An example of a valid value is '3F07'X, whcih describes a linestyle consisting of a long dash followed by a short dash. The default is a solid line, represented by 0xffffffff.

MAX_VALUE (Get, Set)

The maximum value to be plotted.  If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing and are not plotted when the surface is drawn.  Note that the IEEE floating-point value NaN is also treated as missing data.

MIN_VALUE (Get, Set)

The minimum value to be plotted.  If this keyword is present, data values less than the value of MIN_VALUE are treated as missing and are not plotted.  Note that the IEEE floating-point value NaN is also treated as missing data.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

SHADE_RANGE (Get, Set)

Set this keyword to a two-element array that specifies the range of pixel values (color indices) to use for shading.  The first element is the color index for the darkest pixel.  The second element is the color element for the brightest pixel.  This value is ignored when the polygons are drawn to a graphics destination that uses the RGB color model.

SHADING (Get, Set)

Set this keyword to indicate the type of shading to use if STYLE is set to 2 (Filled) or 6 (LegoFilled).Set this keyword to a string representing the type of shading to use:

•	0 = Flat (default): The color has a constant intensity for each face of the surface, based on the normal vector.

•	1 = Gouraud: The colors are interpolated between vertices, and then along scanlines from each of the edge intensities.

Gouraud shading may be slower than flat shading, but results in a smoother appearance.

SHARE_DATA (Set)

Set this keyword to an object whose data is to be shared by this surface.  A surface may only share data with another surface or a contour.  The X, Y, and Z arguments are ignored if this keyword is set.

SHOW_SKIRT (Get, Set)

Set this keyword to enable skirt drawing. The default is to disable skirt drawing.

SKIRT (Get, Set)

Set this keyword to the Z value at which a skirt is to be defined around the array.  The Z value is expressed in data units.  The default is 0.0.  If a skirt is defined, each point on the four edges of the surface is connected to a point on the skirt which has the given Z value, and the same X and Y values as the edge point.  In addition, each point on the skirt is connected to its neighbor. The skirt value is ignored if skirt drawing is disabled (see SHOW_SKIRT above).

STYLE (Get, Set)

Set this keyword to indicate the style to be used to draw the surface.  Valid values include:

•	0 = Points

•	1 = Lines

•	2 = Filled (default)

•	3 = RuledXZ

•	4 = RuledYZ

•	5 = Lego

•	6 = LegoFilled: for outline or shaded and stacked histogram-style plots.

TEXTURE_COORD (Get, Set)

A 2 xn array containing the fill pattern array subscripts of each of the n polygon vertices.  Use this keyword in conjunction with the TEXTURE_MAP keyword to warp images over the surface. To stretch (or shrink) the texture map to cover the surface mesh completely, set TEXTURE_COORD to a scalar. The default is coordinates from 0.0 to 1.0 over the surface bounds.

TEXTURE_INTERP (Get, Set)

 Set this keyword to a nonzero value to indicate that bilinear sampling is to be used with texture mapping. The default method is nearest-neighbor sampling.

TEXTURE_MAP (Get, Set)

Set this keyword to an instance of the IDLgrImage object class to be texture mapped onto the surface. The pattern array may be of any size; if it is smaller than the filled area, the pattern is tiled across the surface. If this keyword is omitted or set to a scalar, no texture map is applied and the surface is filled with the color specified by the COLOR keyword. By default, the texture map will be stretched (or shrunk) to to cover the surface mesh completely.

THICK (Get, Set)

Set this keyword to the line thickness to use to draw surface lines.  The default is 1.0.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

VERT_COLORS (Get, Set)

Set this keyword to a vector of colors to be used to draw at each vertex.  Color is interpolated between vertices if SHADING is set to 1 (Gouraud).  If there are more vertices than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated.  By default, the polygons are all drawn in the single color provided by the COLOR keyword. If this keyword is omitted or set to a scalar, vertex colors are removed and the surface is drawn in the color specified by the COLOR keyword.

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].


IDLgrSurface::SetProperty

The IDLgrSurface::SetProperty procedure method sets the value of a property or group of properties for the surface. IDLgrSurface is described on page 183.

Calling Sequence

Obj ->[IDLgrSurface::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrSurface::Init (page 186) followed by the word "Set" can be retrieved using IDLgrSurface::SetProperty.


IDLgrSymbol

A symbol object represents a graphical element that is plotted relative to a particular position.

Note	Seven predefined symbols are provided by IDL.

Superclasses

This class has no superclass.

Subclasses

This class has no subclasses.

Creation

See IDLgrSymbol::Init (page 194).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrSymbol::Cleanup (page 192)

•	IDLgrSymbol::GetProperty (page 193)

•	IDLgrSymbol::Init (page 194)

•	IDLgrSymbol::SetProperty (page 195)


IDLgrSymbol::Cleanup

The IDLgrSymbol::Cleanup procedure method performs all cleanup on the object. IDLgrSymbol is described on page 192.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrSymbol::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrSymbol::GetProperty

The IDLgrSymbol::GetProperty procedure method retrieves the value of a property or group of properties for the symbol. IDLgrSymbol is described on page 192.

Calling Sequence

Obj ->[IDLgrSymbol::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrSymbol::Init (page 194) followed by the word "Get" can be retrieved using IDLgrSymbol::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.


IDLgrSymbol::Init

The IDLgrSymbol::Init function method initializes the plot symbol. IDLgrSymbol is described on page 192.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrSymbol' [Data])

or

Result = Obj -> [IDLgrSymbol::]Init([Data] )         (In a subclass' Init method only.)

Arguments

Data

This optional argument can be a scalar, or it can be either an IDLgrModel object or atomic graphic object.

Use one of the following scalar-represented internal default symbols:

•	1 = Plus sign, `+' (default)

•	2 = Asterisk

•	3 = Period (Dot)

•	4 = Diamond

•	5 = Triangle

•	6 = Square

•	7 = X

If an instance of the IDLgrModel object class or an atomic graphic object is used, the object tree is used as the symbol. For best results, the object should fill the domain from -1 to +1 in all dimensions.

Keywords

Properties retrievable via IDLgrSymbol::GetProperty (page 193) are indicated by the word "Get" following the keyword. Properties settable via IDLgrSymbol::SetProperty (page 195) are indicated by the word "Set" following the keyword.

COLOR (Get, Set)

Set this keyword to the color used to draw the symbol. The color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model), or an RGB vector (accepted only by graphics destinations using the RGB color model).  The default color is the color of the object for which this symbol is being used.

DATA (Get, Set)

Set this keyword to specify a symbol. This keyword is equivalent to the optional argument.

SIZE (Get, Set)

Set this keyword to a two-element vector describing the X and Y scaling factors to be applied to the symbol. The default is [1.0, 1.0].

THICK (Get, Set)

Set this keyword to the line thickness to use to draw any lines that make up the  symbol.  The default is 1.0.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".


IDLgrSymbol::SetProperty

The IDLgrSymbol::SetProperty procedure method sets the value of a property or group of properties for the symbol. IDLgrSymbol is described on page 192.

Calling Sequence

Obj ->[IDLgrSymbol::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrSymbol::Init (page 194) followed by the word "Set" can be retrieved using IDLgrSymbol::SetProperty.


IDLgrTessellator

A tessellator object represents a helper class which converts a simple concave polygon (or a simple polygon with "holes") into a number of simple convex plygons (general triangles). A polygon is simple if it includes no duplicate vertices, if the edges intersect only at vertices, and exactly two edges meet at any vertex.

Each polygon can be marked as being either an interior or an exterior (default) polygon. Interior polygons are treated as holes in the exterior polygons. Multiple non-overlapping exterior polygons are allowed as well. All polygons should be specified in the same orientation (either clockwise or counter-clockwise). Once all the polygons have been passed into the tesselator object, the final triangulation is accomplished by the IDLgrTessellator::Tessellate method. A list of vertices and a connectivity array are returned. You may process these by hand, or pass them to an IDLgrPolygon object. The tesselator object will not create any vertices in the process, rather the output vertex list will include only those vertices passed into the object originally.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrTessellator::Init (page 199).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrTessellator::AddPolygon (page 198)

•	IDLgrTessellator::Cleanup (page 199)

•	IDLgrTessellator::Init (page 199)

•	IDLgrTessellator::Reset (page 200)

•	IDLgrTessellator::Tessellate (page 200)


IDLgrTessellator::AddPolygon

The IDLgrTessellator::AddPolygon procedure method performs all cleanup on the object. IDLgrTessellator is described on page 197.

Calling Sequence

Obj ->[IDLgrTessellator::]AddPolygon [, X[, Y[, Z]]

Arguments

X

A 2xn or 3xn array points.

Y

A 2xn or 3xn array points. If X and Y are both specified, they must be one-dimensional vectors of the same length.

Z

A 2xn or 3xn array points. If X, Y, and Z are all specified, they must all three be one-dimensional vectors of the same length. If no Z values are specified, the Z value for the polygon is set to 0.

Keywords

POLYGON (Get, Set)

Set this keyword to an array of polygon descriptions.  A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0..in-1 are indices into the X, Y, and Z arguments that represent the polygon vertices. To ignore an entry in the POLYGON array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single polygon will be generated.

Note	The connectivity array described by POLYGONS allows an individual object to contain more than one polygon. Consequently, the polygon object can represent an entire mesh and compute reasonable normal estimates in most cases.

INTERIOR

Set this keyword to set a polygon to be an interior polygon, which is treated as a hole in the exterior polygons.


IDLgrTessellator::Cleanup

The IDLgrTessellator::Cleanup procedure method performs all cleanup on the object. IDLgrTessellator is described on page 197.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrTessellator::]Cleanup                              (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrTessellator::Init

The IDLgrTessellator::Init function method initializes the tessellator object. IDLgrTessellator is described on page 197.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrTesselator')

or

Result = Obj -> [IDLgrTessellator::]Init( )         (In a subclass' Init method only.)

Arguments

There are no arguments for this method.

Keywords

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".


IDLgrTessellator::Reset

The IDLgrTessellator::Reset procedure method resets the object's internal state. All previously added polygons are removed from memory and the object is prepared for a new tesselation task. IDLgrTessellator is described on page 197.

Calling Sequence

Obj ->[IDLgrTessellator::]Reset

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrTessellator::Tessellate

The IDLgrTessellator::Tessellate function method performs the actual tesselation. IDLgrTessellator is described on page 197.

Calling Sequence

Obj ->[IDLgrTessellator::]Tessellate(Vertices, Poly)

Arguments

If the tesselation succeeds, IDLgrTessellator::Tessellate returns 1 and the contents of Vertices and Poly are set to the results of the tesselation. If the tesselation fails, the funcion returns 0.

Vertices

A 2xn array if all the input polygons were 2D. A 3xn array if all the the input polygons were 3D.

Poly

An array of polygon descriptions.  A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0..in-1 are indices into the X, Y, and Z arguments that represent the polygon vertices. To ignore an entry in the Poly array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single polygon will be generated.

Note	The connectivity array described by Poly allows an individual object to contain more than one polygon. Consequently, the polygon object can represent an entire mesh and compute reasonable normal estimates in most cases.

Keywords

There are no keywords for this method.


IDLgrText

A text object represents one or more text strings that share common rendering attributes.

An IDLgrText 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.

Note	An IDLgrText object can not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrText::Init (page 205).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrText::Cleanup (page 202)

•	IDLgrText::GetCTM (page 203)

•	IDLgrText::GetProperty (page 204)

•	IDLgrText::Init (page 205)

•	IDLgrText::SetProperty (page 208)


IDLgrText::Cleanup

The IDLgrText::Cleanup procedure method performs all cleanup on the object. IDLgrText is described on page 71.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrText::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrText::GetCTM

The IDLgrText::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrText is described on page 202.

Calling Sequence

Obj->[IDLgrText::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrText::GetProperty

The IDLgrText::GetProperty procedure method retrieves the value of a property or group of properties for the text. IDLgrText is described on page 202.

Calling Sequence

Obj ->[IDLgrText::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrText::Init (page 205) followed by the word "Get" can be retrieved using IDLgrText::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrText::Init

The IDLgrText::Init function method initializes the text object. IDLgrText is described on page 202.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrText' [, String])

or

Result = Obj -> [IDLgrText::]Init([, String] )
(In a subclass' Init method only.)

Arguments

String

The string (or vector of strings) to be created.  If this argument is not a string, it is converted prior to using the default formatting rules.

Keywords

Properties retrievable via IDLgrText::GetProperty (page 204) are indicated by the word "Get" following the keyword. Properties settable via IDLgrText::SetProperty (page 208) are indicated by the word "Set" following the keyword.

ALIGNMENT (Get, Set)

Set this keyword to a floating point value between 0.0 and 1.0 to indicate the requested alignment of the text baseline.  An alignment of 0.0 (the default) aligns the left-justifies the text at the given position; an alignment of 1.0 right-justifies the text, and an alignment of 0.5 centers the text over the given position.

BASELINE (Get, Set)

Set this keyword to a two (or three) element vector describing the direction in which the baseline is to be oriented.  Use this keyword in conjunction with the UPDIR keyword to specify the plane on which the text lies.  The default BASELINE is [1.0,0,0] (i.e., parallel to the x-axis).

COLOR (Get, Set)

Set this keyword to the color to be used as the foreground color for this model.  The color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).  The default is [255, 255, 255]

FONT (Get, Set)

Set this keyword to an instance of an IDLgrFont object class to describe the font to use to draw this string.  The default is 12 pt. Helvetica.

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

 The default is `Copy'.  Valid values include the following:

•	0 = Copy: Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

LOCATIONS

Set this keyword to an array of one or more two- or three-element vectors specifying the coordinates used to position the string(s).  Each vector is of the form [x, y]  or [x, y, z]. By default, locations are measured in data units.  Each location corresponds to the corresponding string in the String argument.  If only one location is provided, and the String argument is a vector of more than one strings, the initial string is positioned at the given location, and each subsequent string is positioned at the end of the previous string.  If z is not provided for each location, the text is strictly 2D, and is displayed `on the glass'.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

ONGLASS (Get, Set)

Set this keyword to indicate that the text should be displayed "on the glass". The default is projected 3D text.

STRINGS (Get, Set)

Set this keyword to the string (or vector of strings) associated with the text object. This keyword is the same as the String argument described above.

UPDIR (Get, Set)

Set this keyword to a two (or three) element vector describing the vertical direction for the string.  Use this keyword in conjunction with the BASELINE keyword to specify the plane on which the text lies.  The default UPDIR is [0.0, 1.0, 0.0] (i.e., parallel to the Y- axis).

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].


IDLgrText::SetProperty

The IDLgrText::SetProperty procedure method sets the value of a property or group of properties for the text. IDLgrText is described on page 202.

Calling Sequence

Obj ->[IDLgrText::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrText::Init (page 205) followed by the word "Set" can be retrieved using IDLgrText::SetProperty.


IDLgrView

A view object represents a rectangular area in which graphics objects are drawn.

Superclasses

This class is a subclass of IDL_Container (page 70).

Subclasses

This class has no subclasses.

Creation

See IDLgrView::Init (page 212).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrView::Add (page 209)

•	IDLgrView::Cleanup (page 210)

•	IDLgrView::GetByName (page 211)

•	IDLgrView::GetProperty (page 211)

•	IDLgrView::Init (page 212)

•	IDLgrView::Remove (page 214)

•	IDLgrView::SetProperty (page 215)


IDLgrView::Add

The IDLgrView::Add procedure method adds a child to this view. IDLgrView is described on page 209.

Calling Sequence

Obj ->[IDLgrView::]Add, Model

Arguments

Model

An instance of the IDLgrModel (page 125) object class.

Keywords

There are no keywords for this method.


IDLgrView::Cleanup

The IDLgrView::Cleanup procedure method performs all cleanup on the object. IDLgrView is described on page 209.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrView::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrView::GetByName

The IDLgrView::GetByName function method finds contained objects by name. IDLgrView is described on page 209.

Calling Sequence

Result = Obj ->[IDLgrView::]GetByName(Name)

Arguments

Name

The name of the object to be returned.

Keywords

There are no keywords for this method.


IDLgrView::GetProperty

The IDLgrView::GetProperty procedure method retrieves the value of the property or group of properties for the view. IDLgrView is described on page 209.

Calling Sequence

Obj->[IDLgrView::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrView::Init (page 212) followed by the word "Get" can be retrieved using IDLgrView::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.


IDLgrView::Init

The IDLgrView::Init function method initializes the view object. IDLgrView is described on page 209.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrView')

or

Result = Obj -> [IDLgrView::]Init( )         (In a subclass' Init method only.)

Arguments

There are no arguments for this method.

Keywords

Properties retrievable via IDLgrView::GetProperty (page 211) are indicated by the word "Get" following the keyword. Properties settable via IDLgrView::SetProperty (page 215) are indicated by the word "Set" following the keyword.

CHANNEL (Get, Set)

Set this keyword to a long integer bitmask representing the RGB and CI color modes. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. For example, 'ff0000'X represents a Red channel write. The default is represented by 0xffffff.

COLOR (Get, Set)

Set this keyword to the color for the view.  This is the color to which the view area will be erased before its contents are drawn. The color may be specified as a color lookup table index (accepted by graphics destinations using either the  Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model). The default is [0, 0, 0].

DEPTH_CUE (Get, Set)

Set this keyword to a two-element floating point array: [zbright, zdim]. The object itself is set to zbright, while the background color is defined by zdim. You can disable depth cueing by setting zbright = zdim. The default is [0.0, 0.0].

DIMENSIONS (Get, Set)

Set this keyword to a two-element vector of the form [width, height] specifying the dimensions of the viewport (the rectangle in which models are displayed on a graphics destination).  By default, the viewport dimensions are set to [0, 0], which indicates that it will match the dimensions of the graphics destination to which it is drawn. The dimensions are measured in the units specified by the UNITS keyword.

EYE (Get, Set)

Set this keyword to specify the distance from the eyepoint to the viewplane. The default is 1.0.

LOCATION (Get, Set)

Set this keyword to a two-element vector of the form [x, y] specifying the position of the lower lefthand corner of the view.  The default is [0, 0], and is measured in device units (refer to the UNITS keyword).

PROJECTION (Get, Set)

Set this keyword to indicate the type of projection to use within this view. All models displayed within this view will be projected using this type of projection. Valid values are described below.

•	1 = Orthogonal projection (default)

•	2 = Perspective: Indicates that all models are projected toward the eye (located at the origin), which is the apex of the viewing frustum. With a perspective projection, models that are farther away from the eye will appear smaller in the view than models that are nearer to the eye.

TRANSPARENT (Get, Set)

Set this keyword to disable the viewport erase, making the viewport transparent.

UNITS (Get, Set)

Set this keyword to specify the units of measure for this view.  Valid values include:

•	0 = Device (default)

•	1 = Inches

•	2 = Centimeters

•	3 = Normalized: relative to the graphics destination's rect.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

VIEWPLANE_RECT (Get, Set)

Set this keyword to a four-element vector of the form [x, y, width, height] to describe the bounds in x and y of the view volume. A view volume describes what portion of a model get projected into the viewport. These values are measured in normalized space. The default is [0, 0, 1, 1]

Note	The z bounds of the view volume are set via the ZCLIP keyword.

ZCLIP (Get, Set)

Set this keyword to a two element vector representing the near and far clipping planes to be applied to the objects in this view.  The vector should take the form [near, far].  By default, these values are [1, -1].


IDLgrView::Remove

The IDLgrView::Remove procedure method removes a model from the view. IDLgrView is described on page 209.

Calling Sequence

Obj ->[IDLgrView::]Remove, Model

Arguments

Model

An instance of the IDLgrModel object class to be removed from the view.

Keywords

There are no keywords for this method.


IDLgrView::SetProperty

The IDLgrView::SetProperty procedure method sets the value of the property or group of properties for the view. IDLgrView is described on page 209.

Calling Sequence

Obj->[IDLgrView::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrView::Init (page 212) followed by the word "Set" can be retrieved using IDLgrView::SetProperty.


IDLgrVolume

A volume object represents a mapping from a three-dimensional array of data to a three-dimensional array of voxel colors, which, when drawn, are projected to two dimensions.

An IDLgrVolume 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.

Note	An IDLgrVolume object can not have any children.

Superclasses

This class has no superclasses.

Subclasses

This class has no subclasses.

Creation

See IDLgrVolume::Init (page 220).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrVolume::Cleanup (page 216)

•	IDLgrVolume::ComputeBounds (page 217)

•	IDLgrVolume::GetCTM (page 218)

•	IDLgrVolume::GetProperty (page 219)

•	IDLgrVolume::Init (page 220)

•	IDLgrVolume::PickVoxel (page 224)

•	IDLgrVolume::SetProperty (page 225)


IDLgrVolume::Cleanup

The IDLgrVolume::Cleanup procedure method performs all cleanup on the object. IDLgrVolume is described on page 216.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrVolume::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrVolume::ComputeBounds

The IDLgrVolume::ComputeBounds procedure method computes the smallest bounding box that contains all voxels whose opacity lookup is greater than a given opacity value. The BOUNDS keyword of IDLgrVolume::Init (220) is updated to the computed bounding box. IDLgrVolume is described on page 216.

Calling Sequence

Result = Obj ->[IDLgrVolume::]ComputeBounds

Arguments

There are no arguments for this method.

Keywords

OPACITY

Set this keyword to the opacity value to be used to determine which voxels are to be included in the bounding box. All voxels whose opacity lookup is greater than this value will be included. The default value is zero.

RESET

Set this keyword to cause the BOUNDS keyword of IDLgrVolume::Init (220) to be reset to contain the entire volume.


IDLgrVolume::GetCTM

The IDLgrVolume::GetCTM procedure method returns the 4 x 4 graphics transform matrix from the current object upward through the graphics tree. IDLgrVolume is described on page 216.

Calling Sequence

Obj->[IDLgrVolume::]GetCTM

Arguments

There are no arguments for this method.

Keywords

DESTINATION

Set this keyword to a destination object to specify that the projection matrix for the View object in the current tree be included in the returned matrix. The resulting matrix will transform a point in the data space of the self object into a normalized coordinate system (-1 to +1 in X, Y, and Z).

TOP

Set this keyword to an instance of an IDLgrModel object to specify that the returned matrix accumulate from the self object up until, but not including, the specified model object.

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.


IDLgrVolume::GetProperty

The IDLgrVolume::GetProperty procedure method retrieves the value of a property or group of properties for the volume. IDLgrVolume is described on page 216.

Calling Sequence

Obj ->[IDLgrVolume::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrVolume::Init (page 220) followed by the word "Get" can be retrieved using IDLgrVolume::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

PARENT

Set this keyword to return a reference to the parent of the object.

XRANGE

A two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by thhe graphic object.

YRANGE

A two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object.

ZRANGE

A two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object.


IDLgrVolume::Init

The IDLgrVolume::Init function method initializes the volume object. At least one volume method must be specified, via arguments or keywords. IDLgrVolume is described on page 216.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrVolume' [, vol0 ])

or

Result = Obj -> [IDLgrVolume::]Init([vol0 ] )         (In a subclass' Init method only.)

Arguments

vol0

This value is a shortcut for the DATA0 keyword (e.g. vol0 is the same as DATA0 = vol0).

Keywords

Properties retrievretrievable via IDLgrVolume::GetProperty (page 219) are indicated by the word "Get" following the keyword. Properties settable via IDLgrVolume::SetProperty (page 225) are indicated by the word "Set" following the keyword.

AMBIENT (Get, Set)

Use this keyword to set the color/intensity of the volume's base ambient lighting. Color is specified as an RGB vector. The default is [255.0, 255.0, 255.0]. AMBIENT is applicable only when LIGHTING_MODEL is set.

BOUNDS (Get, Set)

Set this keyword to a six-element vector of the form [xmin, ymin, zmin, xmax, ymax, zmax], which represents the sub-volume to be rendered.

COLOR (Get, Set)

Set this keyword to the color to be used as the foreground color for this model.  The color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).  The default is [255, 255, 255]

COMPOSITE_FUNCTION (Get, Set)

The composite function determines the value of the pixel on the viewing plane by analyzing the voxels falling along the coresponding ray according to one of the following compositing functions:

•	0 = Alpha (default): Alpha-blending. The recursive equation, dest' = src * srcalpha + dest * (1 - srcalpha), is used to find the voxel with the highest color value.

•	1 = MIP: Maximum intensity projection. The value of each pixel on the viewing plane is set to the brightest voxel, as determined by its opacity. The most opaque voxel's color appropriation is then reflected by the pixel on the viewing plane.

•	2 = Alpha sum: Alpha-blending, The recursive equation, dest' = src + dest * ( 1 - srcalpha), is used to find the voxel with the highest color value. This equation assumes that the color tables have been pre-multipled by the opacity tables. The accumulated values are clamped to 255.

•	3 = Average: average-intensity projection. The resulting image is the average of all voxels along the corresponding ray.

CUTTING_PLANES (Get, Set)

Set this keyword to a floating point array with dimensions (4, n) specifying the coefficients of n cutting planes. The cutting plane coefficients are in the form {{nx, ny, nz, D}, ...} where (nx)X+(ny)Y+(nz)Z+ D > 0, and (X, Y, Z) are the voxel coordinates.  To clear the cutting planes, pass any scalar value (e.g. CUTTING_PLANES = 0) By default, no cutting planes are defined.

DATA0 (Get, Set)

Set this keyword to a three-element array of the format BYTARR(dx, dy, dz), which specifies a data volume. Volumes must be three-dimensional and in byte format. The dimensions of the object are fixed at initialization and persist for the life of the object.

DEPTH_CUE (Get, Set)

Set this keyword to a two-element array of the form [Zbright, Zdim]. These values define a linear ramp from 1.0 at Zbright to 0.0 at Zdim. Voxel brightnesses are modulated by values from this ramp according to their Z values. Any voxels with Z values outside of the domain defined by [Zbright, Zdim] have their Z values clamped to the nearest limit before looking up a ramp value. To disable depth cueing, set DEPTH_CUE to [0, 0].

The relationship between Zbright and Zdim determines the result of the rendering:

•	Zbright < Zdim: Rrendering darkens with depth.

•	Zbright > Zdim: Rendering brightens with depth.

•	Zbright = Zdim: Disables depth queuing.

Set this keyword to a two-element array of the form [Zbright, Zdim]. Voxel brightnesses are modulated by a ramp in Z from the default of [1.0, 0.0]. All values of Z must be within the range of 0.0 ≤ Z ≤ 1.0, or they will be clamped to the appropriate bounding value. Setting Zbright equal to Zdim disables depth cueing.

GRAPHICS_FUNCTION (Get, Set)

Set this keyword to a string indicating the graphics function to be used to draw this model. This is a logical function which specifies how the source pixel values are combined with the destination pixels values.

Note	The graphics function is allowed only for Color Indexed destination models. On all other destinations, this function will be ignored.

 The default is `Copy'.  Valid values include the following:

•	0 = Copy: Source

•	1 = And: Source AND destination.

•	2 = Or: Source OR destination

•	3 = Nand: (NOT source) OR(NOT destination)

•	4 = Nor: (NOT source) AND (NOT destination)

•	5 = XOR: Source XOR destination

HIDE (Get, Set)

Set this keyword to a boolean value indicating whether this object should be drawn:

•	0: Do not draw graphic

•	1 (default): Draw graphic

INTERPOLATE (Get, Set)

Set this keyword to indicate that Trilinear interpolation is to be used to determine the data value for each step on a ray.  Setting this keyword improves the quality of images produced, at the cost of more computing time. especially when the volume has low resolution with respect to the size of the viewing plane. Nearest_Neighbor sampling is used by default.

LIGHTING_MODEL (Get, Set)

Set this keyword to use the current lighting model during rendering in conjunction with a local gradient evaluation.

NAME (Get, Set)

Set this keyword to a string that will contain the name associated with this object. The default is the null string, ' '.

NO_COPY (Get, Set)

Set this keyword to relocate volume data from the input variables to the volume object, leaving the input variables undefined. Only the DATA0 keyword and the vol0 argument are affected. If this keyword is omitted, the input volume data will be duplicated and a copy will be stored in the object.

OPACITY_TABLE0 (Get, Set)

Set this keyword to a value of the form BYTARR(256) to specify an opacity table. The default table is the linear ramp.

RENDER_STEP (Get, Set)

Set this keyword to a three element vector of the form [x. y. z] to specify the stepping factor through the voxel matrix.

RGB_TABLE0 (Get, Set)

Set this keyword to an array of the form BYTARR(3, 256) to specify an RGB color table. The default table is the linear ramp.

TWO_SIDED (Get, Set)

Set this keyword to force the lighting model to use a two-sided voxel gradient. The two-sided gradient is different from the one-sided gradient (default) in that the absolute value of the inner product of the light direction and the surface gradient is used instead of clamping to 0.0 for negative values.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model X coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[ (-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Y coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0].

ZBUFFER (Get, Set)

Set this keyword to clip the rendering to the current Z-bufferr and then update the buffer. The default is to not modify the current Z-buffer.

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [s0, s1], of scaling factors used to convert model Z coordinates from data units to normalized units.  The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0].

ZERO_OPACITY_SKIP (Get, Set)

Set this keyword to skip voxels with an opacity of 0. This keyword can increase the output contrast of MIP (MAXIMUM_INTENSITY) projections by allowing the background to show through. If this keyword is set, voxels with an opacity of zero will not modify the Z-buffer. The default (not setting the keyword) continues to render voxels with an opacity of zero.


IDLgrVolume::PickVoxel

The IDLgrVolume::PickVoxel function method computes the coordinates of the voxel projected to a location specified by the 2D device coordinates point, [xi, yi], and the current Z-buffer. The function returns the volume indices as a a vector of three longs. IDLgrVolume is described on page 216.

Calling Sequence

Result = Obj ->[IDLgrVolume::]PickVoxel [win, view, [xp, yp]]

Arguments

Win

The IDLgrWindow object from which the Z-buffer is to be used.

Point

The X, Y viewport coordinates of the point chosen.

Keywords

There are no keywords for this method.


IDLgrVolume::SetProperty

The IDLgrVolume::SetProperty procedure method sets the value of a property or group of properties for the volume. IDLgrVolume is described on page 216.

Calling Sequence

Obj ->[IDLgrVolume::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrVolume::Init (page 220) followed by the word "Set" can be retrieved using IDLgrVolume::SetProperty.


IDLgrWindow

A window object is a representation of an on-screen area on a display device that may serve as a graphics source or destination.

Note	Objects or subclasses of this type can not be saved or restored.

Superclasses

This class has no superclass.

Subclasses

This class has no subclasses.

Creation

See IDLgrWindow::Init (page 232).

Methods

Intrinsic Methods

This class has the following methods:

•	IDLgrWindow::Cleanup (page 227)

•	IDLgrWindow::Draw (page 227)

•	IDLgrWindow::Erase (page 228)

•	IDLgrWindow::Flush (page 228)

•	IDLgrWindow::GetProperty (page 230)

•	IDLgrWindow::Iconify (page 231)

•	IDLgrWindow::Init (page 232)

•	IDLgrWindow::Pickdata (page 234)

•	IDLgrWindow::Read (page 235)

•	IDLgrWindow::Select (page 235)

•	IDLgrWindow::SetCurrentCursor (page 237)

•	IDLgrWindow::SetProperty (page 238)


IDLgrWindow::Cleanup

The IDLgrWindow::Cleanup procedure method performs all cleanup on the object. IDLgrWindow is described on page 226.

Note	Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj ->[IDLgrWindow::]Cleanup                               (In a subclass' Cleanup method only.)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrWindow::Draw

The IDLgrWindow::Draw procedure method draws the given view to this graphics destination. IDLgrWindow is described on page 226.

Calling Sequence

Obj->[IDLgrWindow::]Draw, Picture

Arguments

Picture

An instance of an IDLgrScene or IDLgrView object..

Keywords

CREATE_INSTANCE

Set this keyword to specify that this scene is the unchanging part of a drawing.

DRAW_INSTANCE

Set this keyword to specify that this scene is the changing part of a drawing. It is overlaid on the result of the most recent CREATE_INSTANCE draw.

NOERASE

Set this keyword to retain the previous contents of the window. By default, the window is cleared before drawing is initiated.


IDLgrWindow::Erase

The IDLgrWindow::Erase procedure method erases the entire contents of the window. IDLgrWindow is described on page 226.

Calling Sequence

Obj->[IDLgrWindow::]Erase

Arguments

There are no arguments for this method.

Keywords

COLOR

Set this keyword to the color to be used for the erase. The color may be specified as a color lookup table index (accepted by graphics destinations using either the Indexed or RGB color model), or as an RGB vector (accepted only by graphics destinations using the RGB color model).


IDLgrWindow::Flush

The IDLgrWindow::Flush procedure method causes all buffered output to the window to be written to the screen. IDLgrWindow is described on page 226.

Calling Sequence

Obj->[IDLgrWindow::]Flush

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrWindow::GetProperty

The IDLgrWindow::GetProperty procedure method retrieves the value of a property or group of properties for the window. IDLgrWindow is described on page 226.

Calling Sequence

Obj->[IDLgrWindow::]GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrWindow::Init (page 232) followed by the word "Get" can be retrieved using IDLgrWindow::GetProperty. In addition, the following keywords are available:

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

Note	The fields of this structure may change in subsequent releases of IDL.

IMAGE_DATA

Set this keyword to a variable that will contain a byte array reresenting the image that is currently displayed in the window.

Following are the returned images for the window if COLORMODEL, from IDLgrWindow::Init, is set to:

•	0 (RGBA): (3, winXSize, winYSize)

•	1 (Color Indexed): (3, winXSize, winYSize),

where winXSize and winYsize are the dimensions of the window in pixels. See "IDLgrWindow::Read" on page 235 for more information.

PARENT

Set this keyword to return a reference to the parent of the object.

RESOLUTION

Set this keyword to a a vector of the form [xres, yres] that will contain the pixel resolution measured in centimeters per pixel.

SCREEN_DIMENSIONS

Set this keyword to a variable that will contain a two-element vector of the form [width, height] specifying the dimensions of the overall screen dimensions for the screen with which this window is associated.  The screen dimensions are measured in device units.

ZBUFFER_DATA

Set this keyword to a variable that will contain a 2D floating point array representing the depth values in the Z-buffer associated with the window. The dimensions of the returned array are (winXSize, winYSize), where winXSize and winYSize are the dimensions of the window measured in pixels.


IDLgrWindow::Iconify

The IDLgrWindow::Iconify procedure method iconifies or de-iconifies the window. IDLgrWindow is described on page 226.

Note	Iconification under window systems is solely handled by the window manager; client applications, such as IDL, do not have the capability to manage icons. The Iconify method provides a hint to the window manager, which applies the information as it sees fit.

Calling Sequence

Obj->[IDLgrWindow::]Iconify, IconFlag

Arguments

IconFlag

Set IconFlag to 1 to iconify the window or set it to 0 to restore the window. If the window is already restored, it is brought to the front of the window stack.

Keywords

There are no keywords for this method.


IDLgrWindow::Init

The IDLgrWindow::Init function method initializes the window object. IDLgrWindow is described on page 226.

Note	Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Calling Sequence

Obj = OBJ_NEW('IDLgrWindow')

or

Result = Obj -> [IDLgrWindow::]Init( )         (In a subclass' Init method only.)

Arguments

There are no arguments for this method.

Keywords

Properties retrievable via IDLgrWindow::GetProperty (page 230) are indicated by the word "Get" following the keyword. Properties settable via IDLgrWindow::SetProperty (page 238) are indicated by the word "Set" following the keyword.

BYPASS_TRANSLATION (Get, Set)

Set this keyword to bypass the translation tables, allowing direct specification of color indices. Pixel values read via the TVRD function are not translated if this keyword is set, and the result contains the byte value of the actual pixel values present in the display.

By default, the translation tables are used with shared and static color tables. When using displays with private color tables, the translation tables are bypassed.

This keyword is accepted by the WIN device (for compatibility with the X device), but has no effect when set.

COLOR_MODEL (Get)

Set this keyword to the color model to be used for the buffer:

•	0 = RGB (default)

•	1 = Color Index

DIMENSIONS (Get, Set)

Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the window.  By default, the dimensions are set to fit one quadrant of the display screen, and are measured in device units (refer to the UNITS keyword).

DISPLAY_NAME (Get) [X Only]

Set this keyword to the name of the display on which the window is to appear.

LOCATION (Get, Set)

Set this keyword to a two-element vector of the form [x, y] to specify the location of the lower lefthand corner of the window relative to the display screen.  By default, the window is positioned at one of four quadrants on the display screen, and the location is measured in device units (refer to the UNITS keyword).

N_COLORS (Get)

Set this keyword to the number of colors (between 2 and 256) to be used if COLOR_MODEL is set to Indexed. This keyword is ignored if COLOR_MODEL is set to RGB.

PALETTE

Set this keyword to a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values that are to be loaded into the graphics destination's color lookup table, applicable if the Indexed color model is used.

PIXMAP (Get)

Set this keyword to a cause the window to be created in a non-visible portion of display memory called a pixmap. By default, PIXMAP is set to zero; the window is displayed on the screen.

QUALITY (Get, Set)

Set this keyword to a string indicating the quality at which graphics are to be drawn to this destination.  Valid values include:

•	0 = Low

•	1 = Medium

•	2 = High (default).

RETAIN (Get)

Set this keyword to zero, one, or two to specify how backing store should be handled for the window.

•	RETAIN=0 specifies no backing store.

•	RETAIN=1 specifies that the server or window system provide backing store.

•	RETAIN=2 specifies that IDL provide backing store directly.

TITLE (Get, Set)

Set this keyword to a string that represents the title of the window.

TRANSLATION (Get) [X Only]

Set this keyword to a byte array representing the X shared colormap indices to be used by this window.  This allows multiple, simultaneous IDL sessions to use the same colors from a shared colormap. IDL will use the shared color map without allocating any additional colors, and will not load the grayscale color ramp by default.

UNITS (Get, Set)

Set this keyword to indicate the units of measure for the LOCATION and DIMENSIONS keywords.  Valid values include:

•	0 = Device (default)

•	1 = Inches

•	2 = Centimeters

•	3 = Normalized: relative to the graphics destination's rect.

UVALUE (Get, Set)

Set this keyword to a value of any type that represents the "user value".


IDLgrWindow::Pickdata

The IDLgrWindow::Pickdata function method maps a point from the output device to the data space of a model. The resulting 3D dataspace coordinates are returned in the array OUTPUTXYZ. IDLgrWindow is described on page 226.

Calling Sequence

Result = Obj->[IDLgrWindow::]Pickdata()

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrWindow::Read

The IDLgrWindow::Read function method reads an image from a window.  The returned value is an instance of the IDLgrImage object class. IDLgrWindow is described on page 226.

Calling Sequence

Result = Obj->[IDLgrWindow::]Read()

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrWindow::Select

The IDLgrWindow::Select function method returns a list of objects. If no objects are selected, -1 is returned. IDLgrWindow is described on page 226.

Calling Sequence

Result = Obj->[IDLgrWindow::]Select(Picture[, X, Y])

Arguments

Picture

The view (an instance of the IDLgrView or the IDLgrSceneclass) whose children are among the candidates for selection.

If the first argument is a scene, then the returned object list will contain one or more views. If the first argument is a view, the list will contain basic graphic objects or model objects which have their SELECT_TARGET property set. Objects are returned in order, according to their distance from the viewer. The closer an object is to the viewer, the lower its index in the returned object list. If multiple objects are at the same distance from the viewer (views in a scene or 2D geometry), the last object drawn will appear at a lower index in the list.

X, Y

The center of the selection box in device space. By default, the selection box is 3x3 pixels.

Keywords

CONTAINED

Set this keyword if the list of returned objects is to include only those objects that are completely contained within the selection region.  This keyword is ignored if the POINT keyword is used.

DIMENSIONS

Set this keyword to specify that the selection box will have a size [w, h] and will be centered about [x, y]. The box occupies the rect: (x-(w/2), y-(h/2)) - (x+(w/1), y+(h/2)). Any object which intersects this box is considered to be selected.

POINT

Set this keyword to a 2-element vector of the form [x, y] to indicate that the selection region is to be a point.  This keyword is mutually exclusive of the RECT  keyword.  By default, the point is measured in device units (refer to the UNITS keyword).

RECT

Set this keyword to a four-element vector of the form [x, y, width, height] to indicate that the selection region is to be a rectangle.  This keyword is mutually exclusive of the POINT keyword.  By default, the rect is measured in device units (refer to the UNITS keyword).

UNITS

Set this keyword to indicate the units of measure.  Valid values include:

•	0 = Device (default)

•	1 = Inches

•	2 = Centimeters

•	3 = Normalized: relative to the graphics destination's rect.


IDLgrWindow::SetCurrentCursor

The IDLgrWindow::SetCurrentCursor procedure method sets the current cursor image to be used while positioned over a drawing area. IDLgrWindow is described on page 226.

Calling Sequence

Obj->[IDLgrWindow::]SetCurrentCursor, [,CursorName]

Arguments

CursorName

A string which specifies which built-in cursor to use. This argument is ignored if one of the keywords to this routine is set. This string can be one of the following:

Keywords

IMAGE (X Only)

Set this keyword to a 16x16 column bitmap, contained in a 16-element short integer vector, specifying the cursor pattern. The offset from the upper-left pixel to the point that is considered the `hot spot' can be provided via the HOTSPOT keyword.

MASK (X Only)

When the IMAGE keyword is set, the MASK keyword can be used to simultaneously specify the mask that should be used. In the mask, bits that are set indicate bits in the IMAGE that should be seen and bits that are not are "masked" out".

HOTSPOT (X Only)

Set this keyword to a two-element vector specifying the (X, Y) pixel offset of the cursor "hot spot", the point which is considered to be the mouse position, from the upper left corner of the cursor image. This parameter is only applicable if IMAGE is provided. The cursor image is displayed top-down (the first row is displayed at the top).

STANDARD (X and Windows Only)

Set this keyword to change the appearance of the cursor in IDL graphics windows to a standard system cursor.


IDLgrWindow::SetProperty

The IDLgrWindow::SetProperty procedure method sets the value of a property or group of properties for the window. IDLgrWindow is described on page 226.

Calling Sequence

Obj->[IDLgrWindow::]SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrWindow::Init (page 232) followed by the word "Set" can be retrieved using IDLgrWindow::SetProperty.