imodtrans(1) General Commands Manual imodtrans(1)
NAME
imodtrans - Transform an IMOD model file.
SYNOPSIS
imodtrans [options] input_model output_model
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 and Xfalign; 3) as a single 3-D transformation
in a file, such as is produced by Solvematch. When the transforma-
tion 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 or by Rotatevol, specify rotations around Z, then Y,
then X.
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 dimen-
sions of the other image file. If these dimensions differ from those
of the original image file, enter them with the -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 addi-
tional transformations if that center-to-center mapping is not appro-
priate.
The situation may be more complicated when the original and new volumes
have different pixel sizes in their headers. 3dmod takes a change
in pixel size into account when a model is loaded onto a volume, unless
coordinate scaling is overridden with the -m option to 3dmod. If
you scale a volume in 2D with newstack by binning, expansion, or
squeezing, or in 3D with binvol or squeezevol, a model will dis-
play 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 -i option and the name of the scaled image file, instead of using
the -sx, -sy, -sz, and -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 -i option. The resulting model will have the new coordinates,
but it will not load correctly into 3dmod without using the -m
option in 3dmod (which tells 3dmod to ignore coordinate informa-
tion).
The -i and -I options can also be used to manipulate the information
stored in the model about the coordinate system of an associated image
file, without actually transforming the model data. This information
is referred to as image coordinate reference information. Models gen-
erated within IMOD almost always have such information, whereas models
generated outside of IMOD may well lack it. If a model has reference
information, it will show up as "refcurtrans" and "refcurscale" entries
in the ascii model format that can be output with "imodinfo -a". If
there is no reference information, it can be inserted with either the
-I option or the -i option, which will not transform the model in this
case because there is no existing information about what coordinate
system to transform from. If there is existing reference information,
the -i option will transform the model by converting it from pixel
coordinates of the original volume to the scaled coordinate system,
then from those coordinates to the pixel coordinates of the specified
volume. This operation is inappropriate if the existing reference
information is wrong in some way. That can happen if a volume is gen-
erated outside of IMOD without preserving the header entries of the
original volume from IMOD, then an IMOD program is used to generate a
model from that derived model. The IMOD program will store incorrect
reference information in the model. Using the -I option with the orig-
inal IMOD volume will simply replace the incorrect information without
doing any transformation.
More generally, if an original and new volume have corresponding pixels
but the header information for scaling or origin differs in some way,
the model will not load correctly on the new volume in 3dmod without
the -m option. In this case, the -i option to Imodtrans will not work,
but using the -I option and the new volume will be equivalent to load-
ing the model in 3dmod with -m and resaving it.
For 3-D transformations, however they are specified, all contour points
are transformed, as well as all mesh points, surface normals, and clip-
ping planes. The mesh is transformed because formerly it was not pos-
sible 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.
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 vol-
ume 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.
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 -i option with the destination volume. If that
volume is not available, then the same operation can be done with the
-R option, entering 1 to transform to a rotated volume or 0 to trans-
form to the original volume.
OPTIONS
-tx value
-ty value
-tz value
The -tx, -ty and -tz options can be used to translate the model
in the particular direction by the given floating point value,
in pixels.
-sx value
-sy value
-sz value
The -sx, -sy and -sz options can be used to scale the model in
the particular dimension by the given floating point value.
-rx value
-ry value
-rz value
The -rx, -ry and -rz options can be used to rotate the model
about the particular axis by the given value in degrees.
-2 transform file
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 trans-
formed, unless the -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 rota-
tion options or with -3. The translation options -tx and -ty
can be used with this option, and -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 trans-
formation.
-l line #
Transform the whole model with the single 2D transformation at
the given line number in the transform file entered with -2.
Lines are numbered from 0.
-3 transform file
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 -2. It can be used with the transla-
tion options, but each option can be entered only once, and the
shift is applied after the transformation.
-S factor
Scale the X, Y, and Z shifts in the transformations from trans-
form 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.
-n NX,NY,NZ
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.
-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.
-f If the model was last displayed on images loaded into 3dmod
with Y and Z flipped, use this option to apply the transforma-
tion to the flipped coordinates. The default is to apply the
transformation to native, unflipped coordinates, which will work
with transformations obtained from Solvematch.
-i image file
Transform the model coordinates as if the model were being
loaded into 3dmod together with the given image file. The maxi-
mum coordinates in the model (reported as "max # # #" in the
output from Imodinfo) will be changed to match those in the
image file. This transformation occurs before any of the other
operations except flipping with the -Y option.
-I image file
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 ori-
gin is changed in the header of the image file, such as with
Alterheader, 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 -Y option.
-Y Exchange Y and Z coordinates in the model file, without changing
the flag indicating the model's flip state.
-T Toggle the flag indicating the model's flip state, without actu-
ally flipping the data.
-R direction
Rotate the model by 90 degrees around the X axis; if direction
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
direction is 0 the rotation is by +90 degrees and the origin is
adjusted in the inverse direction. This option cannot be entered
with -Y or -T. 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.
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 cre-
ated, using the -origin option to Newstack or Blendmont, then the
command would be:
imodtrans -2 set.xg -i set.ali -S 0.5 input_model output_model
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 transla-
tion is:
xtrans = (alignedXsize - rawXsize / binning) / 2.
ytrans = (alignedYsize - rawYsize / binning) / 2.
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 transforma-
tion that would align the images. The command is:
imodtrans -2 set.xg -l 0 -n bXsize,bYsize,bZsize input_model out-
put_model
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
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
or
imodtrans -R 0 input_model output_model
AUTHOR
Jim Kremer and David Mastronarde
SEE ALSO
midas, xfalign, solvematch, matchvol, rotatevol,
clip, 3dmod
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 imodtrans(1)