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.
To align images in multiple passes, load the saved results of each previous pass, as follows:
$ ale --trans-save=a.t <first pass arguments> $ ale --trans-load=a.t --trans-save=b.t <second pass arguments> $ ale --trans-load=b.t --trans-save=c.t <third pass arguments> . . .
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:
$ ale --trans-save=a.t <first option set> $ ale --trans-load=a.t --perturb-upper=0 <second option set> $ ale --trans-load=a.t --perturb-upper=0 <third option set> . . .
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.
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.
The version 2 version command is as follows:
V 2
The structure of a Euclidean command is as follows:
E <image width> <image height> <x-offset> <y-offset> <rotation-angle>
Projective commands map the four corners of the supplemental frame to four points in the rendering coordinate system:
P <image width> <image height> <top-left-x> <top-left-y> <blx> <bly> <brx> <bry> <trx> <try>
Default commands can be explicitly written as follows:
D
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.
# This comment extends to the end of this line. I can write anything I want here.
Version 3 syntax is required for specifying transformations for the original frame, and for specifying barrel/pincushion distortion parameters.
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.
The version 3 version command is as follows:
V 3
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:
B <n> <coefficient 2> <coefficient 3> ... <coefficient n+1>
Barrel/pincushion distortion commands should precede the projective, Euclidean, or default transformation command for the corresponding frame.