Welcome to the L3 Harris Geospatial documentation center. Here you will find reference guides and help documents.
﻿

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

### 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 + !X.S * X, !Y.S + !Y.S * Y, \$`
`      !Z.S + !Z.S * Z, 1]`
`   ; Transform by !P.T:`
`   P = P # !P.T`
`   ; Return the scaled result as a two-element,`
`   ; two-dimensional, xy vector:`
`   RETURN, [P / P, P / P]`
`END`

## Version History

 Pre 4.0 Introduced