Overview
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.
Launching
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]
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.
Inputs
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}}
Oc_Option Add * Nb_InputFilter decompress \
{{.gz .zip} {gzip -dc} .bz2 bunzip2}
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}
Outputs
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 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
oommf/app/mmdisp/scripts/mmdisp.configis read first, followed by the local customization file,
oommf/app/mmdisp/scripts/local/mmdisp.configif 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:
The print_config array controls printing defaults, as displayed in the File|Print... dialog box:
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
misc,rotation 0
pixel,status 0 misc,zoom 0
pixel,autosample 1 misc,datascale 0
pixel,subsample 0 misc,relcenterpt {0.5 0.5 0.5}
pixel,colormap Blue-White-Red
pixel,colorcount 256 viewaxis +z
pixel,quantity x viewaxis,xarrowspan {}
pixel,colorreverse 0 viewaxis,xpixelspan {}
pixel,colorphase 0 viewaxis,yarrowspan {}
pixel,size 1 viewaxis,ypixelspan {}
pixel,opaque 1 viewaxis,zarrowspan {}
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
}
Details
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.