OOMMF Home next up previous contents
Next: Bitmap File Format Conversion: Up: Command Line Utilities Previous: Command Line Utilities


Making Bitmaps from Vector Fields: avf2ppm

The avf2ppm utility converts a collection of vector field files (e.g., .omf, .ohf) into color bitmaps suitable for inclusion into documents or collating into movies. The command line arguments control filename selection, while plain-text configuration files, modeled after the mmDisp configuration dialog box, specify conversion parameters.

Command syntax
The avf2ppm launch command is:

tclsh oommf.tcl -fg avf2ppm [-h] [-tk 0] [-v <level>] [-f] \
   [-type <P3|P6>] [-config <filename>] [-ipat <glob match spec>] \
   [-opatexp <rexp match spec>] [-opatsub <sub spec>] \
   [-filter <program(s)>] [--] [<infile> ...]
where
-h
Display help message.
-tk 0
If -tk 0 is used, then avf2ppm will not use or initialize Tk. Tk is only needed to convert background color requests (see misc,background in the configuration file discussion below) from symbolic form to hexadecimal representation (#RRGGBB). If the background color is specified using the hexadecimal format, then Tk is not needed, and avf2ppm may be run with -tk 0.
-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.
-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.
-type <P3|P6>
Specify the output image file format. Currently support formats are the true color Portable Pixmap (PPM) formats P3 (ASCII) and P6 (binary). The default is P6.
-config <filename>
Specifies a user (per-run) configuration file to use to specify the image conversion parameters. The configuration file is discussed in detail below.
-ipat <glob match spec>
Specify input files using (``glob-style'') wildcards. Mostly useful in DOS.
-opatexp <rexp match spec>
Specify the ``regular expression'' applied to input filenames to determine portion to be replaced in generation of output filenames.
[4] Default: (\.[^.]?[^.]?[^.]?$|$)
-opatsub <sub spec>
The string with which to replace the portion of input filenames matched by the -opatsub during output filename generation. Default: .ppm
-filter <program(s)>
Post-processing application(s) to run on each app2ppm output file.
--
(Two dashes.) Marks the end of options. Anything after this will be interpreted as input vector field files to process.
<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.

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 input files with the .omf extension, sending the output through ppmtogif before saving the results in a files with the extension .gif:

tclsh oommf.tcl -fg 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 '*.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/avf2ppm.def, which is a Tcl script read during avf2ppm initialization.

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, and z. The mmDisp configuration dialog box will present the complete list of allowed quantities (which may be image dependent).
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,mag
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,...
Each pixel configuration element has interpretation analogous to the corresponding array configuration element, except that there is no pixel,antialias element, and the auto subsampling rate for pixels is considerably denser than for arrows.
misc,background
Specify the background color, using any of the forms recognized by the Tk routine Tk_GetColor. In particular, you may use symbolic names such as white, black, green, or hexadecimal representations with the format #RRGGBB (for example, #ffff00 is yellow).
misc,drawboundary
If 1, then draw the bounding polygon, if any, as specified in the input vector field format file.
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
Rotation in degrees; either 0, 90, 180 or 360.



array set plot_config {
    colormaps  { Red-Black-Blue Blue-White-Red Teal-White-Red \
            Black-Gray-White White-Green-Black Red-Green-Blue-Red }
    arrow,status       1
    arrow,colormap     Black-Gray-White
    arrow,colorcount   0
    arrow,quantity     z
    arrow,autosample   1
    arrow,subsample    10
    arrow,mag          1
    arrow,antialias    1
    pixel,status       1
    pixel,colormap     Teal-White-Red
    pixel,colorcount   225
    pixel,quantity     x
    pixel,autosample   1
    pixel,subsample    2
    pixel,mag          1
    misc,background    white
    misc,drawboundary  1
    misc,margin        10
    misc,width         640
    misc,height        480
    misc,crop          1
    misc,zoom          0
    misc,rotation      0
}
Figure 1: 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 Home next up previous Contents

OOMMF Documentation Team
August 10, 1999