ale/doc/user/tdf/index.xml

<?xml version="1.0"?>

<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
	"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">

<chapter id="user-tdf"><title>Transformation Data Files</title>

<p>Transformation data files are useful when performing alignment in several
passes or refining rendering options, and are necessary for specifying
barrel/pincushion distortion parameters.  They also offer a way to manually
specify alignment when ALE cannot automatically align images.  </p>

<s><t>Multiple-pass alignment</t>

<p>To align images in multiple passes, load the saved results of each previous
pass, as follows:</p>

<pre>$ ale --trans-save=a.t &lt;first pass arguments&gt;
$ ale --trans-load=a.t --trans-save=b.t &lt;second pass arguments&gt;
$ ale --trans-load=b.t --trans-save=c.t &lt;third pass arguments&gt;
.
.
.
</pre>

</s><s><t>Rendering option refinement</t>

<p>To refine rendering options using the same alignment, first save the alignment
for the first option set, and then load the saved alignment information with
each subsequent option set, setting the perturbation upper bound to zero to
prevent a new alignment pass from occurring:</p>

<pre>$ ale --trans-save=a.t &lt;first option set&gt;
$ ale --trans-load=a.t --perturb-upper=0 &lt;second option set&gt;
$ ale --trans-load=a.t --perturb-upper=0 &lt;third option set&gt;
.
.
.
</pre>

</s><s><t>Alignment file syntax (version 2)</t>

<p>There are two varieties of alignment file syntax that are both read and written
by ALE 0.7.0.  The most basic of these is version 2.  Version 3 is slightly
more complex, and is covered in the next section.</p>

<p>At the highest level, version 2 transformation data files contain the following
components: (a) a version command, and (b) a sequence of transformation
commands, one for each supplemental frame.  Each line of text should contain at
most one command, between which optional comments may be interspersed.  A
transformation command can be Euclidean, projective, or default.  Euclidean and
projective commands take several arguments, including the width and height of
the supplemental frame.  Default commands take no arguments.  Commands are
outlined in more detail below.</p>

<s><t>Version command</t>

<p>The version 2 version command is as follows:</p>

<pre>V 2
</pre>

</s><s><t>Euclidean commands</t>

<p>The structure of a Euclidean command is as follows:</p>

<pre>E &lt;image width&gt; &lt;image height&gt; &lt;x-offset&gt; &lt;y-offset&gt; &lt;rotation-angle&gt;
</pre>

</s><s><t>Projective commands</t>

<p>Projective commands map the four corners of the supplemental frame to four
points in the rendering coordinate system:</p>

<pre>P &lt;image width&gt; &lt;image height&gt; &lt;top-left-x&gt; &lt;top-left-y&gt; &lt;blx&gt; &lt;bly&gt; &lt;brx&gt; &lt;bry&gt; &lt;trx&gt; &lt;try&gt;
</pre>

</s><s><t>Default commands</t>

<p>Default commands can be explicitly written as follows:</p>

<pre>D
</pre>

<p>Alternatively, if there are more frames than alignment commands (euclidean,
projective, or default), then the last supplemental frames in the frame
sequence will be assigned the default command.</p>

</s><s><t>Comments</t>

Comments can be inserted with the following syntax:

<pre># This comment extends to the end of this line.  I can write anything I want here.
</pre>

</s></s><s><t>Alignment file syntax (version 3)</t>

<p>Version 3 syntax is required for specifying transformations for the original
frame, and for specifying barrel/pincushion distortion parameters.  </p>

<p>In version 3, the first transformation command is associated with the
original frame, instead of being associated with the first supplemental frame.
Also, barrel/pincushion distortion commands can precede each projective,
Euclidean, or default command.</p>

<s><t>Version command</t>

<p>The version 3 version command is as follows:</p>

<pre>V 3
</pre>

</s><s><t>Barrel/pincushion distortion command</t>

<p>In version 3, barrel/pincushion distortion commands are supported.  Distortion
is modeled as a transformation affecting the distance of image features from the
image center.  The distorted distance is expressed as a polynomial function of
the undistorted distance.  Zeroth and first order coefficients are fixed or
automatically determined; additional coefficients can be specified explicitly,
using the following syntax:</p>

<pre>B &lt;n&gt; &lt;coefficient 2&gt; &lt;coefficient 3&gt; ... &lt;coefficient n+1&gt;
</pre>

<p>Barrel/pincushion distortion commands should precede the projective, Euclidean,
or default transformation command for the corresponding frame.</p>

</s></s>

</chapter>