Name

mir — Multi Image Renderer

Synopsis

mir [-options] [scriptfile]

Description

The mir(1) command runs the mir interpreter on the named file. If no file is given, mir reads from stdin.

mir is intended to apply geometric transformations to an image. It renders input files onto an output canvas by mapping points (xin, yin) from the source file onto points (xout, yout) on the output canvas. It can do so using a single affine transformation for the entire image, or by applying distinct affine transformations for triangular areas of the image. In the latter case, areas of the source image that are not covered by the triangulation are simply ignored.

mir reads a program that may consist of commands, blocks of vertex definitions, and blocks of triangle definitions. Typically, a program will consist of a “setup” section, followed by one or more “image placement” sections, followed by a command to write the output to a file.

Any command may appear in any section, although some obviously make more sense in certain contexts. Commands are all single letters followed by optional arguments. Multiple commands that do not take arguments may appear on the same line. The available commands are detailed below. A few commands (like ?, ~, and E) are mainly for interactive use and testing purposes.

mir allows comments almost anywhere in its input: The hash character (“#”) and any text following it up to the next new line are ignored.

Commands in the mir language

?
Show a brief help text about the available commands.
~
Display current transformation matrices.
A MF00 MF01 MF02 MF10 MF11 MF12
Directly specify new “forward” mapping. The “reverse” mapping is automatically recalculated.
a MI00 MI01 MI02 MI10 MI11 MI12
Directly specify new “reverse” mapping. The “forward” mapping is automatically recalculated.
B wout hout bppout wtile htile_ trans
Specify output width and height, output bytes per pixel, tile width and height, and transparent input value. wout hout, but not the other parameters, are interpreted as multiples of the x and y output scales. bpp may be one (8 bits) or two (16 bits).
D name
Directory prefix for all input filenames. There must be precisely one space between the “D” and the directory name. The entire rest of the line (up to the next newline) is interpreted as the prefix, including any spaces.
E
Exit the program.
F name
Read a new file. Any number of spaces and tab characters may appear between the “F” and the filename. The filename may not contain any spaces. The actual file loaded is determined by concatenating the filename to the current directory prefix (without inserting a slash or anything else). The program aborts if no filename is given, but quietly substitutes a 1x1 image if the file cannot be read. If this is the first image read, the size of the output image is set by the size of the image loaded (unless explicitly given by a B command or -B option). Reading a new image does not reset the transformation matrices.
G MG00 MG01 MG02 MG10 MG11 MG12
Directly specify new “global” mapping. This mapping is not actually used for rendering.
In
Set interpolation level. n must be 0, 1, or 2 for nearest neighbor, bilinear, or bicubic interpolation.
O dxout dyout dxin dyin
Specify pixel offsets. Arguments may contain basic math: Addition, subtraction, multiplication, division, modulo, power, and parentheses are supported.
S Sxout Sxout Sxin Syin
Specify scale factors. These factors are applied to all subsequent vertex definitions and also to the arguments of the B command.
R
Render image directly. See below.
V
Toggle reverse video.
W name
Write output image. Any number of spaces and tab characters may appear between the “W” and the filename. The filename may not contain any spaces. The “directory prefix” is not used. If tiling is enabled (by specifying nonzero wtile and htile_ to the B command), the name must contain two %i place holders for sprintf to insert the row and column indices of the tile (both counted from zero). Writing an output image does not reset the transformation matrices. If no W command is given ever, the final output is written to stdout in PGM format unless the program is terminated by the E command.
X
Following the X command, lines that specify vertices are interpreted as xin yin xout yout rather than xout yout xin yin. A subsequent X command cancels this mode of operation.
Z n
Zero the drawing space to the given gray value n. If n is not given, the default is 0 (unless specified with the -Z command line option).

Rendering images with an explicit transformation matrix

The coordinate transformations used for rendering images may be specified explicitly with the A or a commands. In that case, after setup, the R command may be issued directly.

Commonly, however, mir is used to determine coordinate transformations from specified matchings between points in the output space and points in the input space. This can be done either in a global fashion, or in a local fashion using a triangular mesh over the image.

Rendering images with a global affine transformation based on matched vertices

If “vertex” lines precede the R command, any previously specified matrices (see the A and a commands) are discarded, and the transformation is determined by a least-square optimization process over the given vertex pairs. Vertex lines consist of four coordinates on a line:

xout yout xin yin

(If the X command is in effect, the order is xin yin xout yout instead.) Coordinates may be given directly as floating point numbers, but basic arithmetic is allowed: mir understands multiplication, division, addition, subtraction, modulo, and power. It also understands parentheses. Importantly, however, spaces are not allowed inside equations. mir also appears to allow for variable assignment and dereference, but the author of this page doesn’t yet understand how that works.

After evaluation, the current offset (O command) is applied and then (!) the current scale (S command).

Any number of vertex pairs may appear on consecutive lines.

After the last vertex line, the R command should appear immediately without any other intervening commands.

The number of vertex pairs given determines how the affine transformation is constructed: * If zero, the matrices set by A or a are used. * If one, the vertex specifies a linear shift on top of existing scaling and/or rotation set by A or a. * If two, calculates an affine transformation based on the two points and a fictional point created as (x1 + y2y1, y1 + x1x2). * If three or more, calculates an affine transformation by least-squares optimization.

Rendering images with local affine transformations

To render with locally defined transformations, first specify the vertices of any number of triangles using vertex lines as before, but do not issue an R command immediately afterward. Instead, follow the vertex lines with a line consisting of a single “T” (for Triangles), followed by any number of “triangle lines.”

Triangles are defined by triplets i j k which must be indices into the previously defined vertices (counting from zero). Specifying vertices that do not exist is likely to crash the program. Each triangle definition must be given its own line.

The triangles must be followed by the R command.

Command line options

-Bw,h
Output width and height in pixels. The numbers are multiplied by any scale factors set by a preceding -S option. Default: Determined from first-loaded input image.
-b
Save overlap images for later intensity correction. Filename is constructed as input.back.pgm, where input is the source filename with a three letter extension removed.
-g
Overlay a grid. If given twice, input image pixels are ignored entirely.
-i

Increase interpolation level:

  • Default level is zero: nearest neighbor.
  • Level one: bilinear.
  • Level two (or more): bicubic.
-Nn
Least points. The result of inferring the affine transformation may be rejected (forcing a recalculation) if the average error is too large, but only if at least n points remain available for the inference process. Default value is 4.
-o
Show outline triangles instead of normal image output.
-r
Reverse video. Output image has reverse polarity of input images.
-SSxout,Sxout,Sxin,Syin
Scale. These scale factors are applied to all vertex coordinates. Default values are 1 for all. [Interpretation of arguments is not affected by the -X option.]
-s
Show solid triangles instead of normal image output.
-Tn
Transparent input value. Pixels of this color are not copied to output. (Useful for out-of-bounds areas.) For unknown reasons, the value used to be interpreted as a multiple of the xout scale in force at the time the option is seen, but DAW changed that. Now it is simply a value between 0 and 255.
-X
Same as the X command, this affects lines that consist of four numbers. With the -X flag given, lines are interpreted as xin yin xout yout rather than xout yout xin yin.
-Zn
Specifies background gray value for output. (The default is 0.) For unknown reasons, the value used to be interpreted as a multiple of the xout scale in force at the time the option is seen, but DAW changed that. Now it is simply a value between 0 and 255.
-?
Enable prompting. (That is, show the text “Enter a MIR command >” when mir is ready for command input.)

Options that do not take arguments can be combined. There may not be any spaces between options and their arguments.

Output

mir's output consists of the constructed image file, lots of debugging information on stderr, and information about computed transformations on stdout. The latter has the form “_filename_ AF m00 m01 m02 m10 m11 m12”. Precisely one such line appears for each R command for which mir calculated a global affine transformation. R commands with triangulation result in one line for each triangle. Each “AF” line is followed by an “AI” line with the inverse transformation.

Author

mir was written by Tom Wetzel. This page was written by Daniel Wagenaar. DW does not yet fully understand mir.