imodtrans(1)                                                      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 are 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 -n 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 the -m option.

       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 opera-
       tions is: flipping, then transforming to match an image file, then
       transforming either via transformations in a file or via the entered
       options.

   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 translation,
              scaling, or rotation options, or with -3.

       -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 transla-
              tion, scaling, or rotation options, or with -2.

       -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 transformation to
              the flipped coordinates.  The default is to apply the transfor-
              mation 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.

       -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.


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.



BL3DEMC                              4.3.7                        imodtrans(1)