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* = 2*t*, *z* = *t*^{2}, 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.

## 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`

` ; 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 |