The CONVERT_COORD function transforms one or more sets of coordinates to and from the coordinate systems supported by IDL.

The input coordinates X and, optionally, Y and/or Z can be given in data, device, or normalized form by using the DATA, DEVICE, or NORMAL keywords. The default input coordinate system is DATA. The keywords TO_DATA, TO_DEVICE, and TO_NORMAL specify the output coordinate system.

If the input points are in 3D data coordinates, be sure to set the T3D keyword.

Note: CONVERT_COORD utilizes values currently stored in the !X, !Y, !Z and !P system variables to compute coordinate conversion factors.

Note: For devices that support windows, CONVERT_COORD can only provide valid results if a window is open and current. Also, CONVERT_COORD only applies to Direct Graphics devices.

Examples

Convert, using the currently established viewing transformation, 11 points along the parametric line x = t, y = 2t, z = t2, along the interval [0, 1] from data coordinates to device coordinates:

`; Establish a valid transformation matrix:`
`SURFACE, DIST(20), /SAVE`
` `
`; Make a vector of X values:`
`X = FINDGEN(11)/10.`
` `
`; Convert the coordinates. D will be a (3,11) element array:`
`D = CONVERT_COORD(X, 2*X, X^2, /T3D, /TO_DEVICE)`

To convert the endpoints of a line from data coordinates (0, 1) to (5, 7) to device coordinates, use the following statement:

`D = CONVERT_COORD([0, 5], [1, 7], /DATA, /TO_DEVICE)`

On completion, the variable D is a (3, 2) vector, containing the x, y, and z coordinates of the two endpoints.

For more examples, see Additional Examples near the bottom of this topic.

Syntax

Result = CONVERT_COORD( X [, Y [, Z]] [, /DATA | , /DEVICE | , /NORMAL] [, /DOUBLE][, /T3D] [, /TO_DATA | , /TO_DEVICE | , /TO_NORMAL] )

Return Value

The result of the function is a (3, n) vector containing the (x, y, z) components of the n output coordinates.

Arguments

X

A vector or scalar argument providing the X components of the input coordinates. If only one argument is specified, X must be an array of either two or three vectors (i.e., (2,*) or (3,*)). In this special case, X[0,*] are taken as the X values, X[1,*] are taken as the Y values, and, if present, X[2,*] are taken as the Z values.

Y

An optional argument providing the Y input coordinate(s).

Z

An optional argument providing the Z input coordinate(s).

Keywords

DATA

Set this keyword if the input coordinates are in data space (the default).

DEVICE

Set this keyword if the input coordinates are in device space.

DOUBLE

Set this keyword to indicate that the returned coordinates should be double-precision. If this keyword is not set, the default is to return single-precision coordinates (unless double-precision arguments are input, in which case the returned coordinates will be double-precision).

NORMAL

Set this keyword if the input arguments are specified in normalized [0, 1] coordinates relative to the entire window.

T3D

Set this keyword if the 3D transformation !P.T is to be applied.

TO_DATA

Set this keyword if the output coordinates are to be in data space.

TO_DEVICE

Set this keyword if the output coordinates are to be in device space.

TO_NORMAL

Set this keyword to convert the result to normalized [0, 1] coordinates relative to the entire window.

Three-Dimensional Direct Graphic Coordinate Conversion

The CONVERT_COORD function performs the three-dimensional coordinate conversion process (described in Three-Dimensional Coordinate Conversion) when converting to and from coordinate systems when the T3D keyword is specified. For example, if a three-dimensional coordinate system is established, then the device coordinates of the data point (0, 1, 2) can be computed as follows:

`D = CONVERT_COORD(0, 1, 2, /TO_DEVICE, /T3D, /DATA)`

On completion, the three-element vector D will contain the desired device coordinates. The process of converting from three-dimensional to two-dimensional coordinates also can be written as an IDL function. This function accepts a three-dimensional data coordinate, returns a two-element vector containing the coordinate transformed to two-dimensional normalized coordinates using the current transformation matrix:

`FUNCTION CVT_TO_2D, X, Y, Z`
`   ; Make a homogeneous vector of normalized 3D coordinates:`
`   P = [!X.S[0] + !X.S[1] * X, !Y.S[0] + !Y.S[1] * Y, \$`
`      !Z.S[0] + !Z.S[1] * Z, 1]`
`   ; Transform by !P.T:`
`   P = P # !P.T`
`   ; Return the scaled result as a two-element,`
`   ; two-dimensional, xy vector:`
`   RETURN, [P[0] / P[3], P[1] / P[3]]`
`END`

Version History

 Pre 4.0 Introduced