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 + y2 − y1, y1 + x1 − x2).
* 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.