binvol(1) General Commands Manual binvol(1)NAMEbinvol - Reduce a 3D volume in size isotropically or anisotropicallySYNOPSISbinvol [options] input_file output_fileDESCRIPTIONBinvol 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-antialiasoption. 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.OPTIONSBinvol 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-InputFileFilenameInput image file to bin down in 3D-output(-o)OR-OutputFileFilenameOutput file for binned volume-mode(-mo)OR-ModeToOutputIntegerThe 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-BinningFactorFloatingpointOverall factor to reduce by. Antialiasing must be specified if the value is not an integer. The default is 2.-xbinning(-x)OR-XBinningFactorFloatingpointFactor 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-YBinningFactorFloatingpointFactor 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-ZBinningFactorFloatingpointFactor 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-AntialiasZFilterIntegerThe 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-shrinkoption 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-SpreadSlicesInZOutput 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-FourierReduceByBinningUse 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-FourierExpandByBinningUse 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-ShiftsInXYZThreefloatsShifts 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-MemoryLimitIntegerMaximum 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-VerboseOutputIntegerOutput debugging information: 1 for basic, 2 for output per slice-help(-h)OR-usagePrint help output-StandardInputRead parameter entries from standard input.HISTORYWritten 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/23BUGSEmail bug reports to mast at colorado dot edu. IMOD 4.12.61 binvol(1)