IIMAGE

The IIMAGE procedure creates an iTool and associated user interface (UI) configured to display and manipulate image data.

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

Syntax

iTool Common Keywords: [, DIMENSIONS=[x, y]] [, IDENTIFIER=variable] [, LOCATION=[x, y]] [, NAME=string] [, OVERPLOT=iToolID] [, TITLE=string] [, VIEW_GRID=[columns, rows]] [, /VIEW_NEXT] [, VIEW_NUMBER=integer] [, {X | Y}RANGE=[min, max]]

iTool Image Keywords: [, ALPHA_CHANNEL=2-D array] [, BLUE_CHANNEL=2-D array] [, GREEN_CHANNEL=2-D array] [, IMAGE_DIMENSIONS=[width, height]] [, IMAGE_LOCATION=[x, y]] [, RED_CHANNEL=2-D array] [, RGB_TABLE=array of 256 by 3 or 3 by 256 elements]

Image Object Keywords: [, CHANNEL=hexadecimal bitmask] [, CLIP_PLANES=array] [, /HIDE] [, /INTERPOLATE] [, /ORDER]

Axis Object Keywords: [, {X | Y}GRIDSTYLE={0 | 1 | 2 | 3 | 4 | 5 | 6}] [, {X | Y}MAJOR=integer] [, {X | Y}MINOR=integer] [, {X | Y}SUBTICKLEN=ratio] [, {X | Y}TEXT_COLOR=RGB vector] [, {X | Y}TICKFONT_INDEX={0 | 1 | 2 | 3 | 4}] [, {X | Y}TICKFONT_SIZE=integer] [, {X | Y}TICKFONT_STYLE={0 | 1 | 2 | 3}] [, {X | Y}TICKFORMAT=string or string array] [, {X | Y}TICKINTERVAL=value] [, {X | Y}TICKLAYOUT={0 | 1 | 2}] [, {X | Y}TICKLEN=value] [, {X | Y}TICKNAME=string array] [, {X | Y}TICKUNITS=string] [, {X | Y}TICKVALUES=vector] [, {X | Y}TITLE=string]

Arguments

Image

Either a vector, a two-dimensional, or a three-dimensional array representing the sample values to be displayed as an image.

The X and Y arguments must also be present and contain the same number of elements. In this case, a dialog will be presented that offers the option of gridding the data to a regular grid (the results of which will be displayed as a color-indexed image).

If either dimension is 3:

Image represents an array of x, y, and z values (either [[x₀, y₀, z₀], [x₁, y₁, z₁], ..., [x_n, y_n, z_n]] or [[x₀, x₁, ..., x_n], [y₀, y₁, ..., y_n], [z₀, z₁, ..., z_n]] where n is the length of the other dimension). In this case, the X and Y arguments, if present, will be ignored. A dialog will be presented that allows the option of gridding the data to a regular grid (the results of which will be displayed as a color-indexed image, using the z values as the image data values).

If neither dimension is 3:

Image represents an array of sample values to be displayed as a color-indexed image. If X and Y are provided, the sample values are defined as a function of the corresponding (x, y) locations; otherwise, the sample values are implicitly treated as a function of the array indices of each element of Image.

If one of the dimensions is 3:

Image is a 3 x n x m, n x 3 x m, or n x m x 3 array representing the red, green, and blue channels of the image to be displayed.

If one of the dimensions is 4:

Image is a 4 x n x m, n x 4 x m, or n x m x 4 array representing the red, green, blue, and alpha channels of the image to be displayed.

Either a vector or a two-dimensional array representing the x-coordinates of the image grid.

X must be a vector with the same number of elements as Image.

If the Image argument is a two-dimensional array (for which neither dimension is 3):

If X is a vector:

Each element of X specifies the x-coordinates for a column of Image (e.g., X[0] specifies the x-coordinate for Image[0, *]).

If X is a two-dimensional array:

Each element of X specifies the x-coordinate of the corresponding point in Image (X_ij specifies the x-coordinate of Image_ij).

Either a vector or a two-dimensional array representing the y-coordinates of the image grid.

Y must be a vector with the same number of elements.

If Y is a vector:

Each element of Y specifies the y-coordinates for a column of Image (e.g., Y[0] specifies the y-coordinate for Image[*, 0]).

If Y is a two-dimensional array:

Each element of Y specifies the y-coordinate of the corresponding point in Image (Y_ij specifies the y-coordinate of Image_ij).

Keywords

ALPHA_CHANNEL

Set this keyword to a two-dimensional array representing the alpha channel pixel values for the image to be displayed. This keyword is ignored if the Image argument is present, and is intended to be used in conjunction with some combination of the RED_CHANNEL, GREEN_CHANNEL, and BLUE_CHANNEL keywords.

BLUE_CHANNEL

Set this keyword to a two-dimensional array representing the blue channel pixel values for the image to be displayed. This keyword is ignored if the Image argument is present, and is intended to be used in conjunction with some combination of the RED_CHANNEL, GREEN_CHANNEL, and ALPHA_CHANNEL keywords.

CHANNEL

Set this keyword to a hexadecimal bitmask that defines which color channel(s) to draw. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. For example, 'ff0000'X represents a Blue channel write. The default is to draw all channels, and is represented by the hexadecimal value 'ffffff'X.

CLIP_PLANES

Set this keyword to an array of dimensions [4, N] specifying the coefficients of the clipping planes to be applied to this object. The four coefficients for each clipping plane are of the form [A, B, C, D], where Ax + By + Cz + D = 0. Portions of this object that fall in the half space Ax + By + Cz + D > 0 will be clipped. By default, the value of this keyword is a scalar (-1) indicating that no clipping planes are to be applied.

DIMENSIONS

Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the drawing area of the specific tool in device units. The minimum width of the window correlates to the width of the menubar. The minimum window height is 100 pixels.

GREEN_CHANNEL

Set this keyword to a two-dimensional array representing the green channel pixel values for the image to be displayed. This keyword is ignored if the Image argument is present, and is intended to be used in conjunction with some combination of the RED_CHANNEL, BLUE_CHANNEL, and ALPHA_CHANNEL keywords.

HIDE

Set this keyword to a boolean value indicating whether this object should be drawn:

0 = Draw graphic (the default)

1 = Do not draw graphic

IDENTIFIER

Set this keyword to a named IDL variable that will contain the iToolID for the created tool. This value can then be used to reference this tool during overplotting operations or command-line-based tool management operations.

IMAGE_DIMENSIONS

Set this keyword to a 2-element vector, [width, height], to specify the image dimensions (in data units). By default, the dimensions match the pixel width of the image.

IMAGE_LOCATION

Set this keyword to a 2-element vector, [x, y], to specify the image location (in data units). By default, the location is [0, 0].

INTERPOLATE

Set this keyword to one (1) to display the iImage tool using bilinear interpolation. The default is to use nearest neighbor interpolation.

LOCATION

Set this keyword to a two-element vector of the form [x, y] to specify the location of the upper left-hand corner of the tool relative to the display screen, in device units.

NAME

Set this keyword to a string to specify the name for this particular tool. The name is used for tool-related display purposes only-as the root of the hierarchy shown in the Tool Browser, for example.

ORDER

Set this keyword to force the rows of the image data to be drawn from top to bottom. By default, image data is drawn from the bottom row up to the top row.

OVERPLOT

Set this keyword to an iToolID to direct the graphical output of the particular tool to the tool specified by the provided iToolID.

Set this keyword to 1 (one) to place the graphical output for the command in the current tool. If no current tool exists, a new tool is created.

RED_CHANNEL

Set this keyword to a two-dimensional array representing the red channel pixel values for the image to be displayed. This keyword is ignored if the Image argument is present, and is intended to be used in conjunction with some combination of the GREEN_CHANNEL, BLUE_CHANNEL, and ALPHA_CHANNEL keywords.

RGB_TABLE

Set this keyword to a 3 by 256 or 256 by 3 byte array of RGB color values. If no color tables are supplied, the tool will provide a default 256-entry linear grayscale ramp.

TITLE

Set this keyword to a string to specify a title for the tool. The title is displayed in the title bar of the tool.

VIEW_GRID

Set this keyword to a two-element vector of the form [columns, rows] to specify the view layout within the new tool. This keyword is only used if a new tool is being created (for example, if OVERPLOT, VIEW_NEXT, or VIEW_NUMBER are specified then VIEW_GRID is ignored).

VIEW_NEXT

Set this keyword to change the view selection to the next view following the currently-selected view before issuing any graphical commands. If the currently-selected view is the last one in the layout, then /VIEW_NEXT will cause the first view in the layout to become selected. This keyword is ignored if no current tool exists.

VIEW_NUMBER

Set this keyword to change the currently-selected view to the view specified by the VIEW_NUMBER before issuing any graphical commands. The view number starts at 1, and corresponds to the position of the view within the graphics container (not necessarily the position on the screen). This keyword is ignored if no current tool exists.

[XY]MAJOR

Set this keyword to an integer representing the number of major tick marks. The default is -1, specifying that IDL will compute the number of tickmarks. Setting MAJOR equal to zero suppresses major tickmarks entirely.

[XY]MINOR

Set this keyword to an integer representing the number of minor tick marks. The default is -1, specifying that IDL will compute the number of tickmarks. Setting MINOR equal to zero suppresses minor tickmarks entirely.

[XY]RANGE

Set this keyword to the desired data range of the axis, a 2-element vector. The first element is the axis minimum, and the second is the maximum.

[XY]SUBTICKLEN

Set this keyword to a floating-point scale ratio specifying the length of minor tick marks relative to the length of major tick marks. The default is 0.5, specifying that the minor tick mark is one-half the length of the major tick mark.

[XY]TEXT_COLOR

Set this keyword to an RGB value specifying the color for the axis text. The default value is [0, 0, 0] (black).

[XY]TICKFONT_INDEX

Set this keyword equal to one of the following integers, which represent the type of font to be used for the axis text:

0 = Helvetica

1 = Courier

2 = Times

3 = Symbol

4 = Hershey

[XY]TICKFONT_SIZE

Set this keyword to an integer representing the point size of the font used for the axis text. The default is 12.0 points.

[XY]TICKFONT_STYLE

Set this keyword equal to one of the following integers, which represent the style of font to be used for the axis text:

0 = Normal

1 = Bold

2 = Italic

3 = Bold Italic

[XY]TICKFORMAT

Set this keyword to a string, or an array of strings, in which each string represents a format string or the name of a function to be used to format the tick mark labels. If an array is provided, each string corresponds to a level of the axis. The TICKUNITS keyword determines the number of levels for an axis.

If the string begins with an open parenthesis, it is treated as a standard format string. See Format Codes.

If the string does not begin with an open parenthesis, it is interpreted as the name of a callback function to be used to generate tick mark labels.

If TICKUNITS are not specified:

The callback function is called with three parameters: Axis, Index, and Value, where:

Axis is the axis number: 0 for X axis, 1 for Y axis, 2 for Z axis

Index is the tick mark index (indices start at 0)

Value is the data value at the tick mark (a double-precision floating point value)

If TICKUNITS are specified:

The callback function is called with four parameters: Axis, Index, Value, and Level, where:

Axis, Index, and Value are the same as described above.

Level is the index of the axis level for the current tick value to be labeled. (Level indices start at 0.)

Used with the LABEL_DATE function, this property can easily create axes with date/time labels.

[XY]TICKINTERVAL

Set this keyword to a floating-point scalar indicating the interval between major tick marks for the first axis level. The default value is computed according to the axis [XYZ]RANGE and the number of major tick marks ([XYZ]MAJOR). The value of this keyword takes precedence over the value set for the [XYZ]MAJOR keyword.

For example, if TICKUNITS = ['S', 'H', 'D'], and TICKINTERVAL = 30, then the interval between major ticks for the first axis level will be 30 seconds.

[XY]TICKLAYOUT

Set this keyword to integer scalar that indicates the tick layout style to be used to draw each level of the axis.

0 = The axis line, major tick marks and tick labels are all included. Minor tick marks only appear on the first level of the axis. This is the default tick layout style.

1 = Only the labels for the major tick marks are drawn. The axis line, major tick marks, and minor tick marks are omitted.

2 = Each major tick interval is outlined by a box. The tick labels are positioned within that box (left-aligned). For the first axis level only, the major and minor tick marks will also be drawn.

[XY]TICKLEN

Set this keyword to a floating-point value that specifies the length of each major tick mark, measured in data units. The recommended, and default, tick mark length is 0.2. IDL converts, maintains, and returns this data as double-precision floating-point.

[XY]TICKNAME

Set this keyword to a string array of up to 30 elements that controls the annotation of each tick mark.

[XY]TICKUNITS

Set this keyword to a string (or a vector of strings) indicating the units to be used for axis tick labeling. If more than one unit is provided, the axis will be drawn in multiple levels, one level per unit.

The order in which the strings appear in the vector determines the order in which the corresponding unit levels will be drawn. The first string corresponds to the first level (the level nearest to the primary axis line).

"Numeric"

"Years"

"Months"

"Days"

"Hours"

"Minutes"

"Seconds"

"Time" - Use this value to indicate that the tick values are time values; IDL will determine the appropriate time intervals and tick label formats based upon the range of values covered by the axis.

""- Use the empty string to indicate that no tick units are being explicitly set. This implies that a single axis level will be drawn using the "Numeric" unit. This is the default setting.

If any of the time units are utilized, then the tick values are interpreted as Julian date/time values. Note that the singular form of each of the time value strings is also acceptable (e.g, TICKUNITS = 'Day' is equivalent to TICKUNITS = 'Days').

[XY]TICKVALUES

Set this keyword to a floating-point vector of data values representing the values at each tick mark. If TICKVALUES is set to 0, the default, IDL computes the tick values based on the axis range and the number of major ticks. IDL converts, maintains, and returns this data as double-precision floating-point.

[XY]TITLE

Examples

In the IDL Intelligent Tools system, data can be imported from the IDL Command Line (as described in Example 1), or data can be imported via the File menu in the iTool window (as described in Examples 2 and 3). For detailed information on importing data via the iTool file menu, refer to Data Import Methods.

Example 1

This example shows how use the IDL Command Line to load data into the iImage tool.

file = FILEPATH('mineral.png', $ 
   SUBDIRECTORY = ['examples', 'data']) 
data = READ_PNG(file) 
IIMAGE, data, TITLE = 'Electron Image of Mineral Deposits'

Double-click the image to display image properties, and use the Image Palette setting to load the Stern Special predefined color table through the Load Predefined button in the Palette Editor.

Use the Text Annotation tool to insert a title at the top of the image. Select Insert ® Colorbars to insert a color bar at the bottom of the image. Double-click on the colorbar to display its properties, and change the Title setting to Stern Special.

Example 2

This example shows how to use the iTool File ® Open command to load binary data into the iImage tool.

Select File ® Open to display the Open dialog, then browse to find worldelv.dat in the examples/data directory in the IDL distribution, and click Open.

In the Binary Template dialog, click New Field, and enter the following information in the New Field dialog:

Field Name: data (or a name of your choosing)

Type: Byte (unsigned 8-bits)

Number of Dimensions: 2

1st Dimension Size: 360

2nd Dimension Size: 360

Click OK to close the New Field dialog and the Binary Template dialog, and the image is displayed.

Double-click the image to display image properties, and use the Image Palette setting to load the STD GAMMA-II predefined color table through the Load Predefined button in the Palette Editor.

Example 3

This example shows how to use the IDL Import Data Wizard to load image data into the iImage tool.

At Step 1, select From a File and click Next>>.

At Step 2, under File Name:, browse to find n_vasinfecta.jpg in the examples/data directory in the IDL distribution, and click Next>>.

At Step 3, select Image and click Finish.

Define the edges within the image by selecting Operations ® Filter ® Sobel Filter.