KEYWORD
    inputFileMode multipleImages tiffSeries palette log CommandLine

DESCRIPTION tiff2mrc
     This application takes a TIFF file and converts it into
     Priism's native file format.  With the "Convert" menu
     select whether you are converting a single file or are
     combining a series of TIFF files into one Priism file.
     For a single file, enter the name in "TIFF File" field;
     combining multiple files is described in the tiffSeries
     topic.  Enter the destination file or window in the
     "MRC File" field and press "DoIt" to perform the
     conversion.  The application also has a command line
     interface if that is more convenient for you.

inputFileMode
     The converter either does one file at a time (the
     "Single File" option in the "Convert" menu) or combines a
     numbered series of files (the "Numbered Series" option).
     The inputs not relevant to the option selected will be
     grayed out.

multipleImages
     When converting a single TIFF file, you have the option
     of setting how to handle the case when multiple images are
     present in the file. The default is to only read the first
     image in the file.  The other options are to treat the
     images as z-sections, separate time measurements, or
     wavelengths.  Treating multiple images as waves does not work
     when each image has multiple wavelengths already (i.e. RGB data
     or when converting files with color tables to RGB).

     When working converting a series of TIFF files, only the first
     image in each is read.

tiffSeries
     The "Numbered Series" option in the "Convert" menu
     allows you to combine multiple TIFF files into one Priism
     dataset.   To select the form of the input file names use
     the "Name format" menu.  That menu has three options for
     predefined file name formats and a fourth that allows
     for a custom format.  For all of the predefined formats,
     the file names will start with the contents of the
     "Directory" field, followed by a slash, followed by
     the contents of the "Prefix" field.  The remainder of
     the file name depends on which predefined format you
     select:

     prefix_z#_t#.tif
         After the prefix, the file name will have _z appended
         followed by the z section number written out, in
         decimal, with as many digits as needed for the
         largest z section number (if the section number
         has fewer digits than the largest z section number,
         leading zeros will be inserted).  That will be
         followed by _t and then the time point number written
         out, in decimal, with as many digits as needed for
         the largest time point number (if the time point
         number has fewer digits than the largest time point
         number, leading zeros will be inserted).  The file
         name will end with a .tif extension.  This option
         is equivalent to using the custom file template,
         %d/%p_z%az_t%at.tif.

     prefix_z#.tif
         After the prefix, the file name will have _z appended
         followed by the z section number written out, in
         decimal, with as many digits as needed for the
         largest z section number (if the section number
         has fewer digits than the largest z section number,
         leading zeros will be inserted).  The file name will
         end with a .tif extension.  This option is equivalent
         to using the custom file name template, %d/%p_z%az.tif.

     prefix_t#.tif
         After the prefix, the file name will have _t appended
         followed by the time point number written out, in
         decimal, with as many  digits as needed for the
         largest time point number (if the time point number
         has fewer digits than the largest time point number,
         leading zeros will be inserted).  The file name will
         end with a .tif extension.  This option is equivalent
         to using the custom file name template, %d/%p_t%at.tif.

     If you select the "custom template" option from the
     "Name format" menu, the input file names will be
     generated from the contents of the "Template" field.
     When generating file names, special conversion codes
     are expanded in the template.  The conversion codes
     have the following general form:  %[width]code.  The
     recognized codes are:

     %
         Causes a percent sign to be inserted in the
         file name.

     d
         This conversion code is replaced with the contents
         of the "Directory" field.

     p
         This conversion code is replaced with the contents
         of the "Prefix" field.

     z
         This conversion code is replaced with the z section
         number.

     t
         This conversion code is replaced with the time point
         number.

     width is optional and may be used with the z and t
     codes to specify the minimum number of digits which
     are used to display the index value.  width may be
     a positive integer indicating the minimum number of
     digits to use or the letter a to indicate that the
     minimum number of digits should be the number of
     digits in the maximum corresponding index.  If an
     index would have less than the minimum number of
     digits, leading zeros are added to fill in
     the missing portion.

     As an example of a custom template, if you wanted to
     combine f0001.tif through f1000.tif from the directory
     /var/tmp as time points in a single MRC file.  You
     would select "custom template" from the "Name format"
     menu, enter /var/tmp in the "Directory" field, make
     sure the "Prefix" field was empty, enter %d/f%4t.tif
     in the "Template" field, set the range of z indices to
     start at zero and end at zero with a step of one, and
     set the range of time points to start at one and end
     at one thousand with a step of one.

     The "Z Start/End/Step" and "T Start/End/Step" fields
     set the range of z and time point indices, respectively,
     to use when generating file names.  The first value in
     each field is the starting value, s, to use; the second
     value is the last possible value, e, to use; and the
     third value is the increment, i. The indices used will
     be s, s + i, ..., s + n * i.  If i is greater than zero,
     n is the largest integer such that s + n * i is less
     than or equal to e.  If i is less than zero, n is the
     largest integer such that s + n * i is greater than
     or equal to e.  s and e must be greater than or equal
     to zero. i must not be equal to zero.

palette
     For pseudocolor TIFF files, which have a color table
     (palette) that maps the image values to full color RGB,
     the conversion can use the color table and create an
     output file with three waves (the "as RGB" option), or
     the color table can be ignored and the raw image values
     will be stored in a single wave (the "as Grayscale" or
     "as Inverted Grayscale" options).  The former gives better
     results when the image in the TIFF file was derived from a
     full color image.  The latter is better if you are
     interested in data values from an originally single color
     image which has had a color table applied for visualization
     purposes.

     For images without a color table (full-color RGB or
     grayscales), this setting has no effect.  When an image
     with a color table is converted, messages to that effect
     will be written in the log.

log
     Errors that cause the conversion to fail will cause a
     dialog to appear telling generally in what stage of the
     process the error occurred.  For more information about
     why the conversion failed or possible non-fatal problems
     with the conversion, the "View Log" button in the dialog
     can be used to display the messages generated.  Messages
     that start with tiff2mrc are generated by the application
     itself; other messages are from the underlying conversion
     library.

CommandLine
     The command line syntax for tiff2mrc is

         tiff2mrc options output_file_name

     options may be one or more of the following; you must
     specify either the -in or -template options to indicate
     which input file or files to use.

     -dir=name
         Sets the name of the directory to use in the input
         file name template.  The -in or -template options
         control whether or not a file name template is used
         to generate the input file names.  If you do not
         specify the directory, tiff2mrc will use an empty
         string.

     -in=name or -in=name_format
         The first form selects a single input file to convert.
         The second form selects one or more files whose names
         correspond to a predefined template.  If you have
         multiple files that do not correspond to one of
         the predefined templates, you should use the -template
         option which has precedence over the -in option.
         The allowed values for name_format are:

         prefix+zt
             Causes tiff2mrc to generate output file names
             as if "prefix_z#_t#.tif" had been selected for
             the name format in the user interface.

         prefix+z
             Causes tiff2mrc to generate output file names
             as if "prefix_z#.tif" had been selected for
             the name format in the user interface.

         prefix+t
             Causes tiff2mrc to generate output file names
             as if "prefix_t#.tif" had been selected for
             the name format in the user interface.

     -multi=option
         If you use -in to specify a single input file, use
         this option to control what is done if that file
         contains multiple images.  option may be one of
         the following:

         first
             Use only the first image in the file.  This
             is the default.

         z
             Treat each image as a separate z section.

         t
             Treat each image as a separate time point.

         w
             Treat each image as a separate wavelength.

     -palette=conversion
         Specifies how to convert TIFF files which have a
         color table.  conversion  may be one of the
         following:

         rgb
             Create an output file with three wavelengths
             with each wavelength corresponding to one color
             component (red, green, blue).

         gray
             Ignores the color table and creates an output
             with a single wavelength containing data values
             the raw image values from the input.  This is
             the default.

         grey
             Is a synonym for the gray option.

         inverted
             Ignores the color table and creates an output
             with a single wavelength containing the
             contrast-reversed raw image values.

     -prefix=pref
         Sets the prefix to use in the input file name template.
         If you do not specify the prefix, tiff2mrc will use
         an empty string.

     -t=start:end[:increment]
         Sets the range of time point numbers to use when
         generating multiple input file names.  If you omit
         the increment, tiff2mrc will use an increment of
         one if end is greater than or equal to start and
         use an increment of negative one if end is less
         than start.  If you do not set a time point range,
         tiff2mrc will assume a range which starts at zero,
         ends at zero, and has an increment of one.

     -template=custom_template
         Sets the file name template tiff2mrc will use when
         generating input file names.  If you specify this
         option, it will take precedence over a -in option.

     -z=start:end[:increment]
         Sets the range of z indices to use when generating
         multiple input file names.  If you omit the
         increment, tiff2mrc will use an increment of one
         if end is greater than or equal to start and use
         an increment of negative one if end is less than
         start.  If you do not set a z range, tiff2mrc will
         assume a range which starts at zero, ends at zero,
         and has an increment of one.

     This example creates the file fish.dat in the current
     directory which contains, as time points, the images
     from f0001.tif through f1000.tif in /var/tmp:

         tiff2mrc -template=/var/tmp/f%4t.tif -t=1:1000 fish.dat

     This example extracts all the images from exp1.tif and saves
     them as z sections in the MRC file exp1.mrc:

         tiff2mrc -in=exp1.tif -multi=z exp1.mrc