Routines (alphabetical) > Routines: C > CONVERT_COORD

# CONVERT_COORD

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.

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

## See Also

CV_COORD