The vseries command displays an ordered sequence of volume data sets. It is the command-line implementation of Volume Series. The vseries command can also be used to process and save the data. See also: vop morph, volume, movie-related commands
The command vseries open indicates reading the volume series from one or more files specified by filename (including path/location). The wildcard * can be used to specify multiple files. If filename includes spaces, it should be enclosed in quotes. The members of a series are indexed 0, 1, 2, ... and these indices are referred to as the time. Any numbers in the individual filenames are not used.
Playback is controlled with vseries play, and continuous looping halted with vseries stop. The volume-spec is the model number of any member of the series. The close function simply removes the specified series, whereas save allows saving the series as a single file in Chimera map format (HDF5-based), optionally with processing such as cropping, normalization, and alignment.
Examples:
vseries open myseries*.mrc
vseries close #0
vseries open ~/Desktop/myseries.cmap
vseries play #0 loop true
vseries stop #0
vseries save #0 ~/Desktop/test.cmap subregion 100,0,0,200,511,150 threshold 140 valueType uint8
Option keywords for vseries can be truncated to unique strings and their case does not matter. A vertical bar “|” designates mutually exclusive options, and default values are indicated with bold. Synonyms for true: True, 1. Synonyms for false: False, 0.
jumpTo time
Go directly to the specified time.
direction mode
Specify the playback mode:
loop true | false
Whether to loop playback continuously until it is halted with vseries stop.
maxFrameRate rate
Specify a maximum playback rate in steps per second. By default, playback is as fast as possible, which can be fairly slow for large data. This option is used to slow playback when it is too fast.
normalize true | false
Whether to adjust the thresholds (contour levels) to keep the enclosed volume constant throughout the series. This is useful when the signal level in the data changes over time or between states.
showMarkers true | false
Whether to display markers previously created with Volume Tracer to trace spatial and temporal paths. Each marker is labeled with the time of the data set on which it was placed. The labels are not shown. They are used by vseries to display only the markers for the currently displayed time. Markers for specified numbers of earlier and later time points can also be shown using the precedingMarkerFrames and followingMarkerFrames options, respectively.
precedingMarkerFrames N
When showing markers, for how many earlier time points (default 0) the markers should also be shown.
followingMarkerFrames M
When showing markers, for how many later time points (default 0) the markers should also be shown.
colorRange cutoff
Whether to color volume contour surfaces to match markers within a specified distance cutoff (regardless of whether the markers are shown). All of the markers associated with the current time are used to color the current surface. The coloring does not apply to solid displays.
cacheFrames K
Whether to store volume rendering (surface triangle or solid voxel) information for the K most recent displays (default 1). This can speed playback because less time is spent recalculating display information. There is no hard limit to the memory used to cache rendering information. Surface renderings use memory proportional to the number of triangles composing the surface. Solid renderings use memory proportional to the number of data voxels displayed, and it is generally only feasible to cache solid display information for small data sets.
Alternatively, alignment can be specified with the align option of vseries save.
encloseVolume volume
Before aligning each map, set the threshold (contour level) to enclose the specified volume in distance units cubed (e.g., Å3 if the grid spacing is expressed in Å). The contour level affects alignment because only values above the contour level are used. The level is determined by an iterative procedure (details...). The fastEncloseVolume option is similar but uses a noniterative approximation.
fastEncloseVolume volume
Before aligning each map, set the threshold (contour level) to enclose the specified volume in distance units cubed. The contour level affects alignment because only values above the contour level are used. A fast method is used to estimate the level (details...). The encloseVolume option is similar but uses an iterative procedure with increased accuracy at the cost of increased computation time.
The options are listed in order of application when used together.
subregion i1,j1,k1,i2,j2,k2
Instead of saving the full dimensions, save the subregion delimited by grid indices i1–i2 along the X axis, j1–j2 along the Y axis, and k1–k2 along the Z axis.
valueType value-type
Change grid value type before any processing with other save options. The related option finalValueType sets the value type after any processing. The value-type can be:
- int8 - 8-bit signed integer
- int16 - 16-bit signed integer
- int32 - 32-bit signed integer
- uint8 - 8-bit unsigned integer
- uint16 - 16-bit unsigned integer
- uint32 - 32-bit unsigned integer
- float32 - 32-bit floating-point
- float64 - 64-bit floating-point
threshold minimum
Replace all values below the specified mininum with zero. If this option is used, the output will be compressed.
zeroMean true | false
Subtract the mean from each value so that the new mean will be zero.
scaleFactor f
Scale values by a multiplicative factor f.
[ encloseVolume volume | fastEncloseVolume volume ]
Set the contour level of each map to enclose a specified volume in distance units cubed. Either of two methods can be used, as described above. The contour level affects alignment because only values above the contour level are used.
normalizeLevel value
Scale map values so that the current threshold (contour level) equals the specified value.
align true | false
Align the maps before saving them. Only values above the contour level are used for alignment; contour levels can be set to enclose a specified volume.
onGrid gridmap
Create the new map on the grid of another, where gridmap is a model number preceded by #. This allows using a consistent grid for maps after alignment.
mask maskmap
Mask by maskmap (multiply by the 0,1 values within that map). The maskmap must be on the same grid and have the same dimensions as the series maps.
finalValueType value-type
Set grid value type after any processing with other save options. Possible types are as listed for the related option valueType, which sets the value type before processing.
compress true | false
Compress the output file (Chimera map format).