Volume Creation from Scratch

Copying Volumes

Another method of creating a volume is to simply copy the entire volume definition from an existing volume:

public  Volume   copy_volume_definition(
    Volume   existing_volume,
    nc_type  nc_data_type,
    BOOLEAN  signed_flag,
    Real     voxel_min,
    Real     voxel_max )
public  Volume   copy_volume_definition_no_alloc(
    Volume   volume,
    nc_type  nc_data_type,
    BOOLEAN  signed_flag,
    Real     voxel_min,
    Real     voxel_max )

Both functions creates and returns a new volume which has the same definition (sizes, voxel-to-world space transform, etc.), as an existing volume. If the argument nc_data_type is not MI_ORIGINAL_TYPE, then the storage type of the new volume differs from the original and is specified by nc_data_type, signed_flag, voxel_min, and voxel_max. In the first function, the voxel values are allocated but not initialized. In the second function, they are not allocated.

public  Volume   copy_volume(
    Volume   volume )

Creates an exact copy of a volume.

Volume Caching

In order to efficiently handle volumes that are too large for virtual memory, a simple caching scheme has been implemented. Disk files are read and written on demand to provide the appearance of having large volumes fully resident in memory. All the volume routines described previously support this feature transparently, but there are a few routines for configuration of the volume caching.

public  void  set_n_bytes_cache_threshold(
    int  threshold )

Sets the threshold number of bytes for volume caching. If a volume larger than this is created, either explicitly or by input from a file, then that volume will be internally represented by the caching scheme. If this function is not called, the default is either 80 megabytes, or the value of the environment variable VOLUME_CACHE_THRESHOLD, if present. A threshold of zero will cause all volumes to be cached. A threshold less than zero will result in no volumes being cached.

typedef  enum  { SLICE_ACCESS, RANDOM_VOLUME_ACCESS }
               Cache_block_size_hints;
public  void  set_cache_block_sizes_hint(
    Cache_block_size_hints  hint )
public  void  set_default_cache_block_sizes(
    int   block_sizes[] )

When a voxel is accessed in a cached volume, the corresponding block containing the voxel is read from or written to the disk as necessary. These two functions control the default size of the blocks and therefore the tradeoff between fast access of adjacent voxels (using large block sizes) and fast access of arbitrarily distributed voxels (using small block sizes). The function set_cache_block_sizes_hint indicates that the default block sizes for volumes created in the future should be computed based on the assumption that the application will be accessing volume voxels mostly in a slice-by-slice manner (SLICE_ACCESS) or in an unpredictable order (RANDOM_VOLUME_ACCESS). The second function, set_default_cache_block_sizes, provides an alternative where the default block sizes are explicitly set. A call to either function overrides any previous call to the other function. If neither of these functions is called, the default value is a block size of 8 voxels per dimension, or the value specified by the environment variable VOLUME_CACHE_BLOCK_SIZE. These functions only affect volumes created afterwards. In order to change the value for a given volume, the following function may be used:

public  void  set_volume_cache_block_sizes(
    Volume    volume,
    int       block_sizes[] )

Sets the size of the cache block for the given volume. Because this function causes the cache to be completely flushed, in order to change the block size, it may incur a temporary speed penalty during subsequent voxel accesses which cause the cache to read blocks from a file

public  void  set_default_max_bytes_in_cache(
    int  n_bytes )

Sets the default maximum number of bytes allowed in the cache for each volume. A higher number may provide faster access, due to a greater chance of finding a particular voxel within the cache, so this value should be as large as reasonable, given the amount of virtual memory available. If this function is not called, the default value is 80 megabytes, or the value of the environment variable VOLUME_CACHE_SIZE, if present. Setting a value of 0 will result in cached volumes having exactly one block in their cache. This function only affects volumes created subsequently. In order to change this value for a specific volume, the following function may be used:

public  void  set_volume_cache_size(
    Volume    volume,
    int       max_memory_bytes )

Sets the maximum number of bytes allowed in the cache for a particular volume. Calling this function flushes the cache, in order to reallocate the data structures to account for the new size. As in calling the function set_volume_cache_block_sizes, there may be a temporary speed loss in accessing pixels.

public  void  set_cache_output_volume_parameters(
    Volume                      volume,
    STRING                      filename,
    nc_type                     file_nc_data_type,
    BOOLEAN                     file_signed_flag,
    Real                        file_voxel_min,
    Real                        file_voxel_max,
    STRING                      original_filename,
    STRING                      history,
    minc_output_options         *options )

When a cached volume is modified, a temporary file is created to contain the voxel values. When the volume is deleted this file is also deleted. When a cached volume is output, the temporary file is copied to the output file, which results in two copies of the volume existing at once, which may incur unacceptable demands on disk storage, especially for large volumes. To avoid this, an application can specify a filename where to place the voxel values, which overrides the use of a temporary file. When the volume is deleted, this file is closed and remains on the disk, obviating the need for the application to output the volume.

If the application later calls output_volume() to output this volume to a file of the same name as that set by this function, the request to output will be ignored, because the volume already exists in this file. Basically, the programmer should call set_cache_output_volume_parameters() with the same parameters that will be passed to the eventual call to output_volume(). If the volume is a cached volume, then the output file will be created as soon as a volume voxel is set, and the later call to output_volume() will not recreate the file, but simply flush the cache buffer to make the file fully up to date. If the volume is not a cached volume, the call to set_cache_output_volume_parameters() will be ignored, and the later call to output_volume() will create the file as specified. Note that when calling this function, it is important to delete the volume before exitting the program, so that cached volumes will flush their buffer and close the file, Otherwise, the most recent changes to the volume will not be written to the file.