extracttilts(1)                                                extracttilts(1)



NAME
       extracttilts - Extract tilt angles or other info from image or metadata
       file

SYNOPSIS
       extracttilts  [option] input_image_file [output_file]

DESCRIPTION
       Extracttilts will extract one kind of information from the header of an
       image file, if it is present, and produce a file with a list of the
       values.  The default behavior is to extract tilt angles; these can be
       extracted from headers in the Agard/FEI format or from headers produced
       by SerialEM.  Enter an option to extract one of the other kinds of
       information available.

       In addition to extracting data stored in the extended header of an MRC
       image file, the program can extract from a metadata file written by
       SerialEM in the autodoc format.  A wider range of information can be
       stored in such a file than in the header.  The metadata file must have
       the same number of sections as the image file.  Information for which
       no specific option is provided can be extracted by providing the name
       of the information with the -key option.  The program can also extract
       attributes that are present for each section in an HDF file, either
       with one of the specific options or by name.

OPTIONS
       Extracttilts uses the PIP package for input (see the manual page for
       pip). Thus, the following options can be specified either as command
       line arguments (with the -) or one per line in a command file (without
       the -).  Options can be abbreviated to unique letters; the currently
       valid abbreviations for short names are shown in parentheses.


       -input (-inp) OR -InputFile    File name
              Image file with header information to extract.  If this option
              is not entered, the first non-option argument will be taken as
              the input file, An image file name is required unless the -other
              option is entered.

       -output (-ou) OR -OutputFile   File name
              Output file for header values.  If this option is not entered,
              the second non-option argument will be taken as the output file.
              If no output file is given, the values are printed to standard
              output.

       -mdoc (-md) OR -MdocMetadataFile
              Obtain values from a metadata file named with the name of the
              input file plus '.mdoc', instead of from the extended header of
              the image file.  A file with this name is generated by SerialEM
              when an option is selected to save extra information in a meta-
              data file.  Thus, you do not supply the name of the .mdoc file
              when you use this option.  As of IMOD 4.8.7, the program will
              look for such a file automatically if the requested values are
              not present in the image file header.  Thus, this option is no
              longer necessary except for forcing the program to ignore values
              in the header and access the '.mdoc' file first.

       -other (-ot) OR -OtherMetadataFile       File name
              Obtain values from the metadata file with the given name,
              instead of from the extended header of the image file.  Use this
              option if the .mdoc file name does not start with the input
              image file name, or if the image file is not available.  If you
              do omit an image input file and want an output file, you must
              specify it with -output instead of as a non-option argument.

       -tilts (-t) OR -TiltAngles
              Extract tilt angles from header or metadata file (the default
              behavior).  The angles are in degrees.

       -stage (-s) OR -StagePositions
              Extract stage positions from header or metadata file.  The posi-
              tions are in microns.

       -mag (-ma) OR -Magnifications
              Extract magnifications from header or metadata file.

       -intensities (-int) OR -Intensities
              Extract intensities from header or metadata file.  On the Tec-
              nai, these are the intensity values reported by Tecnai script-
              ing, which range from 0 to 1 and differ by a scaling factor from
              the percent C2 readout in the Tecnai user interface.  On the
              JEOL, they correspond to the percent C3 readout shown in Seri-
              alEM.

       -exp (-e) OR -ExposureDose
              Extract incident dose on specimen during camera exposure,
              referred to as exposure dose in SerialEM.  The units are elec-
              trons per square Angstrom.

       -camera (-c) OR -CameraExposure
              Extract camera exposure time, in seconds, from metadata file.

       -pixel (-p) OR -PixelSpacing
              Extract pixel size in Angstroms from metadata file

       -defocus (-d) OR -Defocus
              Extract defocus in microns from metadata file.  The value is the
              focus readout of the microscope, not the defocus measured by
              autofocusing.

       -key (-k) OR -KeyName     Text string
              Complete name of item to extract from a metadata file or HDF
              file.  The item will be extracted and printed as a string, so it
              can consist of string rather than numeric values.

       -attrib (-at) OR -AttributesInHDFfile
              Output all attributes in an HDF file to a file in the autodoc
              format.  Metadata for each image will appear in sections of the
              file starting

       -warn (-w) OR -WarnIfTiltsSuspicious
              When extracting tilt angles, warn if more than half of them are
              near zero or any are bigger than 95 degrees.

       -all (-al) OR -AllPieces
              Extract the selected item for all pieces of a montage.  The
              default is to output the value for the last piece of the montage
              at each Z value.

       -help (-h) OR -usage
              Print help output

       -StandardInput
              Read parameter entries from standard input.

       If the program is started with no command line arguments, it reverts to
       interactive input with the following entries:

       Image file with tilt information
       Output file for tilt angles, or Return to print to standard output


EXAMPLES
       Some of these examples mention HDF files.  Currently the only way to
       get information originating in SerialEM into an HDF file is to create
       the HDF file from the image stack and .mdoc file.  This command works
       if SerialEM created a metadata file "rootname.mrc.mdoc":
          newstack -mdoc rootname.mrc rootname.hdf

       Extract tilt angles from an MRC or HDF file into a file:
          extracttilts rootname.st rootname.tlt

       Extract magnifications from an MRC or HDF file to the terminal:
          extracttilts -mag rootname.st

       Extract exposure times from an MRC or HDF file to the terminal (for an
       MRC file, rootname.st.mdoc must exist):
          extracttilts -camera rootname.st

       Extract defocus values for an MRC file that has been renamed to the
       terminal
          extracttilts -defocus -other rootname.st.mdoc rootname_orig.st
          extracttilts -defocus -other rootname.st.mdoc

       Extract defocus values for an MRC file that has been renamed to a file
          extracttilts -defocus -other rootname.st.mdoc -out rootname.defocus

       Extract acquisition times from an MRC file or HDF file to the terminal
          extracttilts -key DateTime rootname.st


HISTORY
       Written by David Mastronarde, 1999
       Converted for PIP input and to get other information, 3/17/04
       Access to HDF files and automatic access to mdoc file, 6/5/14

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                 4.9.3                     extracttilts(1)