OOMMF Home next up previous index
Next: Data Archive: mmArchive Up: OOMMF Documentation Previous: Data Graph Display: mmGraph

Vector Field Display: mmDisp

mmDisp Screen Shot

The application mmDisp displays two-dimensional slices of three-dimensional spatial distributions of vector fields. mmDisp currently supports display of 1D (i.e., scalar) and 3D vector data. It can load field data from files in a variety of formats, or it can accept data from client applications, such as a running solver. mmDisp offers a rich interface for controlling the display of vector field data, and can also save the data to a file or produce PostScript print output.

mmDisp may be started either by selecting the mmDisp button on mmLaunch, or from the command line via

tclsh oommf.tcl mmDisp [standard options] [-config file] \
   [-net <0|1>] [filename]

-config file
User configuration file that specifies default display parameters. This file is discussed in detail below.
-net <0|1>
Disable or enable a server which allows the data displayed by mmDisp to be updated by another application. By default, the server is enabled. When the server is disabled, mmDisp may only input data from a file.

If a filename is supplied on the command line, mmDisp takes it to be the name of a file containing vector field data for display. That file will be opened on startup.

Input to mmDisp may come from either a file or from a client application (typically a running solver), in any of the OOMMF vector field formats. Other file formats can also be supported if a translation filter program is available.

Client applications that send data to mmDisp control the flow of data. The user, interacting with the mmDisp window, determines how the vector field data are displayed.

File input is initiated through the File|Open... dialog box. Several example files are included in the OOMMF release in the directory app/mmdisp/examples. When the Browse button is enabled, the ``Open File'' dialog box will remain open after loading a file, so that multiple files may be displayed in sequence. The Auto configuration box determines whether the vector subsampling, data scale, zoom and slice settings should be determined automatically (based on the data in the file and the current display window size), or whether their values should be held constant while loading the file.

mmDisp permits local customization allowing for automatic translation from other file formats into one of the OOMMF vector field formats that mmDisp recognizes. When loading a file, mmDisp compares the file name to a list of extensions. An example extension is .gz. The assumption is that the extension identifies files containing data in a particular format. For each extension in the list, there is a corresponding translation program. mmDisp calls on that program as a filter which takes data in one format from standard input and writes to standard output the same data in one of the formats supported by mmDisp. In its default configuration, mmDisp recognizes the patterns .gz, .z, and .zip, and invokes the translation program gzip -dc to perform the ``translation.'' In this way, support for reading compressed files is ``built in'' to mmDisp on any platform where the gzip program is installed.

There are two categories of translations supported: decompression and format conversion. Both are modified by the usual method of local customization. The command governing decompression in the customization file is of the form

Oc_Option Add * Nb_InputFilter decompress {{.gz .zip} {gzip -dc}}
The final argument in this command is a list with an even number of elements. The first element of each pair is the filename extension. The second element in each pair is the command line for launching the corresponding translation program. To add support for bzip2 compressed files, change this line to
Oc_Option Add * Nb_InputFilter decompress \
                {{.gz .zip} {gzip -dc} .bz2 bunzip2}
This option also affects other applications such as mmGraph that support ``on-the-fly'' decompression. In all cases the decompression program must accept compressed input on standard input and write the decompressed output to standard output.

There is also input translation support for filters that convert from foreign (i.e., non-OOMMF) file formats. For example, if a program foo were known to translate a file format identified by the extension .bar into the OVF file format, that program could be made known to mmDisp by setting the customization command:

Oc_Option Add * Nb_InputFilter ovf {.bar foo}
This assumes that the program foo accepts input of the form .bar on standard input and writes the translated results to standard output.

The vector field displayed by mmDisp may be saved to disk via the File|Save As... dialog box. The output is in the OVF format. The OVF file options may be set by selecting the appropriate radio buttons in the OVF File Options panel. The Title and Desc fields may be edited before saving. Enabling the Browse button allows for saving multiple files without closing the ``Save File'' dialog box.

The File|Print... dialog is used to produce a PostScript file of the current display. On Unix systems, the output may be sent directly to a printer by filling the Print to: entry with the appropriate pipe command, e.g., |lpr. (The exact form is system dependent.) The other print dialog box options are described in the configuration files section below.

The File|Write config... dialog allows one to save to disk a configuration file holding the current display parameters. This file can be used to affect startup display parameters, or used as input to the avf2ppm and avf2ps command line utilities that convert files from the OVF format into bitmap images and PostScript printer files, respectively. (mmDisp does not provide direct support for writing bitmap files.) Details of the configuration file are discussed below.


The menu selection File|Clear clears the display window. The menu selection File|Exit terminates the mmDisp application. The menu Help provides the usual help facilities.

The View menu provides high-level control over how the vector field is placed in the display window. The menu selection View|Wrap Display resizes the display window so that it just contains the entire vector field surrounded by a margin. View|Fill Display resizes the vector field until it fills the current size of the display window. If the aspect ratio of the display window does not match the aspect ratio of the vector field, a larger than requested margin appears along one edge to make up the difference. View|Center Display translates the vector field to put the center of view at the center of the display window. View|Rotate ccw and View|Rotate cw rotate the display one quarter turn counter-clockwise and clockwise respectively. If the display size is not locked (see Options|Lock size below), then the display window also rotates, so that the portion of the vector field seen and any margins are preserved (unless the display of the control bar forces the display window to be wider). View| reDraw allows the user to invoke a redrawing of the display window. The View|Viewpoint tearable submenu supports rotation of the vector field out of the plane of the display, so that it may be viewed from along a different axis.

The menu selection Options|Configure... brings up a dialog box through which the user may control many features of the vector field display. Vectors in the vector field may be displayed as arrows, pixels, or both. The Arrow and Pixel buttons in the Plot type column on the left of the dialog box enable each type of display.

Columns 2-4 in the Configure dialog box control the use of color. Both arrows and pixels may be independently colored to indicate some quantity. The Color Quantity column controls which scalar quantity the color of the arrow or pixel represents. Available color quantities include vector x, y, and z components, total vector magnitude, slice depth, and angles as measured in-plane from a fixed axis. On regularly gridded data the vector field divergence is also available for display.

The assignment of a color to a quantity value is determined by the Colormap selected. Colormaps are labeled by a sequence of colors that are mapped across the range of the selected quantity. For example, if the ``Red-Black-Blue'' colormap is applied to the Color Quantity ``z'', then vectors pointing into the xy-plane (z < 0) are colored red, those lying in the plane (z = 0) are colored black, and those pointing out of the plane (z > 0) are colored blue. Values between the extremes are colored with intermediate colors, selected using a discretization determined by the # of Colors value. This value governs the use of potentially limited color resources, and can be used to achieve some special coloring effects. (Note: The in-plane angle quantities are generally best viewed with a colormap that begins and ends with the same color, e.g., ``Red-Green-Blue-Red.'') The ordering of the colormap can be reversed by selecting the Reverse checkbox. For example, this would change the ``Red-Black-Blue'' colormap to effectively ``Blue-Black-Red.''

Below the Reverse checkbutton in the pixel plot type row is a Opaque checkbutton. If this is selected then arrows below the top row in the pixel slice range (see slice discussion below) will be hidden by the pixel object. If disabled, then the pixel object is translucent, so objects further below are partially visible.

When there are many vectors in a vector field, a display of all of them may be more confusing than helpful. The Subsample column allows the user to request that only a sampling of vectors from the vector field be displayed. The Subsample value is roughly the number of vectors along one spatial dimension of the vector field which map to a single displayed vector (arrow or pixel). Each vector displayed is an actual vector in the vector field--the selection of vectors for display is a sampling process, not an averaging or interpolation process. The subsample rates for arrows and pixels may be set independently. A subsample rate of 0 is interpreted specially to display all data. (This is typically much quicker than subsampling at a small rate, e.g., 0.1.)

The length of an arrow represents the magnitude of the vector field. All arrows are drawn with a length between zero and ``full-scale.'' By default, the full-scale arrow length is computed so that it covers the region of the screen that one displayed vector is intended to represent, given the current subsample rate. Following this default, arrows do not significantly overlap each other, yet all non-zero portions of the vector field have a representation in the display. Similarly, pixels are drawn with a default size that fills an area equal to the region of the screen one pixel is intended to represent, given the pixel subsample rate. The Size column allows the user to (independently) override the default size of pixels and full-scale arrows. A value of 1 represents the default size. By changing to a larger or smaller Size value, the user may request arrows or pixels larger or smaller than the default size.

Below the arrow Size box is the View scale option. If this is enabled (the default) then arrow scaling is adjusted so that a size setting of 1 results in an in-viewplane vector having length approximately equal to the smaller of the two in-plane view-cell dimensions. (The view-cell is the discretization cell multiplied by the subsample setting.) If View scale is disabled then the arrow size is scaled relative to the smallest of all three view-cell dimensions, and is therefore fixed independent of view axis. Disabling both auto subsampling and view scale may make comparisons between different view axis directions easier.

Below the Arrow and Pixel Controls are several additional controls. The Data Scale entry affects the data value scaling. As described above, all arrows are displayed with length between zero and full-scale. The full-scale arrow length corresponds to some scalar value of the magnitude of the vector field. The Data Scale entry allows the user to set the value at which the drawn arrow length goes full-scale. Any vectors in the vector field with magnitude equal to or greater than the data scale value will be represented by arrows drawn at full scale. Other vectors will be represented by shorter arrows with length determined by a linear scale between zero and the data scale value. Similarly, the data scale value controls the range of values spanned by the colormap used to color pixels. The usual use of the Data Scale entry is to reduce the data scale value so that more detail can be seen in those portions of the vector field which have magnitude less than other parts of the vector field. If the data scale value is increased, then the length of the arrows in the plot is reduced accordingly. If the data scale value is decreased, then the length of the arrows is increased, until they reach full-scale. An arrow representing a vector with magnitude larger than the data scale value may be thought of as being truncated to the data scale value. The initial (default) data scale value is usually the maximum vector magnitude in the field, so at this setting no arrows are truncated. Entering 0 into the data scale box will cause the data scale to be reset to the default value. (For OVF files, the default data scale value is set from the ValueRangeMaxMag header line. This is typically set to the maximum vector magnitude, but this is not guaranteed.) The data scale control is intended primarily for use with vector fields of varying magnitude (e.g., H-fields), but may also be used to adjust the pixel display contrast for any field type.

The Zoom entry controls the spatial scaling of the display. The value roughly corresponds to the number of pixels per vector in the fully-sampled vector field. (This value is not affected by the subsampling rate.)

The Margin entry specifies the margin size, in pixels, to be maintained around the vector field.

The next row of entry boxes control slice display. Slice selection allows display of that subset of the data that is within a specified distance of a plane running perpendicular to the view axis. The location of that plane with respect to the view axis is specified in the X-slice center, Y-slice center or Z-slice center entry, depending on the current view axis. The thickness of the slice may be varied separately for arrow and pixel displays, as specified in the next two entry boxes. The slice span boxes interpret specially the following values: 0 resets the slice thickness to the default value, which is usually the thickness of a single cell. Any negative value sets the slice thickness to be the full thickness of the mesh. Values for all of the slice control entries are specified in the fundamental mesh spatial unit, for example, meters. (Refer to the vector field file format documentation for more on mesh spatial units.)

Below the slice contols are controls to specify whether or not a bounding polygon is displayed, and the background color for the display window.

No changes made by the user in the Options|Configure... dialog box affect the display window until either the Apply or OK button is selected. If the OK button is selected, the dialog box is also dismissed. The Close button dismisses the dialog without changing the display window.

The next item under the Options menu is a checkbutton that toggles the display of a control bar. The control bar offers alternative interfaces to some of the operations available from the Options|Configure... dialog box and the View menu. On the left end of the control bar is a display of the coordinate axes. These axes rotate along with the vector field in the display window to identify the coordinate system of the display, and are color coded to agree with the pixel (if active) or arrow coloring. A click of the left mouse button on the coordinate axes causes a counter-clockwise rotation. A click of the right mouse button on the coordinate axes causes a clockwise rotation.

To the right of the coordinate axes are two rows of controls. The top row allows the user to control the subsample rate and size of displayed arrows. The subsample rate may be modified either by direct entry of a new rate, or by manipulation of the slider. The second row controls the current data scale value and zoom (spatial magnification). A vertical bar in the slider area marks the default data scale value. Specifying 0 for the data scale value will reset the data scale to the default value.

The spatial magnification may be changed either by typing a value in the Zoom box of the control bar, or by using the mouse inside the display window. A click and drag with the left mouse button displays a red rectangle that changes size as the mouse is dragged. When the left mouse button is released, the vector field is rescaled so that the portion of the display window within the red rectangle expands until it reaches the edges of the display window. Both dimensions are scaled by the same amount so there is no aspect distortion of the vector field. Small red arrows on the sides of the red rectangle indicate which dimension will expand to meet the display window boundaries upon release of the left mouse button. After the rescaling, the red rectangle remains in the display window briefly, surrounding the same region of the vector field, but at the new scale.

A click and drag with the right mouse button displays a blue rectangle that changes size as the mouse is dragged. When the right mouse button is released, the vector field is rescaled so that all of the vector field currently visible in the display window fits the size of the blue rectangle. Both dimensions are scaled by the same amount so there is no aspect distortion of the vector field. Small blue arrows on the sides of the blue rectangle indicate the dimension in which the vector field will shrink to exactly transform the display window size to the blue rectangle size. After the rescaling, the blue rectangle remains in the display window briefly, surrounding the same region of the vector field, now centered in the display window, and at the new scale.

When the zoom value is large enough that a portion of the vector field lies outside the display window, scrollbars appear that may be used to translate the vector field so that different portions are visible in the display window. On systems that have a middle mouse button, clicking the middle button on a point in the display window translates the vector field so that the selected point is centered within the display window.

mmDisp remembers the previous zoom value and data scale values. To revert to the previous settings, the user may hit the ESC key. This is a limited ``Undo'' feature.

Below the data scale and zoom controls in the control bar is the slice center selection control. This will be labeled Z-slice, X-slice, or Y-slice, depending on which view axis is selected. The thickness of the slice can be set from the Options|Configure... dialog box.

The final item under the Options menu is the Options|Lock size checkbutton. By default, when the display is rotated in-plane, the width and height of the viewport are interchanged so that the same portion of the vector field remains displayed. Selecting the Options|Lock size checkbutton disables this behavior, and also other viewport changing operations (e.g., display wrap).

Several keyboard shortcuts are available as alternatives to menu- or mouse-based operations. (These are in addition to the usual keyboard access to the menu.) The effect of a key combination depends on which subwindow of mmDisp is active. The TAB key may be used to change the active subwindow. The SHIFT-TAB key combination also changes the active subwindow, in reverse order.

When the active subwindow is the display window, the following key combinations are active:

When the active subwindow is the control bar's coordinate axes display, the following key combinations are active:

When the active subwindow is any of the control bar's value entry windows - arrow subsample, size, data scale or zoom, the following key combinations are active:

When the active subwindow is in any of the control bar's sliders--arrow subsample, data scale or slice--the following key combinations are active:

When any of the separate dialog windows are displayed (e.g., the File|Open... or Options|Configure... dialogs), the shortcut CTRL-. (control-period) will raise and transfer keyboard focus back to the root mmDisp window.

Configuration files
The various initial display parameters (e.g., window size, orientation, colormap) are set by configuration files. The default configuration file

is read first, followed by the local customization file,
if it exists. Lastly, any files passed as -config options on the command line are input. The files must be valid Tcl scripts, the main purpose of which is to set elements of the plot_config and print_config arrays, as illustrated in the default configuration file. (See the Tcl documentation for details of the array set command.)

There are several places in the configuration file where colors are specified. Colors may be represented using the symbolic names in oommf/config/colors.config, in any of the Tk hexadecimal formats, e.g., #RRGGBB, or as a shade of gray using the format ``grayD'' (or ``greyD''), where D is a decimal integer from 0-100, inclusive. Examples in the latter two formats are #FFFF00 for yellow, gray0 for black, and gray100 or #FFFFFF for white.

Refer to the default configuration file as we discuss each element of the plot_config array:

Set to 1 to display arrows, 0 to not draw arrows.
If 1, then ignore the value of arrow,subsample and automatically determine a ``reasonable'' subsampling rate for the arrows. Set to 0 to turn off this feature.
If arrow,autosample is 0, then subsample the input vectors at this rate when drawing arrows. A value of 0 for arrow,subsample is interpreted specially to display all data.
Select the colormap to use when drawing arrows. Should be one of the strings specified in the Colormap section of the Options|Configure... dialog.
Number of discretization levels to use from the colormap. A value of zero will color all arrows with the first color in the colormap.
Scalar quantity the arrow color is to represent. Supported values include x, y, z, xy-angle, xz-angle, yz-angle, and slice. The Options|Configure... dialog presents the complete list of allowed quantities, which may be image dependent.
The colorreverse value should be 1 or 0, signifying to reverse or not reverse, respectively. If reverse is selected, then the colormap ordering is inverted, changing for example Blue-White-Red into Red-White-Blue. This corresponds to the Reverse control in the Options|Configure....
The phase is a real number between -1 and 1 that provides a translation in the selected colormap. For the xy-angle, xz-angle and yz-angle color quantities, this displays as a rotation of the colormap, e.g., setting colorphase to 0.333 would effectively change the Red-Green-Blue-Red colormap into Green-Blue-Red-Green. For the other color quantities, it simply shifts the display band, saturating at one end. For example, setting colorphase to 0.5 changes the Blue-White-Red colormap into White-Red-Red. If both inversion and phase adjustment are requested, then inversion is applied first.
Size of the arrows relative to the default size (represented as 1.0).
Enables automatic scaling of arrows determined by the in-viewplane cell dimensions.
Most of the pixel configuration elements have analogous arrow configuration elements, and are interpreted in the same manner. The exception is the pixel,opaque element, which is discussed next. Note too that the auto subsampling rate for pixels is considerably denser than for arrows.
If the opaque value is 1, then the pixel is drawn in a solid manner, concealing any arrows which are drawn under it. If opaque is 0, then the pixel is drawn only partially filled-in, so objects beneath it can still be discerned.
Specify the background color.
If 1, then draw the bounding polygon, if any, as specified in the input vector field file.
String specifying the bounding polygon color, if drawn.
Width of the bounding polygon, in pixels.
The size of the border margin, in pixels.
misc,defaultwindowwidth, misc,defaultwindowheight
Width and height of initial display viewport, in pixels.
misc,width, misc,height
Width and height of displayed area. This will be less than the viewport dimensions if scrollbars are present. These values are ignored during mmDisp initialization, but are written out by the File|Write config... command as a convenience for the avf2ppm command line utility.
Counterclockwise rotation in degrees; either 0, 90, 180 or 270.
Scaling factor for the display. This is the same value as shown in the ``zoom'' box in the mmDisp control bar, and corresponds roughly to the number of pixels per vector in the (original, fully-sampled) vector field. If set to zero, then the scaling is set so the image, including margins, just fits inside the viewport dimensions.
Scale for arrow size and colormap ranges; equivalent to the Data Scale control. In general, this should be a positive real value, but a zero or empty value will set the scaling to its default setting.
If specified, the value should be a three item list of real numbers specifying the center of the display, {x y z}, in file mesh units (e.g., meters).
If specified, the value should be a three item list of real numbers in the range [0, 1] specifying the center of the display in relative coordinates. If both misc,relcenterpt and misc,centerpt are defined, then misc,centerpt takes precedence.
Select the view axis, which should be one of +z, -z, +y, -y, +x, or -x. This option is equivalent to the View|Viewpoint menu control.
viewaxis,xarrowspan, viewaxis,yarrowspan, viewaxis,zarrowspan
Specifies the thickness of the arrow display slice, for the corresponding view. For example, if the view axis is +z or -z, then only viewaxis,zarrowspan is active. The value for each element should be either a real value or an empty string. If the value is zero or an empty string, then the thickness is set to the default value, which is typically the thickness of a single cell. If the value is positive, then it specifies the slice range in file mesh units, e.g., in meters. Lastly, if the value is negative, then the slice is set to the entire thickness of the mesh in that view direction.
viewaxis,xpixelspan, viewaxis,ypixelspan, viewaxis,zpixelspan
Identical interpretation and behavior as the corresponding arrow span elements, but with regards to pixel display.

The print_config array controls printing defaults, as displayed in the File|Print... dialog box:

Paper orientation, either landscape or portrait.
Paper type: letter, legal, A4 or A3.
hpos, vpos
The horizontal and vertical positioning on the printed page. Valid values for hpos are left, center, or right, and for vpos are top, center, or bottom.
Units that the margin and print area dimensions are measured in; either in or cm.
tmargin, lmargin
Top and left margin size, measured in the selected units.
pwidth, pheight
Output print area dimensions, width and height, measured in the selected units. The output will be scaled to meet the more restrictive dimension. In particular, the x/y-scaling ratio remains 1:1.
Boolean value, either 0 or 1. If 1 (true), then the print output is cropped to display only that portion of the vector field that is visible in the display window. If 0, then the display is ignored and the output is scaled so that the entire vector field is printed.

If any of the above elements are set in multiple configuration files, then the last value read takes precedence.

array set plot_config {
  arrow,status       1                misc,background           white
  arrow,autosample   1                misc,drawboundary         1
  arrow,subsample    0                misc,boundarycolor        black
  arrow,colormap     Red-Black-Blue   misc,boundarywidth        1
  arrow,colorcount   256              misc,margin               10
  arrow,quantity     z                misc,defaultwindowwidth   640
  arrow,colorreverse 0                misc,defaultwindowheight  480
  arrow,colorphase   0                misc,width                0
  arrow,size         1                misc,height               0
  arrow,viewscale    1                misc,rotation             0
                                      misc,zoom                 0
  pixel,status       0                misc,datascale            0
  pixel,autosample   1                misc,relcenterpt     {0.5 0.5 0.5}
  pixel,subsample    0
  pixel,colormap     Blue-White-Red   viewaxis                  +z
  pixel,colorcount   256              viewaxis,xarrowspan       {}
  pixel,quantity     x                viewaxis,xpixelspan       {}
  pixel,colorreverse 0                viewaxis,yarrowspan       {}
  pixel,colorphase   0                viewaxis,ypixelspan       {}
  pixel,size         1                viewaxis,zarrowspan       {}
  pixel,opaque       1                viewaxis,zpixelspan       {}
array set print_config {
    orient   landscape                tmargin   1.0
    paper    letter                   lmargin   1.0
    hpos     center                   pwidth    6.0
    vpos     center                   pheight   6.0
    units    in                       croptoview 1
Figure 13.1: Contents of default configuration file mmdisp.config. (description)


The selection of vectors for display determined by the Subsample value differs depending on whether or not the data lie on a regular grid. If so, Subsample takes integer values and determines the ratio of data points to displayed points. For example, a value of 5 means that every fifth vector on the grid is displayed. This means that the number of vectors displayed is 25 times fewer than the number of vectors on the grid.

For an irregular grid of vectors, an average cell size is computed, and the Subsample takes values in units of 0.1 times the average cell size. A square grid of that size is overlaid on the irregular grid. For each cell in the square grid, the data vector from the irregular grid closest to the center of the square grid cell is selected for display. The vector is displayed at its true location in the irregular grid, not at the center of the square grid cell. As the subsample rate changes, the set of displayed vectors also changes, which can in some circumstances substantially change the appearance of the displayed vector field.

Known Bugs
The slice selection feature does not work properly with irregular meshes.

OOMMF Home next up previous index

OOMMF Documentation Team
September 30, 2022