= Writing and Reading Data "Slices =

Two libraries support the writing/reading of data "slices" into/from full images. libDRMS provides drms_segment_writeslice(), drms_segment_readslice(), drms_fitsrw_writeslice(), drms_fitsrw_readslice(), drms_fitstas_writeslice(), and drms_fitstas_readslice(). drms_segment_writeslice() takes a data array and two vectors as input. The data array contains the slice of data that will be written into a region, identified by the vectors, of the full image. The region to be so written must lie completely within the dimensions of the full image - an error message is generated otherwise and the the function returns an error code. drms_segment_readslice() also takes two vectors as input that also specify a bounding box that 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. The caller may specify a data type when calling drms_segment_readslice() - the data slice extracted from the full image will be converted to this data type before the data array is returned to the caller. Both API functions support the FITS, TAS, and FITZ data segment protocols, and drms_segment_readslice() additionally supports the BINARY and BINZIP protocols. All other protocols are currently unsupported.

drms_fitsrw_writeslice() is similar to drms_segment_writeslice(). It writes a data slice to a file containing a full image. It differs, in that it operates only on FITS files. It takes a FITS file path, a slice of data, and information that describes the dimensions of the full image as input. If the FITS file already exists, it simply writes the slice into that FITS file. If the file does not exist, it creates it (using the input dimension information) and writes the first slice into it. Similarly, drms_fitsrw_readslice() reads a slice of data from a FITS file into a data array, using input vectors to identify the location and size of the desired slice in the FITS-file image. 


drms_segment_writeslice() - The data array contains the slice that will be written into a region of the full image. The two vectors, each with a number of elements equivalent to 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. This implies that the number of axes of the data array (slice) to be written must also be equivalent to the number of axes of the full image.



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 (the segment's specification line in the series' jsd) 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.