<usrguide name="FLIRT schedule language reference" section="l" rootdir="../" author="Mark Jenkinson" 
year="2000">

<p>
This document describes the commands that can be used within a schedule
file for <type>flirt</type> via the <attrib>-schedule</attrib> option.
</p>

<section title="Variables">

There are two types of data variables that are manipulated in a schedule
file: <em>scalar</em> and <em>matrix</em> data.

<subsection title="Scalar data">

Any constant can be used as a scalar value in the schedule file.  In addition
token names can be used, and the following token names are currently defined:
<itemize>
<item><param-out>MAXDOF</param-out>
<break></break>the user-defined maximum degrees of freedom (via the 
<attrib>-dof</attrib> option).</item>
<item><param-out>MINSAMPLING</param-out>
<break></break>the minimum sampling that is sensible, as calculated from the
input volumes - defined as Max(Min(refvol voxel dims),Min(testvol voxel dims)).
</item>
</itemize>

</subsection>

<subsection title="Matrix data">

Most data in a schedule file is manipulated in matrix form.  Each matrix
has 17 columns, with the first column representing the cost function value
and the remaining 16 a reshaped version of the 4 by 4 affine matrix that
corresponds to that cost function measurement.

<paragraph>
The matrices that can be accessed are: <param-out>S P U UA UB ... UZ</param-out>.
<break></break>
Note that <param-out>S P</param-out> and <param-out>U</param-out> have special functions
while <param-out>UA UB ... UZ</param-out> are provided for user manipulation.
</paragraph>

<paragraph>
In addition, a subset of rows of a given matrix can be used in place
of any matrix. 
<break></break>
The form of this reference is: <param-out>mat:r1-r2</param-out> 
<break></break>
where <param-out>mat</param-out> is the matrix name (e.g. <param-out>UB</param-out>), <param-out>r1</param-out>
is the first row, and <param-out>r2</param-out> the last row to be used.  Note that
some parts of this may be omitted so that <param-out>mat:r1- </param-out> specifies
the matrix from row <param-out>r1</param-out> to the end, and <param-out>mat:r1</param-out> just 
specifies a single row (<param-out>r1</param-out>).
<break></break>NB: The first row of any matrix has an index of 1.
</paragraph>

<paragraph>
Matrix <param-out>U</param-out> is special as it is used to store the results
of the current optimisation.
</paragraph>
<paragraph>
Matrices <param-out>S</param-out> and <param-out>P</param-out> are used to store the (corresponding)
results of the 8mm search algorithm.
</paragraph>

</subsection>
</section>

<section title="Commands">

<itemize>
<item><function>#</function>
<break></break>Comment line</item>

<item><function>clear</function><param-out>mat</param-out>
<break></break>Clears the matrix <param-out>mat</param-out>.</item>

<item><function>copy</function><param-out>mat1</param-out> <param-out>mat2</param-out>
<break></break>Copies the contents of matrix <param-out>mat1</param-out> into matrix <param-out>mat2</param-out>.  
It does not affect the contents of matrix <param-out>mat1</param-out>.</item>

<item><function>print</function><param-out>mat</param-out>
<break></break>Prints the contents of matrix <param-out>mat</param-out> to the screen.</item>

<item><function>save</function><param-out>mat</param-out> <param-out>filename</param-out>
<break></break>Saves an ascii copy of the contents of matrix <param-out>mat</param-out> to the file
named by <param-out>filename</param-out>.</item>

<item><function>read</function> <param-out>mat</param-out> <param-out>filename</param-out>
<break></break>Reads an ascii file (<param-out>filename</param-out>) and stores 
the contents in matrix <param-out>mat</param-out>.</item>

<item><function>printparams</function> <param-out>mat</param-out>
<break></break>Prints the contents of matrix <param-out>mat</param-out> to the screen as parameter 
values (rather than reshaped 4 by 4 affine matrices).</item>

<item><function>saveparams</function> <param-out>mat</param-out>
<param-out>filename</param-out>
<break></break>Saves an ascii copy of the contents of matrix <param-out>mat</param-out>, as parameter 
values, to the file named by <param-out>filename</param-out>.</item>

<item><function>readparams</function> <param-out>mat</param-out> <param-out>filename</param-out>
<break></break>Reads an ascii file (<param-out>filename</param-out>) where each line represents 
1 cost value followed by 12 parameter values.  It then converts these parameters
to reshaped affine matrices and stores the contents in matrix <param-out>mat</param-out>.</item>

<item><function>setrow</function> <param-out>mat</param-out> <param-out>v1 v2 ... v16</param-out>
<break></break>Adds a row to the end of matrix <param-out>mat</param-out> with the value given by the 
reshaped matrix: <param-out>v1 v2 ... v16</param-out>.  Note that only the 16 matrix values 
are used, not the cost value (which is initialised to 0).</item>

<item><function>setoption</function> <param-out>option</param-out> <param-out>v1 v2 ...</param-out>
<break></break>Sets the value of certain defined options.  The name of the option is
specified as the first parameter, then all remaining parameters are treated
as a vector of scalars.  Note that no matrix arguments can be used here.
At present the available options are <em>smoothing, fuzzyfraction, tolerance, rescaletolerance</em>
and <em>boundguess</em>.</item>

<item><function>sort</function> <param-out>mat</param-out>
<break></break>Sorts the rows of matrix <param-out>mat</param-out> into <param-out>ascending</param-out> order
based on the first column entries of each row (the cost function values).</item>

<item><function>dualsort</function> <param-out>mat1 mat2</param-out>
<break></break>Sorts the rows of matrix <param-out>mat1</param-out> and <param-out>mat2</param-out> into 
<em>ascending</em> order based on the first column entries <param-out>mat1</param-out> only 
(the cost function values).</item>

<item><function>search</function> [ <param-out>dof</param-out> ]
<break></break>Performs the 8mm search algorithm on the currently defined image pair.
The result is returned in matrices <param-out>S</param-out> and <param-out>P</param-out> where
<param-out>S</param-out> contains the optimised values (which are sorted), 
and <param-out>P</param-out> the pre-optimised values from the search grid.  
The rows of the two matrices correspond to each other.  The optional argument
<param-out>dof</param-out> specifies the number of degrees of freedom for the search (only 6 
or 7 are currently sensible).</item>

<item><function>optimise</function> <param-out>dof</param-out> <param-out>mat</param-out> [ <param-out>perturbation_vector</param-out> <param-out>rel/abs</param-out> <param-out>max_iterations</param-out> ]
<break></break>Performs a single optimisation on the currently defined
image pair.  Number of degrees of freedom are specified by <param-out>dof</param-out>
and initial parameter values are taken from <param-out>mat</param-out>.  In addition
a perturbation vector can be applied to the parameters, using either
relative <param-out>rel</param-out> or absolute <param-out>abs</param-out> addition (relative is in terms
of specially chosen parameter perturbations so that a 1 unit relative change
should be a small but measurable change).  The perturbation vector may be of
any length, terminated by either <param-out>rel</param-out> or <param-out>abs</param-out> - if the vector
is longer than the number of parameters, extra values are ignored.
The final parameter (which must follow either <param-out>rel</param-out> or <param-out>abs</param-out>)
is the maximum number of iterations that the optimisation is allowed.
<break></break>
Note that the minimum of <param-out>dof</param-out> and the user-defined maximum degrees
of freedom (<param-out>MAXDOF</param-out>) will always be used.
</item>

<item><function>measurecost</function> <param-out>dof</param-out> <param-out>mat</param-out> [ <param-out>perturbation_vector</param-out> <param-out>rel/abs</param-out> ]
<break></break>Measures (or re-measures) the cost function specified by the
transformations stored in the matrix <param-out>mat</param-out>.  It stores the
results in <param-out>U</param-out>.  Other syntax is
the same as for <param-out>optimise</param-out>.
</item>

<item><function>setscale</function> <param-out>scale</param-out>
<break></break>Sets the scaling (subsampling) of the current image pair.  Permissable
values of <param-out>scale</param-out> are: 8, 4, 2 and 1.</item>

<item><function>if</function> <param-out>val1</param-out> <param-out>op</param-out> <param-out>val2</param-out>
<break></break>Determines whether the <em>next line only</em> is executed.  The test
condition compares two scalars: <param-out>val1</param-out> and <param-out>val2</param-out> using
the boolean operation <param-out>op</param-out>.  There are 6 permissable values for 
<param-out>op</param-out>, which are: <em> <lt></lt> , <gt></gt> , == , != , <lt></lt>= , <gt></gt>= </em>
</item>
</itemize>

</section>

<section title="Example">
The default flirt schedule file is:

<pre>
# 8mm scale
setscale 8
clear S
clear P
search


# 4mm scale
setscale 4
clear U
clear UA 
clear UB
clear US
clear UP

# remeasure costs at this scale
measurecost 7 S 0 0 0 0 0 0 rel
copy U US
clear U
measurecost 7 P 0 0 0 0 0 0 rel
copy U UP
dualsort US UP

# optimise best 3 candidates (pre and post 8mm optimisations)
clear U
optimise 7 US:1-3  0.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 4
optimise 7 UP:1-3  0.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 4
sort U
copy U UA

# select best 3 optimised solutions and try perturbations of these
clear U
copy UA:1-3 U
optimise 7 UA:1-3  1.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 4
optimise 7 UA:1-3 -1.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 4
optimise 7 UA:1-3  0.0   1.0   0.0   0.0   0.0   0.0   0.0  rel 4
optimise 7 UA:1-3  0.0  -1.0   0.0   0.0   0.0   0.0   0.0  rel 4
optimise 7 UA:1-3  0.0   0.0   1.0   0.0   0.0   0.0   0.0  rel 4
optimise 7 UA:1-3  0.0   0.0  -1.0   0.0   0.0   0.0   0.0  rel 4
optimise 7 UA:1-3  0.0   0.0   0.0   0.0   0.0   0.0   0.1  abs 4
optimise 7 UA:1-3  0.0   0.0   0.0   0.0   0.0   0.0  -0.1  abs 4
optimise 7 UA:1-3  0.0   0.0   0.0   0.0   0.0   0.0   0.2  abs 4
optimise 7 UA:1-3  0.0   0.0   0.0   0.0   0.0   0.0  -0.2  abs 4
sort U
copy U UB


# 2mm scale
setscale 2
clear U
clear UC
clear UD
clear UE
clear UF

# remeasure costs at this scale
measurecost 7 UB 0 0 0 0 0 0 rel
sort U
copy U UC

clear U
optimise 7  UC:1  0.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 4
copy U UD
if MAXDOF > 7
 clear U
if MAXDOF > 7
 optimise 9  UD:1  0.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 1
copy U UE
if MAXDOF > 9
 clear U
if MAXDOF > 9
 optimise 12 UE:1  0.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 2
sort U
copy U UF

# 1mm scale
setscale 1
clear U
optimise 12 UF:1  0.0   0.0   0.0   0.0   0.0   0.0   0.0  rel 1
sort U
</pre>
</section>

</usrguide>
