makepyramid(1)              General Commands Manual             makepyramid(1)



NAME
       makepyramid - Create an image pyramid for rapid viewing in 3dmod

SYNOPSIS
       makepyramid  [options]  input_file


DESCRIPTION
       Makepyramid will make an "image pyramid", a set of files representing
       the same volume at a series of resolutions.  Images are also converted
       to a tiled format so that subareas of large images can be read in
       quickly.  When 3dmod is run with the pyramid, any part of the vol-
       ume, at any scale, can be viewed relatively rapidly without have to
       load the entire volume at full resolution into memory.  An image list
       file is created so that the pyramid can be opened by just starting
       3dmod with this filename; also, all files can be placed into a sub-
       directory and 3dmod can be started with just the directory name.
       Output volumes can be either MRC or TIFF files; compression is avail-
       able with the latter.

       The reduction factors applied to the original image are constrained to
       be integers, but by default, the reduction is not done with simple bin-
       ning here.  Images are first reduced in X and Y by Newstack using
       antialias filtering, which is important when images are noisy or reduc-
       tions are large.  They are then reduced in Z by Binvol, also with
       antialias filtering.

       There are default values for the reductions.  The default reduction
       will produce reduced data whose sum is no more than 0.15 as big as the
       original volume.  Here are some considerations if you want to set your
       own values.  A common practice is to make a pyramid with reductions
       that are successive powers of 2, at least in X and Y.  This is essen-
       tially the default and would correspond to an entry of 2,4,8,... to the
       -reductions option.  If you have a giant area, you may find that larger
       steps are sufficient in X and Y, e.g., 2,5,10,...  The reduction in Z
       does not have to match that in X and Y.  Since 3dmod still displays
       every original Z value when zoomed down and interpolates between the
       ones in the file being accessed at that zoom, the default reduction in
       Z is just 2,3,4...  If you do set your own reductions, you may still
       want to reduce less in Z than in X and Y, e.g., "-zreductions 2,3,5".

       For the most rapid viewing of the whole area at low zoom, the last vol-
       ume should be smaller than 4 megapixels (2K x 2K for a square area),
       preferably around 2 megapixels (1400 x 1400).  The default reduction
       accomplishes this as well.

       Images are converted to a tiled form, either a montaged MRC file or a
       TIFF file with storage in tiles, so that subareas can be loaded rapidly
       from the file.  When a file is not organized in tiles and a subarea in
       X is read from the file, the system will typically need to read the
       whole line to access the subarea.  Thus there is substantial benefit in
       converting the full-resolution input file to tiles, especially if the
       size in X is much bigger than 4K, although the -use option allows you
       to skip this conversion.  If storage space is a concern and you do not
       anticipate needing to access the input file in its unmontaged form, it
       should be safe to delete it provided that you created a montaged MRC
       file from it.  It can be recreated from the montage with a command like
          reducemont -nofft -plin rootname-1xy-1z.pl -plout dummy.pl \
             rootname-1xy-1z.mrc full-size-file.mrc


OPTIONS
       Makepyramid uses the PIP package for input (see the manual page for
       pip).  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 (-i) OR -InputFile      File name
              Input image file to make pyramid from.  If this option is not
              entered, the first nonoption argument is taken as the input
              file.  Either way, the input file is a required entry.

       -rootname (-ro) OR -RootOutputName       Text string
              Root name for output files.  If you use the "-subdir" option,
              this will also be the basis of the name of the directory in
              which files are placed.  The default is the root of the input
              file name.

       -reductions (-re) OR -ReductionsInSize   Multiple integers
              Comma-separated list of reduction factors to apply in X and Y,
              such as 2,4,8.  The default is a series of powers of 2, with a
              final factor that comes closest to reducing the image to 2
              megapixels.  The final factor may substitute for the last power
              of two if it is close enough.

       -zreductions (-zr) OR -ReductionsInZ     Multiple integers
              List of reduction factors to apply in Z.  If this option is
              entered, there must be the same number of factors as entered
              with -reductions.  The default is a series of values increasing
              by 1 for each volume.

       -subdir (-s) OR -FilesIntoSubdirectory
              Place files in a subdirectory, which will be named as the root
              name of the output files with "-pyr" appended.  3dmod can
              open the files if given either the name of the image list file
              inside the subdirectory or the name of the directory itself.  If
              the input file is used as is, the program will attempt to move
              it into the subdirectory.

       -tiff (-tif) OR -TiffOutputFiles
              Output tiled TIFF files with Mrc2tif and the -T option.  The
              default is to output a montaged MRC stack and piece list file
              with Reducemont.

       -hdf (-hd) OR -HDFOutputFile
              Output a multi-volume HDF file instead of montaged MRC files or
              tiled TIFF files.  The file will be named rootname-pyr.hdf and
              can be opened directly as a pyramid in 3dmod with no options.
              This option cannot be used with -tiff, -use, or -subdir.

       -compress (-c) OR -TiffCompressionType   Text string
              Apply the given compression to TIFF files.  The allowed entries
              are the same as for Mrc2tif: "lzw", "zip", "jpeg", or numbers
              defined in the libtiff library (these are listed in
              /usr/include/tiff.h on some Linux systems).  See the "-c" option
              of Mrc2tif for details.  If an invalid number is given, an
              error will not occur until Mrc2tif is run.

       -quality (-q) OR -CompressionQuality     Integer
              Quality for JPEG compression (0-100) or for ZIP compression
              (1-9) when writing compressed TIFF files.  See the "-q" option
              of Mrc2tif for details.  ZIP compression can give significant
              size reduction for 16-bit data that do not fill the 16-bit
              range, but usually has little value for byte data.  JPEG com-
              pression is not available with 16-bit data.

       -use OR -UseInputFileAsIs
              Use the input file as it is instead of making a tiled file from
              it.  You would do this if you want to avoid the storage require-
              ments of having two copies of the input file.  Access to subar-
              eas of this image will be slower because whole strips have to be
              loaded, instead of just tiles covering the desired area.

       -xyanti (-x) OR -AntialiasTypeInXandY    Integer
              Type of antialias filter to apply by shrinking the image in X
              and Y with Newstack.  The filters are:
                  2: Blackman - fast but not as good at antialiasing as slower
                                filters
                  3: Triangle - fast but smooths more than Blackman
                  4: Mitchell - good at antialiasing, smooths a bit
                  5: Lanczos 2 lobes - good at antialiasing, less smoothing
                                than Mitchell
                  6: Lanczos 3 lobes - slower, even less smoothing but more
                                risk of ringing
               The default here is 6.  Enter 0 or 1 to use ordinary binning in
              Binvol instead.

       -zanti (-za) OR -AntialiasTypeInZ   Integer
              Type of antialias filter to apply when reducing in Z with Bin-
              vol(1).  The filters are as above, 0 or 1 give ordinary binning,
              and the default is 6.  With antialias filtering, the "-spread"
              option to Binvol will be used to get first and last slices as
              close to the ends of the data set as possible.

       -tile (-til) OR -TileSizeInXandY    Two integers
              Approximate size of tiles to create in X and Y.  This entry is
              treated as a maximum size by Reducemont, whereas Mrc2tif
              will adjust the tile size to be above or below this to minimize
              wasted storage space.  The default is 1024,1024.

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

       -StandardInput
              Read parameter entries from standard input


EXAMPLES
       Until you have some reason to do something different, you can ignore
       most of those options and proceed with very simple commands.  To make a
       pyramid in the current directory from the file "bigfile.mrc", with a
       tiled copy of bigfile.mrc:
           makepyramid bigfile.mrc
       The files can now be opened with
           3dmod bigfile.imlist

       To make such a pyramid in a subdirectory:
           makepyramid -sub bigfile.mrc
       which can be opened with:
           3dmod bigfile-pyr

       To make a pyramid in the current directory that uses the existing copy
       of bigfile.mrc (faster to make, less storage, slower to load):
           makepyramid -use bigfile.mrc
       and again it opens with:
           3dmod bigfile.imlist

       To make a pyramid of TIFF files with JPEG compression in a subdirec-
       tory:
           makepyramid -sub -tif -com jpeg bigfile.mrc
       and again it opens with:
           3dmod bigfile-pyr

FILES
       Image and piece list files are named as "rootname-#xy-#z...", where the
       first "#" is the reduction in X and Y and the second "#" is the reduc-
       tion in Z.  The extension is ".mrc" for MRC files, ".tif" for TIFF
       files, and ".pl" for piece list files.  The image list file is named as
       rootname.imlist.  An existing copy of the output image and piece list
       files will be made into a backup file by adding the extension ~.  An
       existing copy of the image list file will be replaced.


AUTHOR
       David Mastronarde

BUGS
       Email bug reports to mast at colorado dot edu

SEE ALSO
       3dmod, newstack, binvol, mrc2tif, reducemont

HISTORY
IMOD                                4.10.10                     makepyramid(1)