ICONVERTCOORD

The ICONVERTCOORD function converts between iTool coordinate systems.

This routine is written in the IDL language. Its source code can be found in the file iconvertcoord.pro in the lib/itools subdirectory of the IDL distribution.

Syntax

Result = ICONVERTCOORD( X, [Y [, Z]] [, /DATA | , /DEVICE | , /NORMAL] [, TARGET_IDENTIFIER=iToolID] [, /TO_DATA | , /TO_DEVICE | , /TO_NORMAL] [, TOOL=iToolID])

Return Value

Returns a [3 x n] vector containing the [X, Y, Z] components of the output coordinates.

Arguments

X

A vector or scalar value that provides the X components of the input coordinates.

If only one argument is specified, X must be an array of either two or three vectors. For example, [2,*] or [3,*]. In this special case, X[0,*] are the X values, X[1,*] are the Y values, and (if present) X[2,*] are the Z values.

Y

An optional vector or scalar value that provides the Y input coordinate(s).

Z

An optional vector or scalar value that provides the Z input coordinate(s).

Keywords

DATA

Set this keyword if the input arguments are specified in data coordinates.

DEVICE

Set this keyword if the input arguments are specified in device coordinates. These coordinates are based on the virtual window, taking into account any canvas zoom that may be applied to the window.

NORMAL

Set this keyword if the input arguments are specified in normalized [0, 1] coordinates (the default). These coordinates are view-specific.

TARGET_IDENTIFIER

Set this keyword to the iTools identifier of an object that is contained in the desired data space. If not supplied, the first data space in the first view is used.

TO_DATA

Set this keyword to convert the result to data space coordinates.

TO_DEVICE

Set this keyword to convert the result to device space coordinates. These coordinates are based on the virtual window, and take into account any canvas zoom that may be applied to the window.

TO_NORMAL

Set this keyword to convert the result to normalized [0, 1] space coordinates (the default). These coordinates are view-specific.

TOOL

Set this keyword to the iTools identifer of the iTool in which TARGET_IDENTIFIER is found. If not supplied, the current iTool is used.

Examples

In the following examples, we convert coordinates in an iPlot visualization between device, normal, and data coordinate systems.

IPLOT, /TEST, dimensions=[800,600]

; Lower left corner of window in normal space
PRINT, ICONVERTCOORD(0, 0, /DEVICE, /TO_NORMAL)

 
0.000000      0.000000      0.000000

; Dimensions of the window in device space
PRINT, ICONVERTCOORD(1, 1, /NORMAL, /TO_DEVICE)

 
800.000      600.000     0.000000

; Half of window dimensions, in device space
PRINT, ICONVERTCOORD(0.5, 0.5, /NORMAL, /TO_DEVICE)

 
400.00000      300.00000      0.000000

; Data coordinates near horizontal center [100, 0.5],
; in device space
PRINT, ICONVERTCOORD(100, 0.5, /DATA, /TO_DEVICE)

 
401.35678      394.80026      0.00000000

; The previous coordinates, converted to normal space
PRINT, ICONVERTCOORD(401, 395, /DEVICE, /TO_NORMAL)

 
0.50125000      0.65833333       0.00000000

; The previous coordinates, converted to data space
PRINT, ICONVERTCOORD(0.50125, 0.65833, /NORMAL, /TO_DATA)

 
99.868527      0.50092349      0.00000000

; Convert from data to normal space, and back again
PRINT, ICONVERTCOORD(ICONVERTCOORD(50, 0.5, /DATA, /TO_NORMAL), $
/NORMAL, /TO_DATA)

 
50.000000      0.50000000      0.00000000

Version History


7.1	Introduced