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

>  Docs Center  >  IDL Reference  >  iTools  >  IELLIPSE

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