Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells
NEWSTACK(1) NEWSTACK(1)
NAME
newstack - Make a new mrc image stack.
SYNOPSIS
newstack [options] <input file(s)> <output file>
DESCRIPTION
Newstack is a general stack editor to move images into, out of, or between
stacks. It can float the images to a common range or mean of density. It
can bin images and apply a general linear transformations as well as a
specified rotation or expansion. It can put the output into a smaller or
larger array and independently recenter each image separately from the
transformation. Images can be taken from multiple input files and placed
into multiple output files.
Newstack uses the PIP package for input (see the manual page for pip)
and can take input interactively only for options available before
conversion to PIP, to maintain compatibility with old command files. The
options accepted by the old newst script are all accepted by newstack.
Almost all options can be abbreviated to one or two letters. The following
options can be specified either as command line arguments (with the -) or
one per line in a command file or parameter file (without the -):
-input OR -InputFile File name
Input image file. Input files may also be entered after all arguments on
the command line, as long as an output file is the last name on the
command line. Files entered with this option will be processed before
files at the end of the command line, if any.
(Successive entries accumulate)
-output OR -OutputFile File name
Output image file. The last filename on the command line will also be
treated as an output file, following any specified by this option.
(Successive entries accumulate)
-fileinlist OR -FileOfInputs File name
Name of file with list of input files and sections to read. The format of
the file is the number of input files on the first line, the first file to
read on the next line, the list of sections to read on next line, next
filename on next line, etc. If this option is used, no input filenames
may be specified with the -input option or following options on the
command line.
-fileoutlist OR -FileOfOutputs File name
Name of file with list of output files and number of sections to place in
each. The format of the file is the number of output files on the first
line, the first file to write on the next line, number of sections to
write on next line, next filename on next line, etc. If this option is
used, no output filenames may be specified with the -output option or as
the last file on the command line.
-secs OR -SectionsToRead List of integer ranges
List of sections to read from an input file, numbered from 0. Ranges may
be entered (e.g., 1-3,5,8), and / may be used to specify all sections in
the file. If multiple lists are entered, each one will be applied to the
respective input file. If no list is entered for a file, all sections
will be read.
(Successive entries accumulate)
-skip OR -SkipSectionIncrement Integer
Increment for reading a regularly spaced subset of the sections in the
list from the input file. Enter 2 to take every other section, 3 to take
every third section, etc. Note that the increment is used to select from
the input list, not from all the sections in the file.
-numout OR -NumberToOutput Multiple integers
Number of sections to write to each output file, when there are multiple
output files. These numbers may be listed in sequence in one entry, or in
several entries.
(Successive entries accumulate)
-blank OR -BlankOutput
Output blank sections for nonexistent section numbers in input file,
namely for section numbers less than 0 or more than the NZ - 1. The
sections are filled with the mean value of the input file or with a fill
value if one is entered with the -fill option; this value is then scaled
in the same way that actual data are.
-size OR -SizeToOutputInXandY Two integers
The dimensions of the output image in X and Y. The default size is the
same as that of the first input file.
-mode OR -ModeToOutput Integer
The storage mode of the output file; 0 for byte, 1 for 16-bit integer, or
2 for 32-bit floating point. The default is the mode of the first input
file.
-offset OR -OffsetsInXandY Multiple floats
X and Y center offsets for each section. This is an offset to the center
of the area from which image will be taken, so a positive offset in X will
move images to the left. Enter one X,Y pair to apply a single offset to
all sections.
(Successive entries accumulate)
-applyfirst OR -ApplyOffsetsFirst
Apply offsets in X and Y before transforming image, which will make a
rotated image come from a predictable location. The default is to apply
offsets after, which shifts the transformed image instead.
-xform OR -TransformFile File name
File with one or more linear transformations to apply to images
-uselines OR -UseTransformLines List of integer ranges
A list of the line numbers of lines of transforms to use in the transform
file (numbered from 0). Ranges are allowed. The default is for the line
numbers to match the input section numbers. To have a single transform
applied to all of the sections, just enter a single number.
(Successive entries accumulate)
-onexform OR -OneTransformPerFile
Apply one transform line for each input file. The default is for the
first transform to be applied to the first file, the second transform to
the second file, etc., in which case the transform file must have at least
one line per input file. Otherwise, -uselines can be used to specify
which transform to apply for each file, in which case at least one line
must be specified per input file.
-rotate OR -RotateByAngle Floating point
Rotate all images by the given angle in degrees, positive for a
counterclockwise rotation. Rotation is applied after binning and
transformation, if any. If the rotation is by +90 or -90 degrees and no
output size is specified, then the X and Y sizes of the image will be
transposed so the the output file will show the whole rotated image. For
any other rotation angles, you will get the same output size as the input
image unless you enter a new size explicitly.
-expand OR -ExpandByFactor Floating point
Scale all images in size by the given factor, greater than 1 to expand, or
less than 1 to shrink. Scaling is applied after binning and
transformation, if any. If no output size is specified, the size of the
input image will be scaled appropriately so that the output will contain
the entire image.
-bin OR -BinByFactor Integer
Use binning to reduce images in size by the given factor. Binning is
applied before all other image transformations. If no output size is
specified, the size of the input image will be scaled appropriately so
that the output will contain the entire image.
-origin OR -AdjustOrigin
Adjust the origin values in the image file header for changes in image
size or the centering of a subarea. With this adjustment, a model built
on the input stack should be correctly located when loaded onto the output
stack in 3dmod. Model points will be correctly located in Z provided
that a contiguous set of sections is output. They will be correct in X
and Y provided that the only operations on the data are a change in size
of the output, binning with -bin, scaling with -expand, and shifting with
-offset.
-linear OR -LinearInterpolation
Use linear instead of cubic interpolation to transform images. Linear
interpolation is more suitable when images are very noisy, but cubic
interpolation will preserve fine detail better when noise is not an issue.
Images are transformed when the -xform, -expand, -rotate, -distort, or
-gradient option is entered.
-float OR -FloatDensities Integer
Adjust densities of sections individually. Enter 1 for each section to
fill the data range, 2 to scale sections to common mean and standard
deviation, 3 to shift sections to a common mean without scaling, or 4 to
shift sections to a common mean then rescale the minimum and maximum
densities to the Min and Max values specified with the -scale option.
-contrast OR -ContrastBlackWhite Two integers
Rescale densities to match the contrast seen in 3dmod with the given
black and white values. This works properly only when the output file
will be bytes. It will not work if the data were loaded into 3dmod with
intensity scaling; use mrcbyte in that case.
-scale OR -ScaleMinAndMax Two floats
Rescale the densities of all sections by the same factors so that the
original minimum and maximum density will be mapped to the Min and Max
values that are entered.
-fill OR -FillValue Floating point
Value to fill areas of the output image that have no image data. The
filling is done before intensity scaling, so the value in the filled areas
will be modified by any scaling that is done.
-multadd OR -MultiplyAndAdd Two floats
Rescale the densities of all sections by multiplying by the first entered
value then adding the second value. This option must be entered either
once only, or once per input file.
(Successive entries accumulate)
-distort OR -DistortionField File name
Image distortion field file to use for undistorting images. The
undistortion is applied before any transformations.
-imagebinned OR -ImagesAreBinned Integer
The current binning of the images, so that the distortion field can be
applied correctly. This entry is required unless the program can
determine the binning unambiguously from the image size.
-fields OR -UseFields List of integer ranges
A list of the distortion fields to apply for each section (numbered from
0). Ranges are allowed. The default is for the field numbers to match
the input section numbers, unless there is only one field in the file. To
have a single field applied to all of the sections, just enter a single
number.
(Successive entries accumulate)
-gradient OR -GradientFile File name
File with magnification gradients to be applied for each image. This
should be a file listing the tilt angle, the percent magnification change
per micron of Z height, and the degrees of rotation per micron of Z height
for each image, such as is produced by Extractmaggrad. The mag gradient
correction is applied before a distortion field correction and before any
transformations.
-test OR -TestLimits Two integers
To test the code for reading in and binning images in chunks, enter limits
for the total size of the working array, and for the size of the array
used for binning.
-param OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter file.
-help OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
If no command line arguments are entered, inputs are prompted interactively.
The input is as follows; lines starting with IF are entered only if a
particular option is selected.
Number of input files, or -1 to enter list of files from a file
IF you enter a number >0, then for each input file, enter two lines:
File name
list of section numbers to take from that file. The first section is
numbered 0 and ranges may be entered (e.g. 0-4,5,7-9)
OTHERWISE, IF you enter -1, then enter the name of the file with list of
files and sections. The format of this file should be
Number of input files
File name
list of section numbers (first is 0!!!), ranges allowed (e.g. 0-3,5,7-9)
next file and list of sections, etc.
Number of output files, or -1 to enter list of files from a file
IF you enter 1, next enter the name of the single output file.
OR IF you enter a number >1, then for each output file, enter two lines:
File name
Number of sections to put in that file
OR IF you enter -1, then enter the name of the file with the list of files
and numbers of of sections. The format of this file is:
Number of output files
File name
number of sections to place in that file
next file and number of sections, etc.
The X and Y dimensions of the output file, or / to take the same
dimensions as the first input file
The data mode of the output file, or / to take the same mode as the first
input file. Mode can be 0 for bytes, 1 for 16-bit integers, 2 for
32-bit real numbers, or 9 to 15 for 9 to 15 bit values.
0 for no offsets, or 1 to apply X and Y offsets separately to each section,
or -1 to apply the same X and Y offset to all sections
IF offsets are selected, next specify the X and Y center offsets of
each of the sections (they need not be on separate lines), or the single
offset to apply to all sections.
Hint: offsets of 50,50 will take the center of the output image
from the upper right quadrant of the input image.
0 for no transforms, or 1 to transform images using cubic interpolation, or
2 to transform using bilinear interpolation
IF transforming is selected, next specify the file for transforms, and
on a separate line, a list of lines to use in the file (first is 0!!!).
Ranges are allowed here, but all must be on one line. To have a single
transform applied to all of the sections, just enter a single number.
0 for no floating of densities, 1 to float densities so that each section
occupies the same RANGE of densities (the optimum range for the
particular data mode), 2 to float so that all sections have the same
MEAN and STANDARD DEVIATION of density (which requires the input
sections to be read twice), -1 to specify a single scaling that will
be applied equally to all sections, -2 to scale all sections by the
same amount, determined by black and white contrast settings, in order
to convert to bytes with stretched contrast, 3 to SHIFT sections to
the same mean value without rescaling, or 4 to SHIFT sections to the
same mean then rescale all sections by the same specified scaling.
IF single rescaling is selected with "-1", next specify the density values
to which the minimum and maximum in the data file should be mapped, or
just enter "/" to have them mapped to the full-scale range for the
data mode, or enter "1,1" to override any scaling of data that would
otherwise occur because of a change of mode. This scaling method can
be used to invert densities by entering, e.g., 255,0.
IF scaling by black and white contrast settings is selected with -2, next
enter the black and white settings (see mrcbyte).
OR, IF shifting and rescaling was selected with "4", next specify the
density values to which the new, shifted minimum and maximum values
should be mapped, or just enter "/" to have them mapped to the full-
scale range for the data mode.
ADDITIONAL NOTES
The program will adjust the pixel spacing in the header of the output file
if binning and/or the expansion option are used. Models built on the input
file in 3dmod should display correctly on a file scaled by these two
options. However, the image origin is not adjusted for images that are a
subset of the input image, so it would be necessary to shift a model
manually in 3dmod to display it on a subset.
When there is a change of modes, data are rescaled optimally in most
cases. If floating is not selected, the scaling is by an amount that would
map the range for the input data mode into the range for the output data
mode (e.g., going from mode 1 to mode 2, it would scale data up by a factor
of 128). Generally, all sections will be rescaled by the same amount, thus
preserving relative differences between sections. However, if the output
mode is 2 (reals), this kind of rescaling will not occur. In general, if
your input mode is real and you are outputing to bytes or integers, you need
to specify some kind of floating, shifting, or scaling in order to get
usable values. These same kinds of automatic scalings upon change of mode
will occur with shifting to a common mean (option 3), but here the program
is more careful to apply the same scaling to all sections. To disable the
scaling upon change of mode, the use the option "-scale 1,1," or the "-1"
floating option with interactive input.
At the end, the program will report how many pixels have been truncated at
the low or high limits of the output range. If this happens after shifting
with a specified output range, try again with a slightly smaller range.
Complex data (Fourier transforms) can be stacked but not otherwise
manipulated. Don't try to change the size or center of the FFT's.
Newstack will not work with color data (MRC data mode 16). If your images
came from color Tiff files and you do not need the color information, use
the "-g" option when converting them with Tif2mrc. If you do need to
preserve the color information, then you can split the color channels into
three byte-mode files with "clip splitrgb", use Newstack to perform
identical operations on each of the three files, and recombine the data into
a color file with "clip joinrgb".
The program operates on very large images by reading, operating on, and
writing strips of the image if necessary. Images can be larger than 10K by
10K if they are not being rotated much, but when images are rotated by large
angles (30-90 degrees), input image size may be limited to 8K by 8K.
Each linear transformation in a transform file is specified by a line with
six numbers:
A11 A12 A21 A22 DX DY
where the coordinate (X, Y) is transformed to (X', Y') by:
X' = A11 * X + A12 * Y + DX
Y' = A21 * X + A22 * Y + DY
HISTORY
DNM (mast) for VAX 8/88
5/4/89 changed to float to same mean and sd rather than mean and min.
12/19/89 added full control of density scaling; fixed bug in
interpolation that was generating half-pixel error half the time.
4/19/90 added line-by-line prompts for file and section entry and
added time/date stamp
1/23/91: fixed so that it can correctly pad images and extract
subsets of images with either center-shifting or transforms
6/11/91: fixed bug if trying to output scaled real values les than 0
Feb 94 : Ported to SGI by Paul Furcinitti.
Jul 94 : PSF (Furcinitti) Fixed bug when writing byte files.
11/16/94: DNM added shifting to mean, rationalized scaling somewhat
9/24/01: changed to read and write in chunks if images are big
12/24/03: converted to PIP input, added undistorting and binning
SEE ALSO
mrcbyte(1), tif2mrc, clip