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:
SURFACE, DIST(20), /SAVE
X = FINDGEN(11)/10.
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.
Additional Examples
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
P = [!X.S[0] + !X.S[1] * X, !Y.S[0] + !Y.S[1] * Y, $
!Z.S[0] + !Z.S[1] * Z, 1]
P = P # !P.T
RETURN, [P[0] / P[3], P[1] / P[3]]
END
Version History
See Also
CV_COORD