Next: Vector Field File Difference:
Up: Command Line Utilities
Previous: Vector Field File Format
Making Bitmaps from Vector Fields:
avf2ppm
The avf2ppm utility converts a
collection of vector field files (e.g., .omf, .ovf) into color
bitmaps suitable for inclusion into documents or collating into movies.
The command line arguments control filename and format selection, while
plain-text configuration files, modeled after the
mmDisp configuration dialog
box, specify conversion parameters.
Launching
The avf2ppm launch command is:
tclsh oommf.tcl avf2ppm [standard options] [-config file] [-f] \
[-filter program] [-format <P3|P6|B24>] [-ipat pattern] \
[-opatexp regexp] [-opatsub sub] [-v level] [infile ...]
where
- -config file
- User configuration file that specifies the image conversion
parameters. This file is discussed in detail below.
- -f
- Force overwriting of existing (output) files. By default, if
avf2ppm tries to create a file, say foo.ppm, that already
exists, it generates instead a new name of the form foo.ppm-000,
or foo.ppm-001, ..., or foo.ppm-999, that doesn't exist
and writes to that instead. The -f flag disallows alternate
filename generation, and overwrites foo.ppm instead.
- -filter program
- Post-processing application to run on each app2ppm output
file. May be a pipeline of many programs.
- -format <P3|P6|B24>
- Specify the output image file format. Currently supported formats are
the true color Portable Pixmap (PPM) formats P3
(ASCII text) and P6 (binary), and the uncompressed Windows
BMP 24 bits-per-pixel format. The default is P6.
- -ipat pattern
- Specify input files using a pattern including ``glob-style'' wildcards.
Mostly useful in DOS.
- -opatexp regexp
- Specify the ``regular expression''
applied to input filenames to determine portion to be replaced in
generation of output filenames.
Default:
(\.[^.]?[^.]?[^.]?$|$)
- -opatsub sub
- The string with which to replace the portion of input filenames
matched by the -opatexp regexp during output filename
generation. The default is
.ppm
for type P3 and P6 file
output, .bmp
for B24 file output.
- -v level
- Verbosity (informational message) level, with 0 generating only
error messages, and larger numbers generating additional information.
The level value is an integer, defaulting to 1.
- infile ...
- List of input files to process.
The file specification options require some explanation. Input files
may be specified either by an explicit list (infile ...),
or by giving a wildcard pattern, e.g., -ipat *.omf, which is
expanded in the usual way by avf2ppm (using the Tcl command
glob). Unix shells (sh, csh, etc.) automatically expand
wildcards before handing control over to the invoked application, so the
-ipat option is not needed (although it is useful in case of a
``command-line too long'' error). DOS does not do this expansion, so
you must use -ipat to get
wildcard expansion in Windows.
As each input file is processed, a name for the output file is produced
from the input filename by rules determined by handing the
-opatexp and -opatsub expressions to the Tcl regsub command. Refer to the Tcl regsub documentation for
details, but essentially whatever portion of the input filename is
matched by the -opatexp expression is removed and replaced by
the -opatsub string. The default -opatexp expression
matches against any filename extension of up to 3 characters, and the
default -opatsub string replaces this with the extension
.ppm or .bmp.
If you have command line image processing ``filter'' programs, e.g.,
ppmtogif (part of the
NetPBM package), then you can use the -filter
option to pipe the output of avf2ppm through that filter before it
is written to the output file specified by the -opat*
expressions. If the processing changes the format of the file, (e.g.,
ppmtogif converts from PPM to
GIF), then you will likely want to specify a
-opatsub different from the default.
Here is an example that processes all files with the .omf
extension, sending the output through ppmtogif before saving the
results in a files with the extension .gif:
tclsh oommf.tcl avf2ppm -ipat *.omf -opatsub .gif -filter ppmtogif
(On Unix, either drop the -ipat flag, or use quotes to protect
the input file specification string from expansion by the shell, as in
-ipat '*.omf'.) You may also pipe together multiple filters, e.g.,
-filter "ppmquant 256 | ppmtogif".
Configuration files
The details of the conversion process are specified by plain-text
configuration files, with fields analogous to the entries in the
mmDisp configuration dialog
box. Each of the parameters is an element in an array named
plot_config. The default values for this array are taken from the
default configuration file
oommf/app/mmdisp/scripts/avf2ppm.def,
which is a Tcl script read during avf2ppm initialization.
There are several places in the configuration file where colors are
specified. Colors may be represented using the symbolic names in
oommf/config/colors.def, 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.
The sample default configuration script can be used as a starting point for
user (per-run) configuration files. Refer to this sample file and the
mmDisp documentation as we discuss each element of the array
plot_config. (See the Tcl documentation for details of the
array set command.)
- colormaps
- A list of valid colormaps known to the program. This
entry is not user-configurable, and should not appear in user
configuration files.
- arrow,status
- Set to 1 to display arrows, 0 to not draw arrows.
- arrow,colormap
- Select the colormap to use when drawing arrows. Should be one of the
strings specified in the colormaps array element.
- arrow,colorcount
- Number of discretization levels to use
from the colormap. A value of zero will color all arrows with the
first color in the colormap.
- arrow,quantity
- Scalar quantity the arrow color is to represent.
Supported values include x, y, z, xy-angle,
xz-angle, yz-angle, and slice. The
mmDisp configuration dialog box will
present the complete list of allowed quantities (which may be image
dependent).
- arrow,colorphase
- 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, for example, 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.
- arrow,colorinvert
- The colorinvert value should be 1 or 0, signifying to invert or
not invert, respectively. If invert is selected, the the colormap
ordering is reversed, changing for example Blue-White-Red into
Red-White-Blue. If both inversion and phase adjustment are
requested, then inversion is applied first.
- arrow,autosample
- 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.
- arrow,subsample
- 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.
- arrow,size
- Size of the arrows relative to the default size (represented as 1.0).
- arrow,antialias
- If 1, then each pixel along the edge of an arrow is
drawn not with the color of the arrow, but with a mixture of the arrow
color and the background color. This makes arrow boundaries appear
less jagged, but increases computation time. Also, the colors used in
the anti-aliased pixels are not drawn from the arrow or pixel colormap
discretizations, so color allocation in the output bitmap may increase
dramatically.
- pixel,...
- Most of the pixel configuration elements have analogous arrow
configuration elements, and are interpreted in the same manner. The
exceptions are the pixel,opaque element which is discussed next,
the arrow,antialias element which has no corresponding pixel
element, and the qualitative difference in that the auto subsampling
rate for pixels is considerably denser than for arrows.
- pixel,opaque
- 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.
- misc,background
- Specify the background color.
- misc,drawboundary
- If 1, then draw the bounding polygon, if any, as
specified in the input vector field file.
- misc,boundarywidth
- Width of the bounding polygon, in pixels. A value of 0 is treated the
same as 1. To disable drawing of the boundary, use the
misc,drawboundary option.
- misc,boundarycolor
- Color of the bounding polygon.
- misc,boundarypos
- Placement of the bounding polygon, either back or front,
i.e., either behind or in front of the rendered arrows and pixel
elements.
- misc,matwidth
- Specifies the width, in pixels, of a mat (frame) around the outer edge
of the image. The mat is drawn in front of all other objects. To
disable, set matwidth to 0.
- misc,matcolor
- Color of the mat.
- misc,margin
- The size of the border margin, in pixels.
- misc,width, misc,height
- Maximum width and height of the output bitmap, in pixels. If
misc,crop is enabled, then one or both of these dimensions may be
shortened.
- misc,crop
- If disabled (0), then any leftover space in the bitmap (of dimensions
misc,width by misc,height) after packing the image are filled
with the background color. If enabled (1), then the bitmap is cropped
to just include the image (with the margin specified by
misc,margin). NOTE: Some movie formats require that
bitmap dimensions be multiples of 8 or 16. For such purposes, you
should disable misc,crop and specify appropriate dimensions
directly with misc,width and misc,height.
- misc,zoom
- 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
avf2ppm will automatically set the scaling so the image (with
margins) just fits inside the area specified by misc,width and
misc,height.
- misc,rotation
- Counterclockwise rotation in degrees; either 0, 90, 180 or 270.
- misc,datascale
- Scale for arrow size and colormap range; this element is exactly
equivalent to the mmDisp
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 value.
- misc,centerpt
- This element should either be empty, or else be
a three item list of real numbers specifying the center of the display,
in input file mesh units. The OOMMF command line program
avf2ovf
may be invoked with the -info option to determine the range of the
file mesh. This information is also contained in the ``Bounding
box'' message returned when avf2ppm is run, which should in any
event be consulted since any portion of the mesh that is shifted
outside the bounding box will not be rendered. This element provides
the functionality of the scroll bars on the mmDisp main display
window. If an empty value is given, then by default the center of the
mesh is used.
- viewaxis
- Select the view axis, which should be one of +z, -z, +y,
-y, +x, or -x. This option is equivalent to the
mmDisp View|Viewpoint menu control.
- viewaxis,center
- The viewaxis,center element corresponds to the mmDisp
``slice'' selection control. It should be a single real number in the
range of that portion of the input file mesh bounding box corresponding
to the selected view axis. For example, if the view axis is +z or
-z, then the view axis center value should lie between the minimum
and maximum z-values of the file mesh. If an empty value is given,
then the view axis center is set from the corresponding coordinate of
the misc,centerpt value.
The portion of the mesh that is rendered depends upon the interaction
between the bounding box, the center point, the view axis center, and
the axis-selected arrow and pixel spans.
- viewaxis,xarrowspan, viewaxis,yarrowspan,
viewaxis,zarrowspan
- Specifies the thickness of the arrow display slice, for the
corresponding view, e.g., if the view axis is +z or -z, then
only viewaxis,zarrowspan is active. These values for each of
these elements should be either a single real value in units relating
to the corresponding coordinate range of the input file mesh, or else
an empty string, which is interpreted to be the entire thickness of the
mesh in the selected view direction.
- viewaxis,xpixelspan, viewaxis,ypixelspan,
viewaxis,zpixelspan
- Identical interpretation and behavior as the corresponding arrow span
elements, but with regards to pixel display.
array set plot_config {
colormaps {
Red-Black-Blue Blue-White-Red Teal-White-Red
Black-Gray-White Black-White-Black White-Black-White
White-Green-Black Red-Green-Blue-Red
}
arrow,status 1 misc,background #FFFFFF
arrow,colormap Black-Gray-White misc,drawboundary 1
arrow,colorcount 0 misc,boundarywidth 1
arrow,quantity z misc,boundarycolor #000000
arrow,colorphase 0. misc,boundarypos front
arrow,colorinvert 0 misc,matwidth 0
arrow,autosample 1 misc,matcolor #FFFFFF
arrow,subsample 10 misc,margin 10
arrow,size 1 misc,width 640
arrow,antialias 1 misc,height 480
misc,crop 1
pixel,status 1 misc,zoom 0
pixel,colormap Teal-White-Red misc,rotation 0
pixel,colorcount 225 misc,datascale 0
pixel,opaque 1 misc,centerpt {}
pixel,quantity x
pixel,colorphase 0. viewaxis {+z}
pixel,colorinvert 0 viewaxis,center {}
pixel,autosample 1 viewaxis,xarrowspan {}
pixel,subsample 0 viewaxis,xpixelspan {}
pixel,size 1 viewaxis,yarrowspan {}
viewaxis,ypixelspan {}
viewaxis,zarrowspan {}
viewaxis,zpixelspan {}
}
Figure 4:
Sample default configuration
script
avf2ppm.def.
(Description.)
User (per-run) configuration files are specified on the command line
with the -config option. To create a user configuration file,
make a copy of the default avf2ppm.def configuration file, and edit
it as desired in a plain text editor. You may omit any entries that you
do not want to change from the default. (Each entry consists of a name
+ value pair, e.g., misc,width 640.) You may ``layer''
configuration files by specifying multiple user configuration files on
the command line. These are processed from left to right, with the last
value set for each entry taking precedence.
OOMMF Documentation Team
October 30, 2002