NCL Home > Documentation > HLUs > Classes

Transform class

The Transform class provides its subclasses with the ability to handle coordinate transformations.

Synopsis

Header file:		ncarg/hlu/Transform.h
Class name:		transformClass
Class pointer:		<Not referenceable>
Fortran class function:	<Not referenceable>
Superclass:		View
Composite classes:	<None>

Class-defined types


Type name:		NhlTOverlayMode
Definition:
typedef enum _NhlOverlayMode {
	NhlDATATRANSFORM	= 0,	/* "DataTransform" 	*/
	NhlNDCVIEWPORT		= 1,	/* "NDCViewport"  	*/
	NhlNDCDATAEXTENT	= 2	/* "NDCDataExtent"	*/
} NhlOverlayMode;

Resources

Local resources

+---------------------------------------------------------------+
|			Transform Resource Set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| tfDoNDCOverlay                NhlTOverlayMode         RCSG    |
|       TfDoNDCOverlay                  DataTransform           |
|---------------------------------------------------------------|
| tfPlotManagerOn               NhlTBoolean             RCG     |
|       TfPlotManagerOn                 True                    |
|---------------------------------------------------------------|
| tfPolyDrawList		NhlTObjIdGenArray	CSG	|
|	TfPolyDrawList			Null  			|
|---------------------------------------------------------------|
| tfPolyDrawOrder               NhlTDrawOrder           RCSG    |
|       TfPlotManagerOn                 PostDraw                |
+---------------------------------------------------------------+

Composite resources

The Transform object class has no composite class resources.

Superclass resources

For any Transform class object, you can set all resources defined by the Transform class's superclasses, including:

View resources

Description

Objects that belong to the Transform class are viewable objects that support transformations between data coordinate space and NDC space. A Transform object may be called simply a transform. Most Transform subclasses have their own specialized plot elements that you can render by calling the object's NhlDraw method.

Transformation composite class

All subclasses of Transform include as a composite class member at least one subclass of the Transformation class to perform the forward and reverse transformations. There are currently six Transformation classes available to the subclasses of Transform:

The LogLinTransformation provides transformations to and from a linear or logarithmic coordinate space. Either or both coordinate axes may be logarithmic.
The IrregularTransformation provides transformations to and from rectangular coordinate spaces where each coordinate axis may be either irregularly spaced, linear, or logarithmic.
The CurvilinearTransformation provides transformations to and from topologically rectangular grids described using 2D coordinate arrays.
The SphericalTransformation provides transformations to and from topologically rectangular grids defined on the surface of a sphere using 2D coordinate arrays.
The TriangularMeshTransformation provides transformations for a triangular mesh of point data nodes. The triangular mesh can theoretically be created from any type of input grid including rectangular arrays or simply a random array of points. Currently, if the mesh is not pre-defined, only node sets without significant concavities in the boundary are handled reasonably.
The MapTransformation provides transformations to and from any of 10 different standard map projections.

PlotManager composite class

Subclasses of the Transform class may contain the PlotManager class as a composite class member. The PlotManager manages annotations and overlays on behalf of the transform. A transform instantiated with an active PlotManager is is known as a plot object.

Graphics primitives

In addition to their specialized plot elements, objects belonging to the Transform class have the ability to act as a "canvas" for arbitrary graphics primitives. You can either draw these primitives directly using immediate mode rendering, or else you can create Primitive objects that can be associated with any Transform object, to be drawn whenever the NhlDraw method is called for the transform.

You draw immediate mode primitives in data space using the NhlDataPolyline, NhlDataPolygon, and NhlDataPolymarker routines or in NDC space using the routines NhlNDCPolyline, NhlNDCPolygon, and NhlNDCPolymarker. Immediate mode primitives appear in the view space as soon as any of these primitive rendering routines is called. However, since they are not associated with any object, they cannot be made to reappear without explicitly calling the routine again using the same arguments.

Less ephemeral results may be achieved by creating Primitive objects of the graphics primitives. Once a primitive is associated with a Transform object it will be drawn whenever the NhlDraw method is invoked for the object. You add Primitive objects to a transform either by setting the resource tfPolyDrawList directly, or by calling the support function NhlAddPrimitive. You can remove a primitive from the draw list by calling NhlRemovePrimitive. Note that unlike when using immediate mode functions, you can specify the coordinates of Primitive objects in data space only.

Support functions

Transform defines the following support functions:

NhlNDCToData: Given arrays containing the X and Y coordinates of points in NDC space, the NhlNDCToData function returns arrays containing the X and Y coordinates of the same points in data coordinate space.
NhlDataToNDC: Given arrays containing the X and Y coordinates of points in data coordinate space, the NhlDataToNDC function returns arrays containing the X and Y coordinates of the same points in NDC space.
NhlDataPolyline: Given arrays containing the X and Y coordinates of points in data coordinate space, the NhlDataPolyline function outputs an immediate-mode polyline connecting each of the points.
NhlNDCPolyline: Given arrays containing the X and Y coordinates of points in NDC space, the NhlNDCPolyline function outputs an immediate-mode polyline connecting each of the points.
NhlDataPolygon: Given arrays containing the X and Y coordinates of points in data coordinate space, the NhlDataPolygon function outputs an immediate-mode polygon consisting of a filled area and an optional edge with the points at the vertices.
NhlNDCPolygon: Given arrays containing the X and Y coordinates of points in NDC space, the NhlNDCPolygon function outputs an immediate-mode polygon consisting of a filled area and an optional edge with the points at the vertices.
NhlDataPolymarker: Given arrays containing the X and Y coordinates of points in data coordinate space, the NhlDataPolymarker function outputs immediate-mode markers at each of the points.
NhlNDCPolymarker: Given arrays containing the X and Y coordinates of points in NDC space, the NhlNDCPolymarker function outputs immediate-mode markers at each of the points.
NhlIsTransform: This function just determines if a given object id identifies a Transform class object.

The following support functions are used to add Primitive objects to the tfPolyDrawList of a transform, and also to remove them.

NhlAddPrimitive

This function adds a Primitive object to the list of graphics primitives belonging to the Transform object.

NhlRemovePrimitive

This function removes a Primitive object from the list of graphics primitives belonging to the Transform object.

The following support functions are used to add overlays and annotations to plot objects, and also to remove them.

NhlAddOverlay: The NhlAddOverlay function adds transform as an overlay of a base plot.
NhlRemoveOverlay: The NhlRemoveOverlay function removes an overlay from a base plot.
NhlAddAnnotation: The NhlAddAnnotation function adds an arbitrary user-created View object to a plot object as an annotation, returning the id of a controlling AnnoManager object.
NhlRemoveAnnotation: The NhlRemoveAnnotation function removes the association between a user-created View object and the plot object to which it belongs as an annotation. It destroys the controlling AnnoManager object.