Making Bitmaps from Vector Fields: avf2ppm
Keywords: userguide

Next: Making PostScript from Vector 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 display 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 image display 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 avf2ppm output file. May be a pipeline of several 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 with ``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. The default regular expression is: `(\.[^.]?[^.]?[^.]?$|$)`
`-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 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, in the same format as the mmDisp configuration files.

Each of the configurable parameters is an element in an array named `plot_config`. The default values for this array are read first from the main configuration file

> `oommf/app/mmdisp/scripts/avf2ppm.config`

followed by the local customization file

> `oommf/app/mmdisp/scripts/local/avf2ppm.config`

if it exists. Lastly, any files passed as `-config` options on the command line are input. Each of these parameters is interpreted as explained in the mmDisp documentation, except that avf2ppm ignores the `misc,defaultwindowwidth` and `misc,defaultwindowheight` parameters, and the following additional parameters are available:

`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.
`arrow,outlinewidth`
  Width of a colored outline around each arrow; this can improve visibility of an arrow when it is overlayed against a background with color similar to that of the arrow. Default value is zero, meaning no outline. A value of 1 produces an outline with a recommended width, and other positive values are scaled relative to this.
`arrow,outlinecolor`
  If `arrow,outlinewidth` is positive, then this is the color of the arrow outline.
`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,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`.

The default configuration file can be used as a starting point for user configuration files. You may also use configuration files produced by the File|Write config... command in mmDisp, although any of the above avf2ppm-specific parameters that you wish to use will have to be added manually, using a plain text editor. You may omit any entries that you do not want to change from the default. 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.

    array set plot_config {
        arrow,status       1                misc,background    #FFFFFF
        arrow,antialias    1                misc,drawboundary  1
        arrow,outlinewidth 0.0              misc,boundarywidth 1
        arrow,outlinecolor #000000          misc,boundarycolor #000000
        arrow,colormap     Red-Black-Blue   misc,boundarypos   front
        arrow,colorcount   100              misc,matwidth      0
        arrow,quantity     z                misc,matcolor      #FFFFFF
        arrow,colorphase   0                misc,margin        10
        arrow,colorreverse 0                misc,width         640
        arrow,autosample   1                misc,height        480
        arrow,subsample    10               misc,crop          1
        arrow,size         1                misc,zoom          0
                                            misc,rotation      0
        pixel,status       1                misc,datascale     0
        pixel,colormap     Teal-White-Red   misc,relcenterpt   {0.5 0.5 0.5}
        pixel,colorcount   100
        pixel,opaque       1                viewaxis            +z
        pixel,quantity     x                viewaxis,xarrowspan {}
        pixel,colorphase   0                viewaxis,xpixelspan {}
        pixel,colorreverse 0                viewaxis,yarrowspan {}
        pixel,autosample   1                viewaxis,ypixelspan {}
        pixel,subsample    0                viewaxis,zarrowspan {}
        pixel,size         1                viewaxis,zpixelspan {}
    }

Figure 5: Contents of default configuration file `avf2ppm.config`. (Description.)

OOMMF Documentation Team
September 29, 2018