Routines (alphabetical) > Routines: I > IELLIPSE

# IELLIPSE

Note: IELLIPSE creates an annotation object with an identifier of `OVAL`. This identifier must be used when manipulating the object with routines like ISETPROPERTY.

Note: If you create the ellipse with an anisotropic coordinate system, the resulting ellipse object might not appear as expected. If the ellipse object appears distorted, try using device input coordinates.

## Examples

In the following example, we overlay an ellipse on an interesting muscle tissue feature.

; Open the data

file = FILEPATH('muscle.jpg', $

SUBDIRECTORY = ['examples', 'data'])

; Create an iTool with the image data

IIMAGE, file, TITLE = 'Muscle Tissue', IDENTIFIER = iToolID

; Ellipse center (in data space coordinates)

center = [238, 315]

; Major and minor axis distances (data space coords)

majAxisDist = 50.0

minAxisDist = 30.0

; Calculate the ellipse eccentricity

eccentricity = SQRT(1 - (minAxisDist^2 / majAxisDist^2))

; Write the ellipse to the iTool's data space

IELLIPSE, majAxisDist, center[0], center[1], $

/DATA, ECCENTRICITY = eccentricity, $

VISUALIZATION = iToolID, THETA = 120

; Change the ellipse's color, thickness, and transparency

ISETPROPERTY, 'oval', THICK=3, COLOR=[240,0,0], FILL_BACKGROUND=0

## Syntax

IELLIPSE, A, X, Y [, Z] [, /DATA | , /DEVICE | , /NORMAL] [, ECCENTRICITY=Value] [, IDENTIFIER=Variable] [, PROPERTY=Value] [, TARGET_IDENTIFIER=iToolID] [, THETA=Value] [, TOOL=iToolID] [, /VISUALIZATION]

## Arguments

### A

The length of the semi-major axis, specified in normalized coordinates, unless the DATA or DEVICE keyword is set.

### X, Y, Z

The center point of the ellipse, specified in normalized coordinates, unless the DATA or DEVICE keyword is set.

## Keywords

Any property of an ellipse annotation can be set using this routine. To set the value of a property, specify the property name as a keyword set equal to the appropriate property value. See ISETPROPERTY for details.

### 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 (pixels).

### ECCENTRICITY

Set this keyword to a floating-point value between 0.0 and 1.0 specifying the eccentricity of the ellipse, defined here as

where `a` is the length of the semi-major axis and `b` is the length of the semi-minor axis. If a value is not supplied, a default value of 0 (representing a circle) is used.

### IDENTIFIER

Set this keyword to a named variable that will contain the full identifier of the newly-created object.

### NORMAL

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

### TARGET_IDENTIFIER

Set this keyword to the iTools identifier of an object that is contained in the data space into which the ellipse object should be placed. If a value is not supplied, the first data space in the current view is used.

### THETA

Set this keyword to the angle (in degrees) to rotate the object.

If a single value is supplied, the ellipse is rotated counter-clockwise from horizontal.

If a three-element vector is supplied, the values define the degrees of rotation around the X, Y, and Z axis, respectively. Rotation is applied in the order of X, Y, and then Z.

If a value is not supplied, a default of 0 ([0,0,0]) is used.

Note: The coordinate system is right-handed, such that when looking from a positive axis to the origin, a positive rotation is counter-clockwise.

### TOOL

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

### VISUALIZATION

Set this keyword to add the object to the data space. If this keyword is not set, the object is added to the annotation layer.

## Version History

7.1 | Introduced

## See Also

IPOLYLINE, IPOLYGON, ICONVERTCOORD, ITEXT