.na
.nh
.TH imodtrans 1 3.6.16 IMOD
.SH NAME
imodtrans \- Transform an IMOD model file.
.SH SYNOPSIS
imodtrans [options] input_model output_model
.SH DESCRIPTION
Applies transformations to an IMOD model and copies the result to a new
IMOD model. The transformations can be specified in three
different ways: 1) as translations, rotations,
and scaling factors; 2) as a list of 2-D transformations in a file, one for
each section, such as are
produced by Midas(1) and Xfalign(1); 3) as a single 3-D transformation in a
file, such as is produced by Solvematch(1).
When the transformation is specified by individual components, they are
applied in the order that they are entered, and any option can be entered
more than once.
If you want your rotations to match those applied by the
Slicer in 3dmod(1) or by Rotatevol(1), specify rotations around Z, then Y,
then X.
.P
If you plan to display the transformed model on a different image file from
the one that it was built on, the program will not be able to translate the
model to the correct location unless it knows the dimensions of the other
image file. If these dimensions differ from those of the original image
file, enter them with the
.B -n
option. With the dimensions known, the program will translate from the middle
of the original volume to the middle of the new one, and you can specify
additional transformations if that center-to-center mapping is not
appropriate.
.P
The situation may be more complicated when the original and new volumes have
different pixel sizes in their headers. 3dmod(1) takes a change in pixel size
into account when a model is loaded onto a volume, unless coordinate scaling
is overridden with the
.B -n
option to 3dmod(1). If you scale a volume in 2D with newstack(1) by binning,
expansion, or squeezing, or in 3D with binvol(1) or squeezevol(1), a model
will display correctly on the scaled volume with no need to run imodtrans on
it. When it is saved from 3dmod, it will be written with coordinates that
match the new volume. If you need to transform a model into those
coordinates without having to load it into 3dmod, use imodtrans with the
.B -i
option and the name of the scaled image file, instead of using the
.B -sx, -sy, -sz,
and
.B -n
options. The transformed model will have the scaled coordinates and will also
load correctly in 3dmod. If for some reason you do use the scaling and new
size options instead, do not use the
.B -i
option. The resulting model will have the new coordinates, but it will not load
correctly into 3dmod without using the
.B -m
option in 3dmod.
.P
For 3-D transformations, however they are specified, all contour points are
transformed, as well as all mesh points, surface normals, and clipping
planes. The mesh is transformed because formerly it was not possible to
remesh contours that have been rotated out
of the X/Y plane, but this is now possible. For 2-D transformations, only
contour points are transformed, so clipping planes are not preserved and the
model will have to be remeshed. However, if a single 2D transformation is
applied to the whole model it is converted to a 3D transformation and the
entire model is properly transformed.
.P
The program can also manipulate the flipped state of the model in Y and Z
either by actually flipping the Y and Z coordinates, or by simply toggling the
flag that indicates whether the model was loaded on data that were flipped in
3dmod. Either way
may be used after flipping a volume with "clip flipyz" to change a model built
on the
unflipped volume so that it will load onto the flipped volume.
In addition, the model can be transformed to match a particular image
file, just the same as if it were loaded onto that file in 3dmod. The order
of operations is: flipping, then transforming to match an image file, then
transforming either via transformations in a file or via the entered
options.
.P
If a volume is rotated with "clip rotx", a model built on the original
volume will load correctly in 3dmod on the rotated volume, and a model
built on the rotated volume will load correctly on the original
volume. To transform the model in this case without loading on the
other volume, use the
.B -i
option with the destination volume. If that volume is not available,
then the same operation can be done with the
.B -R
option, entering 1 to transform to a rotated volume or 0 to transform
to the original volume.
.SH OPTIONS
.TP
.B -tx \fIvalue\fR
.PD 0
.TP
.B -ty \fIvalue\fR
.TP
.B -tz \fIvalue\fR
.PD
The
.B -tx, -ty
and
.B -tz
options can be used to
translate the model in the particular direction by the given floating point
value, in pixels.
.TP
.B -sx \fIvalue\fR
.PD 0
.TP
.B -sy \fIvalue\fR
.TP
.B -sz \fIvalue\fR
.PD
The
.B -sx, -sy
and
.B -sz
options can be used to
scale the model in the particular dimension by the given floating point value.
.TP
.B -rx \fIvalue\fR
.PD 0
.TP
.B -ry \fIvalue\fR
.TP
.B -rz \fIvalue\fR
.PD
The
.B -rx, -ry
and
.B -rz
options can be used to
rotate the model about the particular axis by the given value in degrees.
.TP
.B -2 \fItransform file\fR
Transform the model in 2-D sections using the given transform file
as input. One line is expected per section, and slices at Z values greater
than the
number of lines will not be transformed, unless the
.B -l
option is given to apply one transform to the whole model.
This option is useful for
transforming a model to match an
image stack that has been aligned with Xfalign or Midas.
This option cannot be entered with the scaling or rotation
options
or with
.B -3.
The translation options
.B -tx
and
.B -ty
can be used with this option, and
.B -tz
can be used when applying one transform to the whole model. In each case, the
option can be entered only once, and the shift is applied after the transformation.
.TP
.B -l \fIline #\fR
Transform the whole model with the single 2D transformation at the given line
number in the transform file entered with
.B -2.
Lines are numbered from 0.
.TP
.B -3 \fItransform file\fR
Transform the model with the single 3-D transformation in the given file.
The format of the file is to have 3 lines, each with 4 numbers, the
coefficients for multiplying the old X, Y, and Z coordinates and a translation
value. The first, second, and third lines are for computing new X, Y, and
Z coordinates, respectively.
This option cannot be entered with the scaling or rotation
options, or with
.B -2.
It can be used with the translation options, but each option can be entered
only once, and the shift is applied after the transformation.
.TP
.B -S \fIfactor\fR
Scale the X, Y, and Z shifts in the transformations from transform files by the given
factor. This option is needed, e.g., if transformations have shifts based on
unbinned coordinates and the model is now in
binned coordinates.
.TP
.B -n \fINX,NY,NZ\fR
Specify the dimensions of the image file on which the model is to be
displayed, if these dimensions are not the same as for the image file
on which the model was originally built. This entry is needed to
have the model translated to the correct location when image file sizes
differ.
.TP
.B -z
Apply Z-scaling to the model, using the Z-scale from the model header, before
transforming the model. The transformed model will then be descaled in Z so
that it will display correctly with the same Z-scale. This option would be
needed to retain the shape of a Z-scaled model, but it would probably prevent
it from matching a transformed image file.
.TP
.B -f
If the model was last displayed on images loaded into 3dmod with Y and Z
flipped, use this option to apply the transformation to the flipped
coordinates. The default is to apply the transformation to native, unflipped
coordinates, which will work with transformations obtained from Solvematch.
.TP
.B -i \fIimage file\fR
Transform the model coordinates as if the model were being loaded into 3dmod
together with the given image file. The maximum coordinates in the model
(reported as "max # # #" in the output from Imodinfo(1)) will be changed to
match those in the image file. This transformation occurs before any of
the other operations except flipping with the
.B -Y
option.
.TP
.B -I \fIimage file\fR
Adjust the image coordinate reference information in the model to match
that in the given image file, without modifying model coordinates.
This option is useful if the pixel spacing or origin is changed in the
header of the image file, such as with Alterheader(1), after a model has
been built on that file. Such changes in header would cause an
inappropriate scaling or shift when loading the model on the modified
image or other images files derived from it. The model resulting from
this operation would again load correctly on such image files. This
operation occurs before any others, including flipping with the
\fB-Y\fR option.
.TP
.B -Y
Exchange Y and Z coordinates in the model file, without changing the flag
indicating the model's flip state.
.TP
.B -T
Toggle the flag indicating the model's flip state, without actually flipping
the data.
.TP
.B -R \fIdirection\fR
Rotate the model by 90 degrees around the X axis; if \fIdirection\fR is
1 then the rotation is by -90 degrees, the same as for "clip rotx",
and image
origin information in the model header will be adjusted the same as it
is for a volume by "clip rotx". If \fIdirection\fR is 0 the rotation
is by +90 degrees and the origin is adjusted in the inverse
direction. This option cannot be entered with \fB-Y\fR or \fB-T\fR. If
the model was built on a file that was loaded into 3dmod with the -Y
option, it will first be flipped into the native orientation of that
file, then rotated, and its flipped flag will be cleared.
.SH Examples
Example 1: Suppose a model is drawn on a raw stack (set.st) and needs to
be transformed to fit on a binned by 2 stack (set.ali) that was aligned with
transformations in set.xg. The aligned file might be a different size
in X and Y than the size of the raw stack divided by the binning. If the
origin was adjusted when the aligned stack was created, using the
.B -origin
option to Newstack(1) or Blendmont(1), then the command would be:
imodtrans -2 set.xg -i set.ali -S 0.5 input_model output_model
.br
First, the program reduces all X and Y coordinates by 2 to match the
coordinate system in set.ali, and shifts points based on the change in origin
values. Then it multiples the shifts in set.xg by 0.5, since they are in
unbinned coordinates, and applies the transformations.
However, if the origin was not adjusted for any size change, then it is
necessary to add a translation to account for it. The needed translation is:
xtrans = (alignedXsize - rawXsize / binning) / 2.
ytrans = (alignedYsize - rawYsize / binning) / 2.
.br
And the command is
imodtrans -2 set.xg -i set.ali -S 0.5 -tx xtrans -ty ytrans input output
Example 2: Suppose a model is drawn on one stack (seta.ali) and needs to fit
on another stack (setb.ali) that is rotated by approximately 90 degrees. The
file set_AtoB.xf has a single line with the transformation that would align
the images. The command is:
imodtrans -2 set.xg -l 0 -n bXsize,bYsize,bZsize input_model output_model
.br
This command works because the input model has the size of seta.st stored as
its maximum coordinates, and because the output file size is given. The
prgram is thus able to shift the model by the difference between the center
coordinates of the two stack.
Example 3: Suppose a model is drawn on a volume and a new volume is
made with "clip flipyz". If the first volume was loaded into 3dmod with the "-Y"
option for rotation around X, the model was saved in flipped
coordinates. To load it on the new volume, the flip flag needs to be
turned off with:
imodtrans -T input_model output_model
However, if the first volume was loaded in its native orientation, then
the model needs to be flipped with:
imodtrans -Y input_model output_model
Example 4: Suppose a volume is rotated wih "clip rotx". To transform a
model built on the original volume to the coordinates of the rotated
volume, you can use:
imodtrans -i rotated_volume input_model output_model
.br
or
imodtrans -R 1 input_model output_model
To transform a model built on the rotated volume to the coordinates of
the original volume, you can use:
imodtrans -i original_volume input_model output_model
.br
or
imodtrans -R 0 input_model output_model
.SH AUTHOR
Jim Kremer and David Mastronarde
.SH SEE ALSO
midas(1), xfalign(1), solvematch(1), matchvol(1), rotatevol(1), clip(1),
3dmod(1)
.SH BUGS
Email bug reports to mast@colorado.edu.