binvol(1) General Commands Manual binvol(1)
NAME
binvol - Reduce a 3D volume in size isotropically or anisotropically
SYNOPSIS
binvol [options] input_file output_file
DESCRIPTION
Binvol can reduce a volume in all three dimensions, with the reduction
done isotropically or by different amounts in X, Y, and Z, and can also
expand volumes. The default is now to use antialiased image reduction
instead of binning in Z, as well as in X and Y when the reduction is
equal in X and Y. In these cases, reduction factors need not be inte-
gers. The previous default of binning can be used by entering 0 for
the -antialias option. Binning means summing (actually averaging) all
of the values in a block of voxels (e.g., 2x2x2 or 1x1x3) in the input
volume to create one voxel in the output volume, so it can be done only
by an integer amount in each dimension, but X and Y can have different
binnings. It is also possible to do reduction by taking the 3-D
Fourier transform and cropping it, which gives perfect antialiasing but
requires more memory and may introduce ringing near the edges. In
addition, a volume can be expanded by padding the 3-D FFT. Both of
these operations require equal scaling in X and Y. The output file
from reduction or expansion will have appropriately larger or smaller
pixel spacings in its header.
OPTIONS
Binvol uses the PIP package for input (see the manual page for pip).
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 (-i) OR -InputFile File name
Input image file to bin down in 3D
-output (-o) OR -OutputFile File name
Output file for binned volume
-mode (-mo) OR -ModeToOutput Integer
The storage mode of the output file; 0 for byte, 1 for 16-bit
signed integer, 6 for 16-bit unsigned integer, 2 for 32-bit
floating point, or 12 for 16-bit floating point. Floating point
would be useful to preserve intensity resolution in the averaged
data, particularly important when applying a large amount of
binning to relatively small byte or integer values. The default
is the mode of the input file, although the default mode of
floating point output for MRC files is governed by the value of
environment variable IMOD_WRITE_FLOATS_16BIT.. Mode 12 is
allowed only if the output format is MRC.
-binning (-b) OR -BinningFactor Floating point
Overall factor to reduce by. Antialiasing must be specified if
the value is not an integer. The default is 2.
-xbinning (-x) OR -XBinningFactor Floating point
Factor to reduce by in X. It must be an integer unless
antialiasing is specified and reductions in X and Y are equal.
The default is to use the overall reduction factor.
-ybinning (-y) OR -YBinningFactor Floating point
Factor to reduce by in Y. It must be an integer unless
antialiasing is specified and reductions in X and Y are equal.
The default is to use the overall reduction factor.
-zbinning (-z) OR -ZBinningFactor Floating point
Factor to reduce by in Z. It must be an integer unless
antialiasing is specified. The default is to use the overall
reduction factor.
-antialias (-a) OR -AntialiasZFilter Integer
The Z dimension will be reduced with antialiased filtering
instead of with binning by default or if a number between 2 and
6 is entered to specify the filter type. If the reduction is
equal in X and Y (and greater than 1), then antialiased reduc-
tion will be applied in those dimensions as well, even if it is
different from the Z reduction. The result will be slightly
shifted from that obtained with the -shrink option to New-
stack(1) if the X or Y dimension is not a multiple of the bin-
ning. The filters are as in Newstack:
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
-1: The default filter, which is Lanczos 3
-spread (-sp) OR -SpreadSlicesInZ
Output slices in Z that sample, or are centered on, Z values as
close to the starting and ending input slices as possible. This
option can be used only when doing antialiased reduction in Z.
By default, the first output slice is centered on the middle of
the first set of slices corresponding to the binning in Z. The
bottom edge of this slice is the same as the bottom edge of the
first input slice and the Z origin is unchanged. The number of
slices is truncated to an integer after division by the reduc-
tion factor. With this option, if the size in Z is not evenly
divisible by the reduction factor, an additional slice is pro-
duced, the centering of the first slice is moved down, and the Z
origin is increased to adjust for this.
-ftreduce (-ftr) OR -FourierReduceByBinning
Use cropping of the 3-D Fourier transform to reduce the volume
by the binning factors entered with other options. This reduc-
tion method provides complete removal of frequencies above the
highest frequency being retained (i.e., antialiasing) with no
attenuation of the retained frequencies, but might produce some
ringing near the edges. The reduction must be equal in X and Y.
Also, the entire input and output volumes (plus some padding)
must fit in the allowed memory at 4 bytes per pixel. For inte-
ger reduction factors, the output should be in good register
with that from real-space reduction. Currently, the reduction
factor must be either an integer, or an integer divided by 2, 3,
4, 5, 6, 8, or 10. Thus, 2.7, 1.375, 3.75, 1.333, and 2.167 are
all acceptable factors. Factors that are integers divided by 3
or 6 must be entered with three decimal places, as in the last
two examples. The actual factor applied in those cases will be
a ratio of integers, not the entered number, and be within 0.001
of the entered factor. If the factor is not acceptable, the
program exits with an error.
-ftexpand (-fte) OR -FourierExpandByBinning
Use padding of the 3-D Fourier transform to scale the volume up
by the binning factors entered with other options. This method
will produce a smoother result than 3-D interpolation, e.g.,
with Matchvol. The expansion must be equal in X and Y.
Also, the entire input and output volumes (plus some padding)
must fit in the allowed memory at 4 bytes per pixel. The allowed
factors have the same limitations as described for -ftreduce.
-shifts (-sh) OR -ShiftsInXYZ Three floats
Shifts in X, Y, and Z to apply to the input before Fourier
reduction or expansion, in addition to whatever internal shifts
are applied to make the volume be in register with output from
real-space reductions. This option has been used to determine
those internal shifts.
-memory (-me) OR -MemoryLimit Integer
Maximum size of working array in megabytes. The size of the
array determines whether data are read in and reduced in chunks
or as whole slices, which is more efficient. The default value
is 1000 megabytes if the system physical memory cannot be deter-
mined; otherwise the size is the minimum of 15 GB, 3/4 of physi-
cal memory, and physical memory minus 1 GB, for memory up to 30
GB, and half of physical memory above 30 GB; but in any case at
least 400 MB. The maximum allowed value is 8000 if system mem-
ory is not determined, or 80% of physical memory.
-verbose (-v) OR -VerboseOutput Integer
Output debugging information: 1 for basic, 2 for output per
slice
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
HISTORY
Written by David Mastronarde
Converted to PIP input and added to package, 10/28/04
Implemented non-integer reduction, 4/2/23
Implemented Fourier reduction and expansion, 12/30/23
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.0.2 binvol(1)