IVECTOR

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

Note
If no arguments are specified, the IVECTOR procedure creates an empty Vector tool.

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

For more information on using the iVector tool, see Working with Vectors (iTool User's Guide).

Syntax

IVECTOR [, U, V [, X, Y]]

iTool Common Keywords: [, ANISOTROPIC_SCALE_2D=value] [, ANISOTROPIC_SCALE_3D=value] [, BACKGROUND_COLOR=value] [, CURRENT_ZOOM=value] [, DEPTHCUE_BRIGHT=value] [, DEPTHCUE_DIM=value] [, DIMENSIONS=[x, y]] [, /DISABLE_SPLASH_SCREEN] [, /FIT_TO_VIEW] [, FONT_COLOR=RGB triple] [, FONT_NAME=string] [, FONT_SIZE=value] [, FONT_STYLE={0|1|2|3}] [, IDENTIFIER=variable] [, LOCATION=[x, y]] [, MACRO_NAMES=string or string array] [, NAME=string] [, /NO_SAVEPROMPT] [, OVERPLOT=iToolID] [, RENDERER={0 | 1}] [, SCALE_ISOTROPIC=value] [, /STRETCH_TO_FIT] [, STYLE_NAME=string] [, TITLE=string] [, VIEW_GRID=[columns, rows]] [, /VIEW_NEXT] [, VIEW_NUMBER=integer] [, VIEW_TITLE=string] [, VIEW_ZOOM=value] [, WINDOW_TITLE=string] [, XMARGIN=value] [, YMARGIN=value] [, /ZOOM_ON_RESIZE]

Vector Keywords: [, ARROW_STYLE={0 | 1}] [, ARROW_THICK=float {1.0 to 10.0}] [, AUTO_COLOR={0 | 1 | 2 }] [, /AUTO_SUBSAMPLE] [, COLOR=RGB vector] [, DATA_LOCATION={0 | 1 | 2 }] [, DIRECTION_CONVENTION={0 | 1 | 2 }] [, GRID_UNITS={0 | 1 | 2 }] [, HEAD_ANGLE=float] [, HEAD_INDENT=float] [, /HEAD_PROPORTIONAL] [, HEAD_SIZE=float] [, /HIDE] [, INSERT_COLORBAR=value] [, LENGTH_SCALE=float] [, MAX_VALUE=float] [, MIN_VALUE=float] [, RGB_TABLE=array] [, /STREAMLINES] [, STREAMLINE_NSTEPS=integer] [, STREAMLINE_STEPSIZE=float] [, SUBSAMPLE_METHOD={0 | 1}] [, SYM_COLOR=value] [, SYM_INDEX=value] [, SYM_SIZE=value] [, THICK=float {1.0 to 10.0}] [, TRANSPARENCY=value] [, USE_DEFAULT_COLOR=value] [, VECTOR_COLORS=vector or array] [, VECTOR_STYLE={0 | 1}] [, X_STREAMPARTICLES=integer] [, X_SUBSAMPLE=integer] [, [XYZ]LOG=value] [, Y_STREAMPARTICLES=integer] [, Y_SUBSAMPLE=integer] [, ZVALUE=float]

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

Arguments

U

A one or two-dimensional array containing the horizontal components of the vectors. If the X and Y arguments are provided, the vectors are plotted as a function of the (x, y) locations specified by their contents. Otherwise, the vectors are plotted as a function of the two-dimensional array index of each element of U.

V

A one or two-dimensional array containing the vertical components of the vectors. V must have the same dimensions as U.

X

A one-dimensional array specifying the x-coordinates for the vectors. If U is a two-dimensional array then X must have the same number of elements as the first dimension of U, where each element of X specifies the x-coordinate for a column of U (e.g., X[0] specifies the x-coordinate for U[0, *]). If U is a one-dimensional array then X must have the same number of elements as U, where each element of X specifies the y-coordinate for the corresponding element of U.

Y

A one-dimensional array specifying the y-coordinates for the vectors. If U is a two-dimensional array then Y must have the same number of elements as the second dimension of U, where each element of Y specifies the y-coordinate for a row of U (e.g., Y[0] specifies the y-coordinate for U[*, 0]). If U is a one-dimensional array then Y must have the same number of elements as U, where each element of Y specifies the y-coordinate for the corresponding element of U.

Keywords

ANISOTROPIC_SCALE_2D

For two-dimensional anisotropic visualizations, set this keyword to a floating point value indicating the ratio of the Y dimension to the X dimension. The default is 0.7. If the dataspace and its contained visualizations are isotropic then this keyword is ignored.

ANISOTROPIC_SCALE_3D

For three-dimensional anisotropic visualizations, set this keyword to a floating point value indicating the ratio of the Z dimension to the X and Y dimensions. The default is 0.7. If the dataspace and its contained visualizations are isotropic then this keyword is ignored.

ARROW_STYLE

Set this keyword to specify the style of the arrows. Possible values are:


0	Lines	Arrows are drawn as an outline
1	Filled	Arrows are drawn as filled

If VECTOR_STYLE is not 0 (Arrows) then this keyword is ignored.

ARROW_THICK

Set this keyword to a value between 1.0 and 10.0, specifying the thickness of the arrow shaft. The default is 1.0 points.

AUTO_COLOR

Set this keyword to enable or disable automatic coloring of vectors or streamlines. Possible values are:


0	No automatic colors, or use the vertex colors if VECTOR_COLORS is provided (the default)
1	Color according to magnitude, using the current color palette
2	Color according to direction, using the current color palette

If AUTO_COLOR is set to 1 or 2 then the VECTOR_COLORS keyword (and the vector colors parameter) will be ignored.

AUTO_SUBSAMPLE

Set this keyword to enable or disable automatic subsampling of vectors. If automatic subsampling is enabled, then the X and Y subsampling factors will change depending upon the current view zoom. The default is disabled.

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.

COLOR

Set this keyword to the color to be used to draw the vectors. This color is specified as an RGB vector. The default is [0, 0, 0]. This value will be ignored if AUTO_COLOR is set or if VECTOR_COLORS is provided.

CURRENT_ZOOM

Set this keyword to the zoom factor to be used for the current view. The default value is 1.0, which represents 100%.

DATA_LOCATION

Set this keyword to specify the position of the vectors at each data location. Possible values are:


0	Tail	Vectors are positioned so that the vector tail lies on each data location
1	Center	Vectors are positioned so that the vector center lies on each data location (the default)
2	Head	Vectors are positioned so that the vector head lies on each data location

This keyword is ignored if streamlines are being displayed.

DEPTHCUE_BRIGHT

Set this keyword to a floating-point value giving the distance in the Z plane at which the objects in the view begin to fade into the background color. The values range from -1 (closest to the viewer) to +1 (farthest from the viewer). The default value is 0. See DEPTHCUE_DIM for examples.

DEPTHCUE_DIM

Set this keyword to a floating-point value giving the distance in the Z plane at which the objects in the view have completely faded into the background color. The values range from -1 (closest to the viewer) to +1 (farthest from the viewer). The default value is 0. Some usage examples are:

Zbright = Zdim

Depth cue is disabled and no fading will occur.

Zbright < Zdim

Objects farther than Zbright will begin to fade into the background, and objects farther than Zdim will be completed faded. This is useful for simulating fog.

Zbright > Zdim

Objects closer than Zbright will begin to fade into the background, and objects closer than Zdim will be completely faded. This is useful for simulating lighting at a distance.

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 menu bar. The minimum window height is 100 pixels.

DIRECTION_CONVENTION

Set this keyword to indicate the convention to be used when displaying vector directions. Possible values are:


0	Polar	This describes the direction counterclockwise from X axis, and is the usual physics convention (the default)
1	Meteorological	This describes the direction from which the wind is blowing, and uses terms such as northerly, westerly, and so on
2	Wind azimuths	This describes the direction towards which the wind is blowing, and uses terms such as southward, eastward, and so on

Figure 11-16: Vector Direction Display Conventions

DISABLE_SPLASH_SCREEN

Set this keyword to disable the iTools splash screen. By default, the first time an iTool is run, the splash screen is displayed.

FIT_TO_VIEW

Set this keyword to automatically scale the newly-created visualization so that it fills the current view. This keyword is ignored if VIEW_ZOOM is present.

FONT_COLOR

Set this keyword equal to an RGB vector specifying the title text color. The default is [0, 0, 0] (black).

This keyword applies only to the text annotation created by the TITLE keyword. It is ignored if TITLE is not specified.

FONT_NAME

Set this keyword equal to a string specifying the name of the IDL or system font to use for the title text. The default is "Helvetica".

This keyword applies only to the text annotation created by the TITLE keyword. It is ignored if TITLE is not specified.

FONT_SIZE

Set this keyword equal to an integer specifying the font size for the title text. The default is 16 pt.

This keyword applies only to the text annotation created by the TITLE keyword. It is ignored if TITLE is not specified.

FONT_STYLE

Set this keyword equal to an integer specifying the font style to be used for the title text. Allowed values are:


0	Normal (the default)
1	Bold
2	Italic
3	Bold Italic

This keyword applies only to the text annotation created by the TITLE keyword. It is ignored if TITLE is not specified.

GRID_UNITS

Set this keyword to an integer specifying the units for the vector grid. This keyword applies only when there is a map projection inserted. It has the following values:


0	None	The vector grid is in arbitrary units that are not tied to a map projection (the default)
1	Meters	The vector grid is in meters, and is tied to a particular map projection. You are responsible for choosing the dataspace map projection that matches the vector map projection
2	Degrees	The vector grid is in degrees longitude/latitude, and the vectors will be automatically warped to the current map projection

If GRID_UNITS is not set, but a map projection is present, then IDL will attempt to use the range of the X and Y parameters to determine whether GRID_UNITS is in meters or degrees.

HEAD_ANGLE

Set this keyword to a floating-point value between 0 and 90 giving the angle in degrees of the arrowhead to the shaft. The default is 30.

HEAD_INDENT

Set this keyword to a floating-point value between -1 and +1 giving the indentation of the back of the arrowhead along the shaft. A value of 0 gives a triangular shape, a value of +1 will create an arrowhead that is just two lines, while a value of -1 will create a diamond shape. The default is 0.4.

Figure 11-17: Anatomy of a Vector Arrow

HEAD_PROPORTIONAL

Set this keyword to make the size of arrowheads proportional to their magnitude. The default is to make all arrowheads the same size. This keyword is ignored for wind barbs or for streamlines.

HEAD_SIZE

Set this keyword to a floating-point value giving a scale factor to be used when drawing the arrow heads or feathers. The default is 1.0.

HIDE

Set this keyword to a boolean value to indicate 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.

INSERT_COLORBAR

If the newly-created visualization contains a color table (as specified by the RGB_TABLE keyword) set this keyword to automatically insert a colorbar. By default the colorbar will be positioned in the bottom center of the view. To manually position the colorbar, set this keyword equal to a two-element vector with values in the range (0 to 1) specifying the location of the bottom left corner of the colorbar in normalized coordinates.

LENGTH_SCALE

Set this keyword to a floating-point value giving a scale factor for the length of arrows or barbs. The default is 1.0. This keyword is ignored if streamlines are being displayed.

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.

Note
Some X Window managers explicitly ignore any request from the client for window placement. See Positioning Top-Level Bases for additional information.

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.

MAX_VALUE

Set this keyword to the maximum magnitude value to be plotted. Vectors which have a magnitude greater than this value are treated as missing data. The default is to display all vectors. This keyword is ignored for streamlines.

MIN_VALUE

Set this keyword to the minimum magnitude value to be plotted. Vectors which have a magnitude smaller than this value are treated as missing data. The default is to display all vectors. This keyword is ignored for streamlines.

NAME

Set this keyword to a string to specify the name for this visualization. The name is used for tool-related display purposes only.

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.

RENDERER

Set this keyword to override the value specified by the IDL_GR_WIN_RENDERER (Windows) or IDL_GR_X_RENDERER (UNIX) preference for the iTool. IDL will use the specified graphics renderer when drawing objects within the iTool window. Valid values are:


Value	Description
0	Use platform native OpenGL
1	Use IDL's software implementation

If your platform does not have a native OpenGL implementation, IDL uses its own software implementation regardless of the value of this property. See Hardware vs. Software Rendering (Object Programming) for details.

RGB_TABLE

Set this keyword to the number of the predefined IDL color table, or to either a 3 by 256 or 256 by 3 byte array containing color values to use for the color palette. This color palette is used when either the AUTO_COLOR property is set or if VECTOR_COLORS is set to an array of color indices. The default is to use a grayscale ramp.

SCALE_ISOTROPIC

Set this keyword to indicate the scaling method to be used for the dataspace. Possible

values are:


0	Automatic scaling. If any visualization within the dataspace has its Isotropic scaling property set to True, the dataspace will be automatically set to isotropic. If none of the visualizations are isotropic, the dataspace will be automatically set to anisotropic. This is the default.
1	Isotropic scaling. The dataspace will be proportionally scaled in the X, Y, and Z directions according to the data ranges in each direction.
2	Anistropic scaling. The dataspace will be scaled in the X, Y, and Z directions according to the ANISOTROPIC_SCALE_2D or ANISOTROPIC_SCALE_3D keywords.

Note
If the dataspace is anisotropic (either automatically or by setting SCALE_ISOTROPIC to 2), then the ANISOTROPIC_SCALE_2D or ANISOTROPIC_SCALE_3D keywords may be used to change the scaling. If the dataspace is isotropic then the ANISOTROPIC_SCALE_2D and ANISOTROPIC_SCALE_3D keywords are ignored.

STREAMLINES

If this keyword is set then the UV field is drawn using streamlines with direction symbols.

STREAMLINE_NSTEPS

If STREAMLINES is set, then set this keyword to an integer giving the number of steps to take for each streamline. The default is 100. This keyword is ignored for arrows or wind barbs.

STREAMLINE_STEPSIZE

If STREAMLINES is set, then set this keyword to a floating point value giving the normalized step size for each step in a streamline. The default is 0.2. This keyword is ignored for arrows or wind barbs.

STRETCH_TO_FIT

Set this keyword to indicate whether the visualizations should be stretched to fit within the view. The default value is 1 (True).

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.

SUBSAMPLE_METHOD

If either X_SUBSAMPLE or Y_SUBSAMPLE are set to a value greater than 1, then set this keyword to specify the method used for subsampling. Possible values are:


0	Nearest neighbor (the default)
1	Bilinear

SYM_COLOR

Set this keyword to an RGB value specifying the color for the missing-point symbols.

Note
This color is applied to the symbols only if the USE_DEFAULT_COLOR keyword is explicitly set equal to zero.

SYM_INDEX

Set this keyword to an integer specifying the symbol to be used for missing points. Possible values are:


0	No symbol
1	Plus sign, `+' (default)
2	Asterisk
3	Period (Dot)
4	Diamond
5	Triangle
6	Square
7	X
8	Arrow Head

SYM_SIZE

Set this keyword to a floating-point value from 0.0 to 1.0 specifying the size of the missing-point symbols.

THICK

Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to be used to draw the vectors or streamlines. The default is 1.0 points.

TITLE

Set this keyword to a string specifying a title for the newly-created visualization. The text annotation will be added to the dataspace containing the new visualization. If the TITLE is specified, you can also specify any of the FONT_COLOR, FONT_NAME, FONT_SIZE, and FONT_STYLE keywords to control the title appearance.

Note
Prior to IDL version 7.1, the TITLE keyword specified the title for the iTool window rather than for the visualization. Use the WINDOW_TITLE keyword to create a window title.

TRANSPARENCY

Set this keyword equal to an integer between 0 and 100 that specifies the percent transparency of the vectors. The default is zero.

USE_DEFAULT_COLOR

Set this keyword to use the color of the vectors for the missing-point symbols (this is the default). If this keyword is explicitly set to 0, the color specified by the SYM_COLOR keyword is used for symbols.

VECTOR_COLORS

Set this keyword to a vector or two-dimensional array with the same number of elements as U, or a two-dimensional array containing RGB triplets (or RGBA) representing colors to be used for each vector. If this keyword is set to an array with the same number of elements as U, 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. For RGB triplets the first dimension of VECTOR_COLORS must be 3 (or 4 for RGBA), and the second dimension must be equal to the number of elements in U. If this keyword is omitted, the vectors are drawn in the color specified by the COLOR keyword or the default color.

If VECTOR_COLORS is not of type byte, it is byte scaled into the range 0-255. This is useful if you have an auxiliary dataset (say of type float) and you want to color your vectors according to this auxiliary dataset.

Tip
IDL will remember the original data range of VECTOR_COLORS before byte scaling. If you insert a colorbar for the vector visualization, the colorbar axis will have the correct range for your auxiliary dataset.

VECTOR_STYLE

Set this keyword to specify the style of the vector visualization. Possible values are:


0	Arrows	Vectors are drawn as arrows with lines for arrowheads
1	Wind barbs	Vectors are drawn as wind barbs with feathers and flags

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.

Note
The contents of the newly-selected view will be emptied unless /OVERPLOT is set.

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.

Note
The contents of the newly-selected view will be emptied unless /OVERPLOT is set.

VIEW_TITLE

Set this keyword equal to a scalar string that will be placed in a text annotation centered horizontally in the current view, near the top. The text will be created with the properties (size, style, color, etc.) defined for text annotations in the current tool style.

VIEW_ZOOM

Set this keyword to a floating-point number giving the initial view zoom factor. For example, setting VIEW_ZOOM to 2.0 would give an initial zoom of 200%. The default is 1.0.

WINDOW_TITLE

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

X_STREAMPARTICLES

If STREAMLINES is set, then set this keyword to an integer giving the number of streamline particles in the x direction. The default is 25. This keyword is ignored for arrows or wind barbs.

X_SUBSAMPLE

Set this keyword to an integer giving a subsampling factor to be used for the first dimension of U and V. This keyword is ignored if AUTO_SUBSAMPLE is true.

Y_STREAMPARTICLES

If STREAMLINES is set, then set this keyword to an integer giving the number of streamline particles in the y direction. The default is 25. This keyword is ignored for arrows or wind barbs.

Y_SUBSAMPLE

Set this keyword to an integer giving a subsampling factor to be used for the second dimension of U and V. This keyword is ignored if AUTO_SUBSAMPLE is true.

ZVALUE

Set this keyword to a float giving the Z coordinate to be used for the vectors or streamlines. The default is 0.0. If ZVALUE is non-zero, all vectors or streamlines will be plotted at that Z value, and the dataspace will change to three-dimensional.

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

Set this keyword to specify a logarithmic axis. The minimum value of the axis range must be greater than zero.

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

XMARGIN

Set this keyword to a floating-point value giving the horizontal margin size between the edge of the view and the edge of the visualization. The valid range is 0.0 to 0.49, and the default value is 0.15. This keyword is ignored if STRETCH_TO_FIT is set to 0.

YMARGIN

Set this keyword to a floating-point value giving the vertical margin size between the edge of the view and the edge of the visualization. The valid range is 0.0 to 0.49, and the default value is 0.15. This keyword is ignored if STRETCH_TO_FIT is set to 0.

[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

Tip
Available fonts also include any additional TrueType fonts available to IDL. For a discussion of TrueType fonts, see About TrueType Fonts).

Instead of using the [XYZ]TICKFONT_INDEX keyword, to access these additional fonts you may wish to create an iTools Style that sets the desired font for your axes. For more in iTools Styles, see What Are Styles? (iTool User's Guide).

[XYZ]TICKFONT_SIZE

Set this keyword to a floating-point 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 (Application Programming).

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.)

Note
For more information, see [XYZ]TICKFORMAT.

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.

Valid values include:


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

Note
For all tick layout styles, at least one tick label will appear on each level of the axis (even if no major tick marks fall along the axis line). If there are no major tick marks, the single tick label will be centered along the axis.

[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).

Valid unit strings include:

"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').

Note
Julian values must be in the range -1095 to 1827933925, which corresponds to calendar dates 1 Jan 4716 B.C.E. and 31 Dec 5000000 C.E., respectively.

[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

Set this keyword to a string representing the title of the specified axis.

ZOOM_ON_RESIZE

Set this keyword to 1 (True) so that visualizations change size when the window is resized. The default value is 0 (False), which ensures that visualizations remain the same size regardless of the window dimensions.

Examples

These examples show how to overlay and visualize vector data on images.

Example 1

This example shows how to overlay wind vectors on a map with continents.

; Read the data.
RESTORE, FILEPATH('globalwinds.dat', SUBDIR=['examples','data'])
; Set up the map projection, grid, and continents.
IMAP, /NO_SAVEPROMPT, MAP_PROJECTION='Equirectangular', $
LIMIT=[0,-180,89,-30]
tool = IGETCURRENT(TOOL=oTool)
void = oTool->DoAction('Operations/Insert/Map/Continents')
; Modify the inserted shape
ISETPROPERTY, 'shape', TRANSPARENCY=0
ISETPROPERTY, 'shape', FILL_COLOR=[192,192,192]

; Create the vector visualization and color vectors by magnitude
IVECTOR, u, v, x, y, /OVERPLOT, $
AUTO_COLOR=1, $ ; Color by magnitude
RGB_TABLE=39

; Insert a colorbar.
void = oTool->DoAction('Operations/Insert/Colorbar')
; Add a title to the colorbar
ISETPROPERTY, 'colorbar', AXIS_TITLE='Magnitude'
; Rearrange items for a pleasing display
ITRANSLATE, 'data space', Y=25, /DEVICE
ITRANSLATE, 'colorbar', Y=-15, /DEVICE

Figure 11-18: iVector Example One

Example 2

This example shows how to visualize wind barbs as a function of time and altitude in the atmosphere.

; Create random data as a function of time vs altitude.
nx = 13
ny = 12
u = 10*RANDOMU(s, nx, ny)*REBIN(FINDGEN(1,ny)+1,nx,ny)
v = 20*(RANDOMU(s, nx, ny) - 0.5)
x = TIMEGEN(nx, Units='Minutes', YEAR=2000, STEP=30)
y = FINDGEN(ny) + 1

; Create the wind barb visualization.
LOADCT, 39, /SILENT
TVLCT, r, g, b, /GET
rgbTable = [[r],[g],[b]]
IVECTOR, u, v, x, y, VECTOR_STYLE=1, $ ; wind barbs
   AUTO_COLOR=1, $ ; color by magnitude
   RGB_TABLE=rgbTable, $
   YRANGE=[0,12], $
   YTITLE='Altitude (km)', $
   XTICKFORMAT='(C(CDI2.2,CMoA," ",CYI0,"!C",CHI,":",CMI2.2))'

; Insert a colorbar.
tool = IGETCURRENT(TOOL=oTool)
void = oTool->DoAction('Operations/Insert/Colorbar')

; Add a title to the colorbar
ISETPROPERTY, 'colorbar', AXIS_TITLE='Magnitude'
; Rearrange items for a pleasing display
ITRANSLATE, 'data space', Y=30, /DEVICE
ITRANSLATE, 'colorbar', Y=-15, /DEVICE

Figure 11-19: iVector Example Two

Example 3

This example shows how to visualize global wind data as streamlines on a global map.

; Read the data.
RESTORE, FILEPATH('globalwinds.dat', SUBDIR=['examples','data'])
; Set up the map projection, grid, and continents.
IMAP, /NO_SAVEPROMPT, MAP_PROJECTION='Mollweide'
tool = IGETCURRENT(TOOL=oTool)
void = oTool->DoAction('Operations/Insert/Map/Continents')
; Modify the inserted shape
ISETPROPERTY, 'shape', TRANSPARENCY=0
ISETPROPERTY, 'shape', FILL_COLOR=[192,192,192]

; Create the streamline visualization.
LOADCT, 39, /SILENT
TVLCT, r, g, b, /GET
rgbTable = [[r],[g],[b]]
IVECTOR, u, v, x, y, /OVERPLOT, $
   AUTO_COLOR=1, $ ; color by magnitude
   RGB_TABLE=rgbTable, $
   /STREAMLINES

; Insert a colorbar
void = oTool->DoAction('Operations/Insert/Colorbar')
; Add a title to the colorbar
ISETPROPERTY, 'colorbar', AXIS_TITLE='Magnitude'
; Rearrange items for a pleasing display
ITRANSLATE, 'colorbar', Y=-15, /DEVICE

Figure 11-20: iVector Example Three

Version History


6.3	Introduced
6.4	Deprecated the MARK_POINTS keyword
6.4	Added the ANISTROPIC_SCALE_2D, ANISTROPIC_SCALE_3D, FIT_TO_VIEW, INSERT_COLORBAR, RENDERER, SCALE_ISOTROPIC, SYM_COLOR, SYM_INDEX, SYM_SIZE, TRANSPARENCY, USE_DEFAULT_COLOR, VIEW_ZOOM, and [XYZ]LOG keywords
7.1	Added the FONT_COLOR, FONT_NAME, FONT_SIZE, FONT_STYLE, WINDOW_TITLE, CURRENT_ZOOM, DEPTHCUE_BRIGHT, DEPTHCUE_DIM, STRETCH_TO_FIT, XMARGIN, YMARGIN, and ZOOM_ON_RESIZE keywords. Modified behavior of the TITLE keyword to create a text annotation along with the visualization.