Two libraries support the writing/reading of data "slices" to/from full (and potentially larger) images. libDRMS provides drms_segment_writeslice() and drms_segment_readslice(). drms_segment_writeslice() takes an output data array and two vectors as input. The data array contains the slice that will be written into a region of the full image. The two vectors, each with a rank that matches the number of dimensions of the full image, specify the location in the full image to where the slice should be written. One vector, the "start" vector, specifies the "lower-left corner" of a bounding box that resides within the full image. The other vector, the "end" vector, specifies the "upper-right corner" of the bounding box. The bounding box thus described is exactly the same size as the slice to be written - drms_segment_writeslice() will write the slice into the bounding box with the data in the slice completely "filling" the bounding box. drms_segment_readslice() also takes two vectors as input that also specify a bounding box the lies within the full image. The function reads the data from the bounding box and returns a data array containing that data to the caller.
When the image to be written/read is compressed, only certain slice sizes are permitted. This restriction prevents inefficient writes and reads. The slice to be written/read must fully overlap an integral number of compression tiles. Otherwise image data that reside outside of the slice would need to be compressed/uncompressed. The restriction on slice dimensions ensures that the amount of data to be compressed/uncompressed is minimized.
When writing the first slice of a new, non-existent FITS file, a decision needs to be made about the dimensions of the final image in the new file being created. libDRMS always uses the dimension lengths in the segment's description when possible. For all non-VARDIM segment protocols, this is always the case; the segment's description must specify positive values for all dimension lengths, otherwise a failure will result. If a valid set of dimension lengths is specified, then the resulting FITS file will contain an image with those valid dimension lengths. If the segment protocol is VARDIM, however, then it is a combination of parameters in the segment's description and the output array being written that controls the dimensions of this final image:
If a segment description has the first N-1 dimension lengths non-zero, then the final, full image's first N-1 dimensions will always match these first N-1 dimensions specified in the jsd. If the jsd is defined in this way, then this implies that ALL images written to this series will always have the same dimension lengths for the first N-1 dimensions. The last dimension, however, could vary among images. The last dimension in the segment description specifies how large the image is in this last dimension when the image is first created. The first time a slice is written to a new image, a complete image is created (at least in memory, but the image could be flushed to disk). This initial image's first N-1 dimensions will match the first N-1 dimensions listed in the segment's specification. The last dimension will match the last dimension listed in the segment's specification, unless that dimension is 0. If that last dimension is 0, then the initial length of the last dimension is 1. Any pixel in this new image not contained in this first slice will be set to the appropriate missing value. Finally, as slices are written to the image, this last dimension could increase as needed. It is only in this last dimension that the image is allowed to "grow". For example, if the jsd specifies three dimensions with lengths of 1024, 256, 72, then ALL images written will have 1024 x 256 as the first two dimensions. The initial third dimension length of each image will be 72. And any image pixel not included in the first slice written will have missing as its value. If the caller writes a slice with dimensions 1024 x 256 x 144, then the image will grow in its third dimension to 144 pixels.
If any of the first N-1 dimension lengths in the segment description are 0, then libDRMS will use the first N-1 dimension lengths from the output array to determine the final image's first N-1 dimensions. In this case, the final images written to this series no longer need to match in the first N-1 dimensions. Each final image could have unique dimension lengths (although the total number of dimensions cannot vary). Again, each image can grow in the Nth dimension as slices are written, but it cannot grow in any of the other N-1 dimensions.