ISURFACE

The ISURFACE procedure creates an iTool and the associated user interface (UI) configured to display and manipulate surface data.

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

Syntax

Arguments

If Y and Z are vectors and have the same length as X:

Each element of X specifies the x-coordinates of a point in space (e.g., X[0] specifies the x-coordinate for Y[0] and Z[0]). The gridding wizard will automatically launch in this case.

If Z is a two-dimensional array:

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

If X is a two-dimensional array, each element of X specifies the x-coordinate of the corresponding point in Z (X_ij specifies the x-coordinate of Z_ij).

If X and Z are vectors and have the same length as Y:

Each element of Y specifies the y-coordinates of a point in space (e.g., Y[0] specifies the y-coordinate for X[0] and Z[0]). The gridding wizard will automatically launch in this case.

If Z is a two-dimensional array:

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

If Y is a two-dimensional array, each element of Y specifies the y-coordinate of the corresponding point in Z (Y_ij specifies the y-coordinate of Z_ij).

If X and Y are vectors and have the same length as Z:

Each element of Z specifies the z-coordinates of a point in space (e.g., Z[0] specifies the z-coordinate for X[0] and Y[0]). The gridding wizard will automatically launch in this case.

If X and Y are provided:

The surface is defined as a function of the (x, y) locations specified by their contents.

If X and Y are not provided:

The surface is generated as a function of the array indices of each element of Z.

Keywords

BACKGROUND_COLOR

Set this keyword to an RGB value specifying the color to be used as the background color for the view. The default is [255, 255, 255] (white). The BACKGROUND_COLOR keyword can be used when a tool is being created or when a new visualization is being created in an existing tool with the use of the OVERPLOT, VIEW_NUMBER or VIEW_NEXT keywords. The background color is applied to the current view. For example, if multiple views have been created with the VIEW_GRID keyword, and the VIEW_NUMBER keyword is used to create a visualization in the second view, use of the BACKGROUND_COLOR keyword would set the background color in the second view only.

BOTTOM

Set this keyword to an RGB color for drawing the bottom of the surface. Set this keyword to a scalar to draw the bottom with the same color as the top.

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.

COLOR

Set this keyword to the color to be used as the foreground color for this model. The color is specified as an RGB vector. The default is [225, 184, 0].

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.

DEPTH_OFFSET

Set this keyword to an integer value that specifies an offset in depth to be used when rendering filled primitives. This offset is applied along the viewing axis, with positive values moving the primitive away from the viewer.

The units are "Z-Buffer units," where a value of 1 is used to specify a distance that corresponds to a single step in the device's Z-Buffer.

Use DEPTH_OFFSET to always cause a filled primitive to be rendered slightly deeper than other primitives, independent of model transforms. This is useful for avoiding stitching artifacts caused by rendering lines or polygons on top of other polygons at the same depth.

EXTENDED_LEGO

Set this keyword to force the iSurface tool to display the last row and column of data when lego display styles are selected.

HIDDEN_LINES

Set this keyword to draw point and wireframe surfaces using hidden line (point) removal. By default, hidden line removal is disabled.

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.

LINESTYLE

Set this keyword to indicate the line style that should be used to draw the surface lines. The value can be either an integer value specifying a pre-defined line style, or a two-element vector specifying a stippling pattern.

To use a pre-defined line style, set the LINESTYLE keyword equal to one of the following integer values:

0 = Solid line (the default)

1 = dotted

2 = dashed

3 = dash dot

4 = dash dot dot dot

5 = long dash

6 = no line drawn

To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1's or 0's in the bitmask should be repeated. (That is, if three consecutive 0's appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 £ repeat £ 255.

The bitmask indicates which pixels are drawn and which are not along the length of the line. Bitmask is most conveniently specified as a 16-bit hexadecimal value.

For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off).

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.

MACRO_NAMES

Set this keyword to a scalar string or an array of strings that specifies the names of one or more macros to run. The macro names are retrieved and the macros are run sequentially after the iTool and (if applicable) any visualizations have been created. If a macro of the specified name does not exist, IDL generates an error and the routine exits.

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.

NO_SAVEPROMPT

Set this keyword to cause the iTool not to prompt the user to save changes when closing the tool. The default is to prompt the user to save changes.

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 equal to one to place the graphical output for the command in the current tool. If no current tool exists, a new tool is created.

RGB_TABLE

Set this keyword to a two-dimensional array containing RGB triplets defining the colors to be used in a color indexed texture image or by vertex colors. The values should be within the range of 0 £ value £ 255. The array must be a 3 by N array where m must not exceed 256.

SHADING

Set this keyword to an integer representing the type of shading to use if STYLE is set to 2 (Filled).

0 = Flat (default): The color has a constant intensity for each face of the surface, based on the normal vector.

1 = Gouraud: The colors are interpolated between vertices, and then along scanlines from each of the edge intensities.

Gouraud shading may be slower than flat shading, but results in a smoother appearance.

SHOW_SKIRT

Set this keyword to enable skirt drawing. The default is to disable skirt drawing.

SKIRT

Set this keyword to the Z value at which a skirt is to be defined around the array. The Z value is expressed in data units; the default is 0.0. If a skirt is defined, each point on the four edges of the surface is connected to a point on the skirt which has the given Z value, and the same X and Y values as the edge point. In addition, each point on the skirt is connected to its neighbor. The skirt value is ignored if skirt drawing is disabled (see SHOW_SKIRT above). IDL converts, maintains, and returns this data as double-precision floating-point.

STYLE

Set this keyword to an integer value that indicates the style to be used to draw the surface. Valid values are:

0 = Points

1 = Wire mesh

2 = Filled (the default)

3 = RuledXZ

4 = RuledYZ

5 = Lego

6 = LegoFilled: for outline or shaded and stacked histogram-style plots.

STYLE_NAME

Set this keyword equal to a string that specifies the name of a user-defined or a system style. If a style of the specified name does not exist, IDL generates an error and the routine exits. The style is applied using the following rules:

If the tool exists and /OVERPLOT is specified, then the style is only applied to the newly-created visualizations within the current view. The current tool style is not updated with the new style, nor is the style applied to any other items within the view.

Otherwise, if the tool exists and either VIEW_NEXT or VIEW_NUMBER is being used to select a different view, then the style is applied to all items within that view. The current tool style is updated with the new style.

Otherwise, if a new tool is being created, then the style is applied to all items within all views. The current tool style is updated with the new style.

TEXTURE_ALPHA

Set the keyword to a two-dimensional array containing the alpha channel of an image to be used as a texture image. Use of this keyword requires that TEXTURE_RED, TEXTURE_GREEN, and TEXTURE_BLUE be set to arrays of identical size and type.

TEXTURE_BLUE

Set the keyword to a two-dimensional array containing the blue channel of an image to be used as a texture image. Use of this keyword requires that TEXTURE_RED and TEXTURE_GREEN be set to arrays of identical size and type.

TEXTURE_GREEN

Set the keyword to a two-dimensional array containing the green channel of an image to be used as a texture image. Use of this keyword requires that TEXTURE_RED and TEXTURE_BLUE be set to arrays of identical size and type.

TEXTURE_HIGHRES

An integer value that determines the type of texture tiling, if any, that will be used to maintain the full pixel resolution of the original texture image. Set this property to one of the following options:

0 = If the texture map is larger than the maximum resolution supported by the 3-D hardware, the texture is scaled down to this resolution.

1 = If the texture map is larger than the maximum resolution supported by the hardware, texture tiling is used to ensure no loss of data. As a large image could easily consume all available video memory, this mode employs texture Level of Detail (LoD). Rather than loading the entire image into the texture tiles at the full resolution, the image tiles are downsampled based on the level of zoom. If the entire image is visible the texture tiles will contain highly downsampled data from the image to conserve video memory. As a portion of the image is zoomed in on, progressively higher resolution image data is loaded into the visible tiles, until the maximum resolution is reached. The tiles that are not visible during zooming are not loaded with high resolution data.

Note

2 = If the texture map is larger than the maximum resolution supported by the hardware, texture tiling is used to ensure no loss of data. However, the highest resolution data is loaded into all tiles. LoD tiling is disabled. This mode should only be used if the video memory is sufficient for the image size.

If not set, and the texture map is larger than the maximum resolution supported by the 3-D hardware, the texture is scaled down to the maximum resolution supported by the 3-D hardware on your system. The default value is 0.

TEXTURE_IMAGE

Set this keyword to an array containing an image to be texture mapped onto the surface. If this keyword is omitted or set to a null object reference, no texture map is applied and the surface is filled with the color specified by the COLOR or VERTEX_COLORS property. The image array can be a two-dimensional array of color indexes or a three-dimensional array specifying RGB values at each pixel (3 x n x m, n x 3 x m, or n x m x 3). Setting TEXTURE_IMAGE to a three-dimensional array contains an alpha channel (4 x n x m, n x 4 x m, or n x m x 4) allows you to create a transparent iSurface object. The TEXTURE_IMAGE keyword will override any values passed to TEXTURE_RED, TEXTURE_GREEN, TEXTURE_BLUE, or TEXTURE_ALPHA.

TEXTURE_INTERP

Set this keyword to a nonzero value to indicate that bilinear sampling is to be used with texture mapping. The default method is nearest-neighbor sampling.

TEXTURE_RED

Set the keyword to a two-dimensional array containing the red channel of an image to be used as a texture image. Use of this keyword requires that TEXTURE_GREEN and TEXTURE_BLUE be set to arrays of identical size and type.

THICK

Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to use to draw surface lines, in points. The default is 1.0 points.

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.

USE_TRIANGLES

Set this keyword to force the iSurface tool to use triangles instead of quads to draw the surface and skirt.

VERT_COLORS

Set this keyword to a vector, two-dimensional array of equal size to Z, or a two-dimensional array containing RGB triplets representing colors to be used at each vertex. If this keyword is set to a vector or a two-dimensional array of equal size to Z, these values are indices into a color table that can be specified by the RGB_TABLE keyword. If the RGB_TABLE keyword is not set, a grayscale color is used. If more vertices exist than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated. If this keyword is omitted, the surface is drawn in the color specified by the COLOR keyword or the default color.

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.

[XYZ]GRIDSTYLE

The index of the linestyle to be used for plot tickmarks and grids (i.e., when [XYZ]TICKLEN is set to 1.0). See LINESTYLE for a list of linestyles.

[XYZ]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.

[XYZ]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.

[XYZ]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.

[XYZ]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.

[XYZ]TEXT_COLOR

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

[XYZ]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

[XYZ]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.

[XYZ]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

[XYZ]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. This function is defined with either three or four parameters, depending on whether TICKUNITS is specified.

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.

[XYZ]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.

[XYZ]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.

[XYZ]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.

[XYZ]TICKNAME

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

[XYZ]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').

[XYZ]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.

[XYZ]TITLE

ZERO_OPACITY_SKIP

Set this keyword to gain finer control over the rendering of textured surface pixels (texels) with an opacity of 0 in the texture map. Texels with zero opacity do not affect the color of a screen pixel since they have no opacity. If this keyword is set to 1, any texels are "skipped" and not rendered at all. If this keyword is set to zero, the Z-buffer is updated for these pixels and the display image is not affected as noted above. By updating the Z-buffer without updating the display image, the surface can be used as a clipping surface for other graphics primitives drawn after the current graphics object. The default value for this keyword is 1.

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 to use the IDL Command Line to load data into the iSurface tool.

file = FILEPATH('surface.dat', $ 
   SUBDIRECTORY = ['examples', 'data']) 
data = READ_BINARY(file, DATA_DIMS = [350, 450], DATA_TYPE = 2, $ 
   ENDIAN = 'little') 
ISURFACE, data, TITLE = 'Maroon Bells Elevation', $ 
   COLOR = [255, 128, 0]

Place a title on the elevation axis of your plot by selecting the axis, right-clicking to display the context menu, selecting Properties to display the property sheet, and typing Elevation (m) in the Title field.

Use the Operations ® Statistics... option to display the iTools Statistics dialog. Within this dialog, observe the Z value's Maximum, which is 4241 at [29, 253]. Close the iTools Statistics dialog by selecting File ® Close.

Annotate your plot by selecting the Text Annotation tool, clicking near the top of the highest peak in the display, and typing Highest Point (4241 m). Draw a line annotation between the text annotation and the highest peak on the surface.

Example 2

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

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

The Binary Template wizard is displayed. In the Binary Template, change File's byte ordering to Little Endian. Then, click New Field, and enter the following information in the New Field dialog:

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

Type: Float (32 bit)

Number of Dimensions: 2

1st Dimension Size: 200

2nd Dimension Size: 200

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

Insert a contour onto the surface by clicking the Surface Contour button on the toolbar, then clicking and dragging on the surface to position the contour at the desired height.

Example 3

This example shows how to use the File ® Import command to load ASCII data into the iSurface tool.

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

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

At Step 3, select Surface and click Finish.

At Step 1, click Next>> to accept the displayed Data Type/Range definitions.

At Step 2, click Next>> to accept the displayed Delimiter/Fields definitions.

At Step 3, click Finish to accept the displayed Field Specifications.

At the iTool's Create Visualization window, you have the option of launching the Gridding wizard or not creating a visualization. Choose Launch the gridding wizard and click Ok.

At Step 1, click Next>> to accept the interpolation of data values and locations.

At Step 2, click Next>> to accept the dimensions, start and spacing.

At Step 3, select Inverse Distance as the gridding method, click Preview to preview the possible results, and click Finish to display the surface.

Double-click the surface to display the Properties sheet, and change the Fill shading setting from Flat to Gouraud.

Use the Rotate tool on the Toolbar to rotate the surface slightly forward to better display the surface convolutions.