makepyramid
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
This option sets the quality for JPEG compression (0-100) or for
ZIP compression (1-9) when writing compressed TIFF files, or
enables ZIP compression with the given quality level when writ-
ing to an HDF file. 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 compression is not avail-
able with 16-bit data. ZIP compression when writing HDF files
is also controlled by an environment variable, IMOD_HDF_COMPRES-
SION. An entry here overrides the value set by that variable,
and an entry of 0 can be used to disable compression.
-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
To make a pyramid in a single HDF file with ZIP compression,
makepyramid -hdf -qual 5 bigfile.mrc
and it opens with:
3dmod bigfile-pyr.hdf
The header of each volume in the HDF file can be printed with the -vol-
ume option and the volume number, e.g.,
header -vol 2 bigfile-pyr.hdf
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 5.2.0 makepyramid(1)