Use this procedure to create an ENVI Classic annotation file or to append items to an existing annotation file. If the annotation file does not exist, ENVI Classic creates a new annotation file and adds the specified item. If the annotation file exists, each subsequent call to ENVI_USER_DEFINED_ANNOTATION adds another annotation item to the file. The desired item is specified by the appropriate keywords and associated parameters.
Syntax
ENVI_USER_DEFINED_ANNOTATION, Name, X, Y [, ALIGN={0 | 0.5 | 1}] [, /ARROW] [, BGCOLOR=integer] [, CHARSIZE=floating point] [, COLOR=integer] [, /COL_RAMP] [, FILL_MODE={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7}] [, FILL_ORIEN=integer] [, FILL_SPACING=floating point] [, FONT=string] [, IMAGE=array] [, LSTYLE=integer] [, /MAP_KEY] [, ORIEN=integer], [, /POLYGON] [, /POLYLINE] [, /SCALE_BARS] [, STR_TEXT=string] [, /TEXT] [, THICK=integer] [, USE_MAP_COORDS=file ID]
Optional keywords for ARROW:
[, HEAD_ANGLE=floating point] [, HEAD_PCT=floating point]
Optional keywords for COL_RAMP:
[, RAMP_INC=integer] [, RAMP_LENGTH=integer] [, RAMP_MAX_VAL=floating point] [, RAMP_MIN_VAL=floating point] [, RAMP_ORIEN={0 | 1 | 2 | 3}] [, RAMP_PRECISION=integer] [, RAMP_WIDTH=integer]
Optional keywords for MAP_KEY:
[, KEY_FILL_MODE=integer] [, KEY_FILL_ORIEN=integer] [, KEY_FILL_SPACING=floating point]
Keywords for SCALE_BARS
PIXEL_SIZE=floating point [, SCALE_FLAG=array] [, SCALE_HEIGHT=integer] [, SCALE_INC=array] [, SCALE_LENGTH=array] [, SCALE_SUB_INC=array] [, SCALE_TITLES=string array]
Arguments
Name
This is a string variable specifying the annotation filename. If Name does not exist, ENVI Classic creates a new annotation file. If Name exists, ENVI Classic appends the desired item to the annotation file.
X
This is the x pixel location for the annotation item.
Y
This is the y pixel location for the annotation item.
Keywords
ALIGN (optional)
Use this keyword to specify the text alignment for annotation objects supporting this keyword. ALIGN is one of the following floating-point values:
- 0.0: Left justified
- 0.5: Centered
- 1.0: Right justified
ARROW (optional)
Set this keyword to specify that the annotation item is an arrow. If you set ARROW, the x and y location parameters are not used, but you must specify the keywords XPTS and YPTS to define the two end points of the arrow (in image coordinates). Optional keywords that you can use with ARROW include COLOR, FILL_MODE, FILL_ORIEN, FILL_SPACING, HEAD_ANGLE, HEAD_PCT, LSTYLE, and THICK.
BGCOLOR (optional)
Use this keyword to specify the background color index for annotation objects supporting this keyword. BGCOLOR is an integer color index where 0 is black, 1 is white, 2 is red, etc. Set BGCOLOR equal to -1 for no background.
CHARSIZE (optional)
Use this keyword to specify the character size for annotation objects supporting this keyword. CHARSIZE is a floating-point value specifying the character size.
COLOR (optional)
Use this keyword to specify the color index for annotation objects supporting this keyword. COLOR is an integer color index into the graphic colors where the default colors are 0 (black), 1 (white), 2 (red), etc.
COL_RAMP (optional)
Set this keyword to specify that the annotation item is a color ramp. If you set COL_RAMP, you must set the x and y location parameters (in image coordinates). Optional keywords that you can use with COL_RAMP include BGCOLOR, COLOR, CHARSIZE, FONT, RAMP_LENGTH, RAMP_INC, RAMP_MAX_VAL, RAMP_MIN_VAL, RAMP_ORIEN, RAMP_PRECISION, RAMP_WIDTH, and THICK.
FILL_MODE (optional)
Use this keyword to specify the IDL fill style for annotation objects supporting this keyword. FILL_MODE is one of the following integer values.
- 0: No fill
- 1: Solid fill
- 2: Solid line fill
- 3: Dotted line fill
- 4: Dashed line fill
- 5: Dash dot line fill
- 6: Dash dot dot line fill
- 7: Long dash line fill
FILL_ORIEN (optional)
Use this keyword to specify the rotation of fill for annotation objects supporting this keyword. FILL_ORIEN is an integer value greater than 1.
FILL_SPACING (optional)
Use this keyword to specify the spacing of fill for annotation objects supporting this keyword. FILL_SPACING is floating-point number. This keyword is only used for FILL_MODE values greater than 1.
FONT (optional)
Use this keyword to specify the font for annotation objects supporting this keyword. FONT is a string value specifying either a hershey font ('!3' to '!20') or a valid name for a true-type font ('Courier').
IMAGE (optional)
Use this keyword to specify an annotation image. IMAGE is a byte array with dimensions [num_samples, num_lines] for gray scale or [num_samples, num_lines, 3] for RGB images. If you set IMAGE, you must set the x and y location parameters (in image coordinates), which reference the lower-left corner of IMAGE.
LSTYLE (optional)
Use this keyword to specify the IDL line style for annotation objects supporting this keyword. LSTYLE is an integer value.
MAP_KEY (optional)
Set this keyword to specify that the annotation item is a map key. If you set MAP_KEY, you must set the x and y location parameters (in image coordinates) and specify the keywords KEY_COLORS and KEY_NAMES. Optional keywords for MAP_KEY include BGCOLOR, CHARSIZE, COLOR, FONT, KEY_FILL_MODE, KEY_FILL_ORIEN, KEY_FILL_SPACING, and THICK.
ORIEN (optional)
Use this keyword to specify the orientation for annotation objects supporting this keyword. ORIEN is an integer value specifying the clockwise rotation angle.
POLYGON (optional)
Set this keyword to specify that the annotation item is a polygon. If you set POLYGON, the x and y location parameters are not used, but you must use the keywords XPTS and YPTS to define the vertices of the polygon (in image coordinates). Optional keywords that you can use with POLYGON include COLOR, FILL_MODE, FILL_ORIEN, FILL_SPACING, LSTYLE, and THICK.
POLYLINE (optional)
Set this keyword to specify that the annotation item is a polyline. If you set POLYLINE, the x and y location parameters are not used, but you must use the keywords XPTS and YPTS to define the polyline vertices (in image coordinates). Optional keywords that you can use with POLYLINE include COLOR, LSTYLE, and THICK.
SCALE_BARS (optional)
Set this keyword to specify that the annotation item is a scale bar. If you set SCALE_BARS, you must specify the x and y location parameters (in image coordinates) and the keyword PIXEL_SIZE. Optional keywords that you can use with SCALE_BARS include BGCOLOR, COLOR, FONT, SCALE_FLAG, SCALE_HEIGHT, SCALE_INC, SCALE_LENGTH, SCALE_SUB_INC, SCALE_TITLES, and THICK.
STR_TEXT (optional)
Use this keyword to specify the text string for the annotation item TEXT. You must delineate multiple lines of text with !C!C. For example, 'Hello!C!CWorld' prints Hello and World on separate lines.
TEXT (optional)
Set this keyword to specify that the annotation item is a text string. If you set TEXT, you must specify the x and y location parameters and the STR_TEXT keyword. Optional keywords that you can use with TEXT include ALIGN, BGCOLOR, CHARSIZE, COLOR, FONT, ORIEN, and THICK.
THICK (optional)
Use this optional integer keyword to specify the line thickness of hershey-font characters for annotation objects supporting this keyword.
USE_MAP_COORDS (optional)
Set this keyword to the FID of a georeferenced image to put the (x,y) and (xpts,ypts) coordinates sent to this procedure in map coordinates instead of file coordinates.
Keywords for ARROW
HEAD_ANGLE (optional)
Use this keyword to specify the head angle of an ARROW annotation object. HEAD_ANGLE is a floating-point value greater than 0, specifying the angle in degrees of the arrow head. The default value is 35.0.
HEAD_PCT (optional)
Use this keyword to specify the size of the head for an ARROW annotation object. HEAD_PCT is a floating-point value between 0.0 and 1.0, specifying the percentage of the head size versus the overall length. The default value is 0.15.
Keywords for COL_RAMP
RAMP_INC (optional)
Use this keyword to specify the number of color ramp increments. RAMP_INC is an integer value specifying number of increments. The default value is 3.
RAMP_LENGTH (optional)
Use this keyword to specify the color ramp length in pixels. RAMP_LENGTH is an integer value specifying the color ramp length in pixels. The default value is 200.
RAMP_MAX_VAL (optional)
Use this keyword to specify the value associated with the high end of the color ramp. RAMP_MAX_VAL is a floating-point value.
RAMP_MIN_VAL (optional)
Use this keyword to specify the value associated with the low end of the color ramp. RAMP_MIN_VAL is a floating-point value.
RAMP_ORIEN (optional)
Use this keyword to specify the color ramp orientation. RAMP_ORIEN is one of the following integer values:
- 0: Horizontal (low to high)
- 1: Vertical (high to low)
- 2: Horizontal (high to low)
- 3: Vertical (low to high)
RAMP_PRECISION (optional)
Use this keyword to specify the number of precision digits for color ramp values. RAMP_PRECISION is an integer. The default value is 1.
RAMP_WIDTH (optional)
Use this keyword to specify the color ramp width in pixels. RAMP_WIDTH is an integer. The default value is 25.
Keywords for MAP_KEY
KEY_FILL_MODE (optional)
Use this keyword to specify the IDL fill mode for map key polygons. KEY_FILL_MODE is an integer value indicating the IDL fill mode. The default value is 0 (no fill).
KEY_FILL_ORIEN (optional)
Use this keyword to specify the orientation for fill. KEY_FILL_ORIEN is an integer value greater than l. The default value is 0 (no rotation).
KEY_FILL_SPACING (optional)
Use this keyword to specify the spacing for fill. KEY_FILL_SPACING is floating-point value indicating the fill spacing. KEY_FILL_SPACING is only valid when KEY_FILL_MODE is greater than 1. The default value is 0.1.
Keywords for SCALE_BARS
PIXEL_SIZE
Use this keyword to specify a floating-point number that represents both the x and y pixel size in meters. If the pixel size is not in meters, you need to convert it to meters. If the x and y pixel sizes are different, use the x pixel size (since scale bars are always horizontal).
SCALE_FLAG (optional)
Use this keyword to specify which units are active for a scale bar. SCALE_FLAG is a four-element byte array of zeros and ones, where a value of 1 makes the corresponding units active. The elements of SCALE_FLAG correspond to the units [km, miles, meters, feet]. The default is [1, 0, 0, 0], displaying only kilometer units.
SCALE_HEIGHT (optional)
Use this keyword to specify the height in pixels for the scale bars. SCALE_HEIGHT is an integer value specifying the scale bar height in pixels. The default value is 25.
SCALE_INC (optional)
Use this keyword to specify the number of increments for each type of scale bar. SCALE_INC is a four-element array of integers specifying the number of increments for each of the units [km, miles, meters, feet]. The default is [1, 1, 1, 1].
SCALE_LENGTH (optional)
Use this keyword to specify the length in map scale for each type of scale bar. SCALE_LENGTH is a four-element array of floating-point values specifying the length in map scale for each of the units [km, miles, meters, feet].
SCALE_SUB_INC (optional)
Use this keyword to specify the number of sub-increments for the first unit of a given scale bar. SCALE_SUB_INC is a four-element array of integers specifying the number of increments for each of the units [km, miles, meters, feet]. The default is [4, 4, 4, 4].
SCALE_TITLES (optional)
Use this keyword to specify the titles for each scale bar. SCALE_TITLE is a four-element string array specifying the titles for each of the units [km, miles, meters, feet]. Use a null string ('') for units that you do not use. The default is ['Kilometers', 'Miles', 'Meters', 'Feet'].
Example
PRO ANNOTATION_DEMO
compile_opt IDL2
in_file = DIALOG_PICKFILE()
ENVI_OPEN_FILE, in_file, R_FID = in_fid
ENVI_USER_DEFINED_ANNOTATION, 'example_annotation_file.ann', $
125, 50, STR_TEXT = 'Text!C!CTest Object', COLOR = 2, /TEXT, $
ALIGN = 0.5
The lower left corner will be at
image = BYTSCL(DIST(40))
ENVI_USER_DEFINED_ANNOTATION, 'example_annotation_file.ann', $
50, 140, image=image
END
API Version
4.2