CBFlib Manual

Version	Date	By	Description
0.1	Apr. 1998	PJE	This was the first CBFlib release. It supported binary CBF files using binary strings.
0.2	Aug. 1998	HJB	This release added ascii imgCIF support using MIME-encoded binary sections, added the option of MIME headers for the binary strings was well. MIME code adapted from mpack 1.5. Added hooks needed for DDL1-style names without categories.
0.3	Sep. 1998	PJE	This release cleaned up the changes made for version 0.2, allowing multi-threaded use of the code, and removing dependence on the mpack package.
0.4	Nov. 1998	HJB	This release merged much of the message digest code into the general file reading and writing to reduce the number of passes. More consistency checking between the MIME header and the binary header was introduced. The size in the MIME header was adjusted to agree with the version 0.2 documentation.
0.5	Dec. 1998	PJE	This release greatly increased the speed of processing by allowing for deferred digest evaluation.
0.6	Jan. 1999	HJB	This release removed the redundant information (binary id, size, compression id) from a binary header when there is a MIME header, removed the unused repeat argument, and made the memory allocation for buffering and tables with many rows sensitive to the current memory allocation already used.
0.6.1	Feb. 2001	HP (per HJB)	This release fixed a memory leak due to misallocation by size of cbf_handle instead of cbf_handle_struct
0.7	Mar. 2001	PJE	This release added high-level instructions based on the imgCIF dictionary version 1.1.
0.7.1	Mar. 2001	PJE	The high-level functions were revised to permit future expansion to files with multiple images.
0.7.2	Apr. 2001	HJB	This release adjusted cbf_cimple.c to conform to cif_img.dic version 1.1.3
0.7.2.1	May 2001	PJE	This release corrected an if nesting error in the prior mod to cbf_cimple.c.
0.7.3	Oct. 2002	PJE	This release modified cbf_simple.c to reorder image data on read so that the indices are always increasing in memory (this behavior was undefined previously).
0.7.4	Jan 2004	HJB	This release fixes a parse error for quoted strings, adds code to get and set character string types, and removes compiler warnings
0.7.5	Apr 2006	HJB	This release cleans up some compiler warnings, corrects a parse error on quoted strings with a leading blank as adds the new routines for support of aliases, dictionaries and real arrays, higher level routines to get and set pixel sizes, do cell computations, and to set beam centers, improves support for conversion of images, picking up more data from headers.
0.7.6	Jul 2006	HJB	This release reorganizes the kit into two pieces: CBFlib_0.7.6_Data_Files and CBFlib_0.7.6. An optional local copy of getopt is added. The 1.4 draft dictionary has been added. cif2cbf updated to support vcif2 validation. convert_image and cif2cbf updated to report text of error messages. convert_image updated to support tag and category aliases, default to adxv images. convert_image and img updated to support row-major images. Support added for binning. API Support added for validation, wide files and line folding. Logic changed for beam center reporting. Added new routines: cbf_validate, cbf_get_bin_sizes, cbf_set_bin_sizes, cbf_find_last_typed_child, cbf_compose_itemname, cbf_set_cbf_logfile, cbf_make_widefile, cbf_read_anyfile, cbf_read_widefile, cbf_write_local_file, cbf_write_widefile, cbf_column_number, cbf_blockitem_number, cbf_log, cbf_check_category_tags, cbf_set_beam_center
0.7.7	February 2007	HJB	This release reflects changes for base 32K support developed by G. Darakev, and changes for support of reals, 3d arrays, byte_offset compression and J. P. Abrahams packed compression made in consultation with (in alphabetic order) E. Eikenberry, A. Hammerley, W. Kabsch, M. Kobas, J. Wright and others at PSI and ESRF in January 2007, as well accumulated changes fixing problems in release 0.7.6.
0.7.7.1	February 2007	HJB	This release is a patch to 0.7.7 to change the treatment of the byteorder parameter from strcpy semantics to return of a pointer to a string constant. Our thanks to E. Eikenberry for pointing out the problem.
0.7.7.2	February 2007	HJB	This release is a patch to 0.7.7.1 to add testing for JPA packed compression and to respect signs declared in the MIME header.
0.7.7.3	April 2007	HJB	This release is a patch to 0.7.7.3 to add f90 support for reading of CBF byte-offset and packed compression, to fix problems with gcc 4.4.1 and to correct errors in multidimensional packed compression.
0.7.7.4	May 2007	HJB	Corrects in handling SLS detector mincbfs and reorder dimensions versus arrays for some f90 compilers as per H. Powell.
0.7.7.5	May 2007	HJB	Fix to cbf_get_image for bug reported by F. Remacle, fixes for windows builds as per J. Wright and F. Remacle.
0.7.7.6	Jun 2007	HJB	Fix to CBF byte-offset compression writes, fix to Makefiles and m4 for f90 test programs to allow adjustable record length.
0.7.8	Jul 2007	HJB	Release for full support of SLS data files with updated convert_minicbf, and support for gfortran from gcc 4.2.
0.7.8.1	Jul 2007	HJB	Update to 0.7.8 release to fix memory leaks reported by N. Sauter and to update validation checks for recent changes.
0.7.8.2	Dec 2007	CN, HJB	Update to 0.7.8.1 to add ADSC jiffie by Chris Nielsen, and to add ..._fs and ..._sf macros.
0.7.9	Dec 2007	CN, HJB	Identical to 0.7.8.2 except for a cleanup of deprecated examples, e.g. diffrn_frame_data
0.7.9.1	Jan 2008	CN, HJB	Update to 0.7.8.2 to add inverse ADSC jiffie by Chris Nielsen, to clean up problems in handling maps for RasMol.
0.8.0	Jul 2008	GT, HJB	Cleanup of 0.7.9.1 to start 0.8 series.
0.8.1	Jul 2009	EZ, CN, PC, GW, JH, HJB	Release with EZ's 2008 DDLm support using JH's PyCifRW, also cbff f95 wrapper code, PC's java bindings.
0.9.1	Aug 2010	PC, EE, JLM, NS, EZ, HJB	Release with EE's Dectris template software, also with vcif3, new arvai_test, sequence_match.
0.9.2	Feb 2011	PC, EE, JLM, NS, EZ, HJB	New default release with updated pycbf, tiff support, removal of default use of PyCifRW to avoid Fedora license issue.
0.9.3	Oct 2013	JS, HJB	Added low-level 'cbf_H5' functions for interacting with HDF5, higher level functions for converting CBF or miniCBF files to NeXus format, two utility programs to convert CBF or miniCBF files to NeXus format and some unit tests for the low-level 'cbf_H5' functions. Add initial FEL detector support.
0.9.4	March 2014	JS, HJB	Refactored implementation of the NXMX application defintion functional mapping with improvements to cmake support and a preliminary effort at handling Stokes polarization mapping. This release had serious issues in the functional mapping axis mapping and should not be used for production involving NeXus files.
0.9.5	April 2014	HJB	This is a production release for single detector module single crystal MX NeXus support.

cbf_get_datestamp sets *year, *month, *day, *hour, *minute and *second to the corresponding values of the collection timestamp. *timezone is set to timezone difference from UTC in minutes. The parameter < i>reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
year	Pointer to the destination timestamp year.
month	Pointer to the destination timestamp month (1-12).
day	Pointer to the destination timestamp day (1-31).
hour	Pointer to the destination timestamp hour (0-23).
minute	Pointer to the destination timestamp minute (0-59).
second	Pointer to the destination timestamp second (0-60.0).
timezone	Pointer to the destination timezone difference from UTC in minutes.

2.4.23 cbf_set_datestamp

int cbf_set_datestamp (cbf_handle handle, unsigned int reserved, int year, int month, int day, int hour, int minute, double second, int timezone, double precision);

cbf_set_datestamp sets the collection timestamp in seconds since January 1 1970 to the value specified by time. The timezone difference from UTC in minutes is set to timezone. If no timezone is desired, timezone should be CBF_NOTIM EZONE. The parameter reserved is presently unused and should be set to 0.

The precision of the new timestamp is specified by the value precision in seconds. If precision is 0, the saved timestamp is assumed accurate to 1 second.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
time	Timestamp in seconds since January 1 1970.
timezone	Timezone difference from UTC in minutes or CBF_NOTIMEZONE.
precision	Timestamp precision in seconds.

2.4.24 cbf_set_current_timestamp

int cbf_set_current_timestamp (cbf_handle handle, unsigned int reserved, int timezone);

cbf_set_current_timestamp sets the collection timestamp to the current time. The timezone difference from UTC in minutes is set to timezone. If no timezone is desired, timezone should be CBF_NOTIMEZONE. If no timezone is used, the timest amp will be UTC. The parameter reserved is presently unused and should be set to 0.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
timezone	Timezone difference from UTC in minutes or CBF_NOTIMEZONE.

2.4.25 cbf_get_image_size, cbf_get_image_size_fs, cbf_get_image_size_sf,
cbf_get_3d_image_size, cbf_get_3d_image_size_fs, cbf_get_3d_image_size_sf

int cbf_get_image_size (cbf_handle handle, unsigned int reserved, unsigned int element_number, size_t *ndimslow, size_t *ndimfast);
int cbf_get_image_size_fs (cbf_handle handle, unsigned int reserved, unsigned int element_number, size_t *ndimfast, size_t *ndimslow);
int cbf_get_image_size_sf (cbf_handle handle, unsigned int reserved, unsigned int element_number, size_t *ndimslow, size_t *ndimfast);

int cbf_get_3d_image_size (cbf_handle handle, unsigned int reserved, unsigned int element_number, size_t *ndimslow, size_t *ndimmid, size_t *ndimfast);
int cbf_get_3d_image_size_fs (cbf_handle handle, unsigned int reserved, unsigned int element_number, size_t *ndimfast, size_t *ndimmid, size_t *ndimslow);
int cbf_get_3d_image_size_sf (cbf_handle handle, unsigned int reserved, unsigned int element_number, size_t *ndimslow, size_t *ndimmid, size_t *ndimfast);

cbf_get_image_size, cbf_get_image_size_fs and cbf_get_image_size_sf set *ndimslow and *ndimfast to the slow and fast dimensions of the image array for element number element_number. If the array is 1-dimensional, *ndimslow will be set to the array size and *ndimfast will be set to 1. If the array is 3-dimensional an error code will be returned. cbf_get_3d_image_size, cbf_get_3d_image_size_fs and cbf_get_3d_image_size_sf set *ndimslow, *ndimmid and *ndimfast to the slowest, next fastest and fastest dimensions, respectively, of the 3D image array for element number element_number. If the array is 1-dimensional, *ndimslow will be set to the array size and *ndimmid and *ndimfast will be set to 1. If the array is 2-dimensional *ndimslow and *ndimmid will be set as for a call to cbf_get_image_size and *ndimfast will be set to 1.

The _fs calls give the dimensions in a fast-to-slow order. The calls with no suffix and the calls _sf calls give the dimensions in slow-to-fast order

Note that the ordering of dimensions is specified by values of the tag _array_structure_list.precedence with a precedence of 1 for the fastest dimension, 2 for the next slower, etc., which is opposite to the ordering of the dimension arguments for these functions, except for the ones with the _fs suffix..

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
ndimslow	Pointer to the destination slowest dimension.
ndimmid	Pointer to the destination next faster dimension.
ndimfast	Pointer to the destination fastest dimension.

2.4.26 cbf_get_image, cbf_get_image_fs, cbf_get_image_sf,
      cbf_get_real_image, cbf_get_real_image_fs, cbf_get_real_image_sf,
      cbf_get_3d_image, cbf_get_3d_image_fs, cbf_get_3d_image_sf,
      cbf_get_real_3d_image, cbf_get_real_3d_image_fs, cbf_get_real_3d_image_sf

int cbf_get_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimfast);
int cbf_get_image_fs (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, int elsign, size_t ndimfast, size_t ndimslow);
int cbf_get_image_sf (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimfast);

int cbf_get_real_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, size_t ndimslow, size_t ndimfast);
int cbf_get_real_image_fs (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, size_t ndimfast, size_t ndimslow);
int cbf_get_real_image_sf (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, size_t ndimslow, size_t ndimfast);

int cbf_get_3d_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_get_3d_image_fs (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, int elsign, size_t ndimfast, size_t ndimmid, size_t ndimslow);
int cbf_get_3d_image_sf (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t ndimfast);

int cbf_get_real_3d_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_get_real_3d_image_fs (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, size_t ndimfast, size_t ndimmid, size_t ndimslow);
int cbf_get_real_3d_image_sf (cbf_handle handle, unsigned int reserved, unsigned int element_number, void *array, size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);

cbf_get_image, cbf_get_image_fs and cbf_get_image_sf read the image array for element number element_number into an array. The array consists of ndimslow×ndimfast elements of elsize bytes each, starting at array. The elements are signed if elsign is non-0 and unsigned otherwise. cbf_get_real_image, cbf_get_real_image_fs and cbf_get_real_image_sf read the image array of IEEE doubles or floats for element number element_number into an array. A real array is always signed. cbf_get_3d_image, cbf_get_3d_image_fs and cbf_get_3d_image_sf read the 3D image array for element number element_number into an array. The array consists of ndimslow×ndimmid×ndimfast elements of elsize bytes each, starting at array. The elements are signed if elsign is non-0 and unsigned otherwise. cbf_get_real_3d_image, cbf_get_real_3d_image_fs, cbf_get_real_3d_image_sf reads the 3D image array of IEEE doubles or floats for element number element_number into an array. A real array is always signed.

The _fs calls give the dimensions in a fast-to-slow order. The calls with no suffix and the calls _sf calls give the dimensions in slow-to-fast order

The structure of the array as a 1-, 2- or 3-dimensional array should agree with the structure of the array given in the ARRAY_STRUCTURE_LIST category. If the array is 1-dimensional, ndimslow should be the array size and ndimfast and, for the 3D calls, ndimmid, should be set to 1 both in the call and in the imgCIF data being processed. If the array is 2-dimensional and a 3D call is used, ndimslow and ndimmid should be the array dimensions and ndimfast should be set to 1 both in the call and in the imgCIF data being processed.

If any element in the binary data can�t fit into the destination element, the destination is set the nearest possible value.

If the requested number of elements can�t be read, the function will read as many as it can and then return CBF_ENDOFDATA.

Currently, the destination array must consist of chars, shorts or ints (signed or unsigned) for cbf_get_image, or IEEE doubles or floats for cbf_get_real_image. If elsize is not equal to sizeof (char), sizeof (short), sizeof (int), sizeof(double) or sizeof(float), the function returns CBF_ARGUMENT.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
array	Pointer to the destination array.
elsize	Size in bytes of each destination array element.
elsigned	Set to non-0 if the destination array elements are signed.
ndimslow	Slowest array dimension.
ndimmid	Next faster array dimension.
ndimfast	Fastest array dimension.

2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,
      cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf,
      cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,
      cbf_set_real_3d_image, cbf_set_real_3d_image_fs, cbf_set_real_3d_image_sf

int cbf_set_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimfast);
int cbf_set_image_fs(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array, size_t elsize, int elsign, size_t ndimfast, size_t ndimslow);
int cbf_set_image_sf(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimfast);

int cbf_set_real_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array,size_t elsize, size_t ndimslow, size_t ndimfast);
int cbf_set_real_image_fs(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array,size_t elsize, size_t ndimfast, size_t ndimslow);
int cbf_set_real_image_sf(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array,size_t elsize, size_t ndimslow, size_t ndimfast);

int cbf_set_3d_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_set_3d_image_fs(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array, size_t elsize, int elsign, size_t ndimfast, size_t ndimmid, size_t ndimslow);
int cbf_set_3d_image_sf(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array, size_t elsize, int elsign, size_t ndimslow, size_t ndimmid, size_t ndimfast);

int cbf_set_real_3d_image (cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array,size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);
int cbf_set_real_3d_image_fs(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array,size_t elsize, size_t ndimfast, size_t ndimmid, size_t ndimslow);
int cbf_set_real_3d_image_sf(cbf_handle handle, unsigned int reserved, unsigned int element_number, unsigned int compression, void *array,size_t elsize, size_t ndimslow, size_t ndimmid, size_t ndimfast);

cbf_set_image, cbf_set_image_fs and cbf_set_image_sf write the image array for element number element_number. The array consists of ndimfast×ndimslow elements of elsize bytes each, starting at array. The elements are signed if elsign is non-zero and unsigned otherwise. cbf_set_real_image, cbf_set_real_image_fs and cbf_set_real_image_sf write the image array for element number element_number. The array consists of ndimfast×ndimslow IEEE double or float elements of elsize bytes each, starting at array. cbf_set_3d_image, cbf_set_3d_image_fs and cbf_set_3d_image_sf write the 3D image array for element number element_number. The array consists of ndimfast×ndimmid×ndimslow elements of elsize bytes each, starting at array. The elements are signed if elsign is non-0 and unsigned otherwise. cbf_set_real_3d_image, cbf_set_real_3d_image_fs and cbf_set_real_3d_image_sf writes the 3D image array for element number element_number. The array consists of ndimfast×ndimmid×ndimslow IEEE double or float elements of elsize bytes each, starting at array.

The _fs calls give the dimensions in a fast-to-slow order. The calls with no suffix and the calls _sf calls give the dimensions in slow-to-fast order

If the array is 1-dimensional, ndimslow should be the array size and ndimfast and, for the 3D calls, ndimmid, should be set to 1. If the array is 2-dimensional and the 3D calls are used, ndimslow and ndimmid should be used for the array dimensions and ndimfast should be set to 1.

The array will be compressed using the compression scheme specifed by compression. Currently, the available schemes are:

CBF_CANONICAL	Canonical-code compression (section 3.3.1)
CBF_PACKED	CCP4-style packing (section 3.3.2)
CBF_PACKED_V2	CCP4-style packing, version 2 (section 3.3.2)
CBF_BYTE_OFFSET	Simple "byte_offset" compression.
CBF_NIBBLE_OFFSET	Simple "nibble_offset" compression.
CBF_NONE	No compression.

The values compressed are limited to 64 bits. If any element in the array is larger than 64 bits, the value compressed is the nearest 64-bit value.

Currently, the source array must consist of chars, shorts or ints (signed or unsigned)for cbf_set_image, or IEEE doubles or floats for cbf_set_real_image. If elsize is not equal to sizeof (short), sizeof (int), sizeof(double) or sizeof(float), the function returns CBF_ARGUMENT.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
compression	Compression type.
array	Pointer to the image array.
elsize	Size in bytes of each image array element.
elsigned	Set to non-0 if the image array elements are signed.
ndimslow	Slowest array dimension.
ndimmid	Second slowest array dimension.
ndimfast	Fastest array dimension.

2.4.28 cbf_count_axis_ancestors, cbf_get_axis_ancestor, cbf_get_axis_depends_on,
cbf_get_axis_equipment, cbf_get_axis_equipment_component,
cbf_get_axis_offset,
cbf_get_axis_rotation, cbf_get_axis_rotation_axis,
cbf_get_axis_setting,
cbf_get_axis_type,
cbf_get_axis_vector

int cbf_count_axis_ancestors (cbf_handle handle, const char *axis_id, unsigned int *ancestors);

int cbf_get_axis_ancestor (cbf_handle handle, const char *axis_id, const unsigned int ancestor_index, const char * *ancestor);

int cbf_get_axis_depends_on (cbf_handle handle, const char *axis_id, const char * *depends_on);

int cbf_get_axis_equipment (cbf_handle handle, const char *axis_id, const char * *equipment);

int cbf_get_axis_equipment_component (cbf_handle handle, const char *axis_id, const char * *equipment_component);

int cbf_get_axis_offset (cbf_handle handle, const char *axis_id, double *offset1, double *offset2, double *offset3);

int cbf_get_axis_rotation (cbf_handle handle, const char *axis_id, double *rotation);

int cbf_get_axis_rotation_axis (cbf_handle handle, const char *axis_id, const char * *rotation_axis);

int cbf_get_axis_setting (cbf_handle handle, unsigned int reserved, const char *axis_id, double *start, double *increment);

int cbf_get_axis_type (cbf_handle handle, const char *axis_id, cbf_axis_type *axis_type);

int cbf_get_axis_vector (cbf_handle handle, const char *axis_id, double *vector1, double *vector2, double *vector3);

cbf_count_axis_ancestors sets ancestors to the number of ancestors of axis axis_id. cbf_get_axis_ancestor sets *ancestor to the ancestor axis of index ancestor_index of axis axis_id, starting with axis_id for ancestor_index 0.

cbf_get_axis_depends_on sets *depends_on to the immediate ancestor of axis_id or to "." if there is no such ancestor. cbf_get_axis_equipment sets *equipment to the equipment of axis_id or to "." if there is no such equipment. cbf_get_axis_equipment_component sets *equipment_component to the equipment_component of axis_id or to "." if there is no such equipment_component.

cbf_get_axis_offset sets *offset1, *offset2 and *offset3 to the components of the ofset of axis_id.

cbf_get_axis_rotation sets rotation to the rotation of axis_id or to 0 if there is no such rotation. cbf_get_axis_rotation_axis sets *rotation_axis to the rotation_axis of axis_id or to "." if there is no such rotation_axis.

cbf_get_axis_setting sets *start and *increment to the corresponding values of the axis axis_id. Any of the destination pointers may be NULL.

cbf_get_axis_vector sets *vector1, *vector2 and *vector3 to the components of the vector of axis_id.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
axis_id	Axis id.
ancestor_index	Integer index of the desired ancestor, starting with 0 for the current axis_id.
ancestor	Pointer to destination ancestor name pointer.
depends_on	Pointer to destination depends_on name pointer.
equipment	Pointer to destination equipment name pointer.
equipment_component	Pointer to destination equipment_component name pointer.
offset1	Pointer to destination first offset component value.
offset2	Pointer to destination second offset component value.
offset3	Pointer to destination third offset component value.
rotation	Pointer to destination rotation value.
rotation_axis	Pointer to destination rotation_axisn name pointer.
start	Pointer to the destination start value.
increment	Pointer to the destination increment value.
type	Pointer to destination axis type of type .
vector1	Pointer to destination first vector component value.
vector2	Pointer to destination second vector component value.
vector3	Pointer to destination third vector component value.

2.4.29 cbf_set_axis_setting

int cbf_set_axis_setting (cbf_handle handle, unsigned int reserved, const char *axis_id, double start, double increment);

cbf_set_axis_setting sets the starting and increment values of the axis axis_id to start and increment.

ARGUMENTS

handle	CBF handle.
reserved	Unused. Any value other than 0 is invalid.
axis_id	Axis id.
start	Start value.
increment	Increment value.

2.4.30 cbf_construct_goniometer

int cbf_construct_goniometer (cbf_handle handle, cbf_goniometer *goniometer);

cbf_construct_goniometer constructs a goniometer object using the description in the CBF object handle and initialises the goniometer handle *goniometer.

ARGUMENTS

handle	CBF handle.
goniometer	Pointer to the destination goniometer handle.

2.4.31 cbf_free_goniometer

cbf_free_goniometer destroys the goniometer object specified by goniometer and frees all associated memory.

2.4.32 cbf_get_rotation_axis

int cbf_get_rotation_axis (cbf_goniometer goniometer, unsigned int reserved, double *vector1, double *vector2, double *vector3);

cbf_get_rotation_axis sets *vector1, *vector2, and *vector3 to the 3 components of the goniometer rotation axis used for the exposure.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
vector1	Pointer to the destination x component of the rotation axis.
vector2	Pointer to the destination y component of the rotation axis.
vector3	Pointer to the destination z component of the rotation axis.

2.4.33 cbf_get_rotation_range

int cbf_get_rotation_range (cbf_goniometer goniometer, unsigned int reserved, double *start, double *increment);

cbf_get_rotation_range sets *start and *increment to the corresponding values of the goniometer rotation axis used for the exposure.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
start	Pointer to the destination start value.
increment	Pointer to the destination increment value.

2.4.34 cbf_rotate_vector

int cbf_rotate_vector (cbf_goniometer goniometer, unsigned int reserved, double ratio, double initial1, double initial2, double initial3, double *final1, double *final2, double *final3);

cbf_rotate_vector sets *final1, *final2, and *final3 to the 3 components of the of the vector (initial1, initial2, initial3) after reorientation by applying the goniometer rotations. The value ratio specif ies the goniometer setting and varies from 0.0 at the beginning of the exposure to 1.0 at the end, irrespective of the actual rotation range.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
ratio	Goniometer setting. 0 = beginning of exposure, 1 = end.
initial1	x component of the initial vector.
initial2	y component of the initial vector.
initial3	z component of the initial vector.
vector1	Pointer to the destination x component of the final vector.
vector2	Pointer to the destination y component of the final vector.
vector3	Pointer to the destination z component of the final vector.

2.4.35 cbf_get_reciprocal

int cbf_get_reciprocal (cbf_goniometer goniometer, unsigned int reserved, double ratio, double wavelength, double real1, double real2, double real3, double *reciprocal1, double *reciprocal2, double *reciprocal3);

cbf_get_reciprocal sets *reciprocal1, * reciprocal2, and * reciprocal3 to the 3 components of the of the reciprocal-space vector corresponding to the real-space vector (real1, real2, real3). The reciprocal-space vector is oriented to correspond to the goniometer setting with all axes at 0. The value wavelength is the wavlength in Å and the value ratio specifies the current goniometer setting and varies from 0.0 at the beginning of the exposur e to 1.0 at the end, irrespective of the actual rotation range.

ARGUMENTS

goniometer	Goniometer handle.
reserved	Unused. Any value other than 0 is invalid.
ratio	Goniometer setting. 0 = beginning of exposure, 1 = end.
wavelength	Wavelength in Å.
real1	x component of the real-space vector.
real2	y component of the real-space vector.
real3	z component of the real-space vector.
reciprocal1	Pointer to the destination x component of the reciprocal-space vector.
reciprocal2	Pointer to the destination y component of the reciprocal-space vector.
reciprocal3	Pointer to the destination z component of the reciprocal-space vector.

2.4.36 cbf_construct_detector, cbf_construct_reference_detector, cbf_require_reference_detector

int cbf_construct_detector (cbf_handle handle, cbf_detector *detector, unsigned int element_number);

int cbf_construct_reference_detector (cbf_handle handle, cbf_detector *detector, unsigned int element_number);

int cbf_require_reference_detector (cbf_handle handle, cbf_detector *detector, unsigned int element_number);

cbf_construct_detector constructs a detector object for detector element number element_number using the description in the CBF object handle and initialises the detector handle *detector.

cbf_construct_reference_detector constructs a detector object for detector element number element_number using the description in the CBF object handle and initialises the detector handle *detector using the reference settings of the axes. cbf_require_reference_detector is similar, but try to force the creations of missing intermediate categories needed to construct a detector object.

ARGUMENTS

handle	CBF handle.
detector	Pointer to the destination detector handle.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.

2.4.37 cbf_free_detector

cbf_free_detector destroys the detector object specified by detector and frees all associated memory.

2.4.38 cbf_construct_positioner, cbf_construct_reference_positioner,

int cbf_construct_positioner (cbf_handle handle, cbf_positioner *positioner, const char *axis_id);

int cbf_construct_reference_positioner (cbf_handle handle, cbf_positioner *positioner, const char *axis_id);

cbf_construct_positioner constructs a positioner object for the axis given by axis_id using the description in the CBF object handle and initialises the positioner handle *positioner.

cbf_construct_reference positioner constructs a positioner object for the axis given by axis_id using the description in the CBF object handle and initialises the detector handle *detector using the reference settings of the axes.

ARGUMENTS

handle	CBF handle.
detector	Pointer to the destination detector handle.
axis_id	The identifier of the axis in the "axis" category.

2.4.39 cbf_free_positioner

cbf_free_positioner destroys the positioner object specified by positioner and frees all associated memory.

2.4.40 cbf_get_beam_center, cbf_get_beam_center_fs, cbf_get_beam_center_sf,
cbf_set_beam_center, cbf_set_beam_center_fs, cbf_set_beam_center_sf,
set_reference_beam_center, set_reference_beam_center_fs, set_reference_beam_center_fs

int cbf_get_beam_center (cbf_detector detector, double *indexslow, double *indexfast, double *centerslow, double *centerfast);
int cbf_get_beam_center_fs (cbf_detector detector, double *indexfast, double *indexslow, double *centerfast, double *centerslow);
int cbf_get_beam_center_sf (cbf_detector detector, double *indexslow, double *indexfast, double *centerslow, double *centerfast);

int cbf_set_beam_center (cbf_detector detector, double *indexslow, double *indexfast, double *centerslow, double *centerfast);
int cbf_set_beam_center_fs (cbf_detector detector, double *indexfast, double *indexslow, double *centerfast, double *centerslow);
int cbf_set_beam_center_sf (cbf_detector detector, double *indexslow, double *indexfast, double *centerslow, double *centerfast);

int cbf_set_reference_beam_center (cbf_detector detector, double *indexslow, double *indexfast, double *centerslow, double *centerfast);
int cbf_set_reference_beam_center_fs (cbf_detector detector, double *indexfast, double *indexslow, double *centerfast, double *centerslow);
int cbf_set_reference_beam_center_sf (cbf_detector detector, double *indexslow, double *indexfast, double *centerslow, double *centerfast);

cbf_get_beam_center sets *centerfast and *centerslow to the displacements in mm along the detector axes from pixel (0, 0) to the point at which the beam intersects the detector and *indexfast and *indexslow to the corresponding indices. cbf_set_beam_center sets the offsets in the axis category for the detector element axis with precedence 1 to place the beam center at the position given in mm by *centerfast and *centerslow as the displacements in mm along the detector axes from pixel (0, 0) to the point at which the beam intersects the detector at the indices given *indexfast and *indexslow. cbf_set_reference_beam_center sets the displacments in the array_structure_list_axis category to place the beam center at the position given in mm by *centerfast and *centerslow as the displacements in mm along the detector axes from pixel (0, 0) to the point at which the beam intersects the detector at the indices given by *indexfast and *indexslow. In order to achieve consistent results, a reference detector should be used for detector to have all axes at their reference settings.

Note that the precedence 1 axis is the fastest axis, so that *centerfast and *indexfast are the fast axis components of the center and *centerslow and *indexslow are the slow axis components of the center.

The _fs calls give the displacments in a fast-to-slow order. The calls with no suffix and the calls _sf calls give the displacements in slow-to-fast order

Any of the destination pointers may be NULL for getting the beam center. For setting the beam axis, either the indices of the center must not be NULL.

The indices are non-negative for beam centers within the detector surface, but the center for an axis with a negative increment will be negative for a beam center within the detector surface.

For cbf_set_beam_center if the diffrn_data_frame category exists with a row for the corresponding element id, the values will be set for _diffrn_data_frame.center_fast and _diffrn_data_frame.center_slow in millimetres and the value of _diffrn_data_frame.center_units will be set to 'mm'.

For cbf_set_reference_beam_center if the diffrn_detector_element category exists with a row for the corresponding element id, the values will be set for _diffrn_detector_element.reference_center_fast and _diffrn_detector_element.reference_center_slow in millimetres and the value of _diffrn_detector_element.reference_units will be set to 'mm'.

ARGUMENTS

detector	Detector handle.
indexfast	Pointer to the destination fast index.
indexslow	Pointer to the destination slow index.
centerfast	Pointer to the destination displacement along the fast axis.
centerslow	Pointer to the destination displacement along the slow axis.

2.4.41 cbf_get_detector_distance

cbf_get_detector_distance sets *distance to the nearest distance from the sample position to the detector plane.

ARGUMENTS

detector	Detector handle.
distance	Pointer to the destination distance.

2.4.42 cbf_get_detector_normal

int cbf_get_detector_normal (cbf_detector detector, double *normal1, double *normal2, double *normal3);

cbf_get_detector_normal sets *normal1, *normal2, and *normal3 to the 3 components of the of the normal vector to the detector plane. The vector is normalized.

ARGUMENTS

detector	Detector handle.
normal1	Pointer to the destination x component of the normal vector.
normal2	Pointer to the destination y component of the normal vector.
normal3	Pointer to the destination z component of the normal vector.

2.4.43 cbf_get_detector_axis_slow, cbf_get_detector_axis_slow, cbf_get_detector_axes, cbf_get_detector_axes_fs, cbf_get_detector_axes_sf, cbf_get_detector_surface_axes

int cbf_get_detector_axis_slow (cbf_detector detector, double *slowaxis1, double *slowaxis2, double *slowaxis3);
int cbf_get_detector_axis_fast (cbf_detector detector, double *fastaxis1, double *fastaxis2, double *fastaxis3);
int cbf_get_detector_axes (cbf_detector detector, double *slowaxis1, double *slowaxis2, double *slowaxis3, double *fastaxis1, double *fastaxis2, double *fastaxis3);
int cbf_get_detector_axes_fs (cbf_detector detector, double *fastaxis1, double *fastaxis2, double *fastaxis3, double *slowaxis1, double *slowaxis2, double *slowaxis3);
int cbf_get_detector_axes_sf (cbf_detector detector, double *slowaxis1, double *slowaxis2, double *slowaxis3, double *fastaxis1, double *fastaxis2, double *fastaxis3);
int cbf_get_detector_surface_axes(cbf_detector detector, const char * * axis_id1, const char * * axis_id2);

cbf_get_detector_axis_slow sets *slowaxis1, *slowaxis2, and *slowaxis3 to the 3 components of the slow axis of the specified detector at the current settings of all axes. cbf_get_detector_axis_slow sets *fastaxis1, *fastaxis2, and *fastaxis3 to the 3 components of the fast axis of the specified detector at the current settings of all axes. cbf_get_detector_axes, cbf_get_detector_axes_fs and int cbf_get_detector_axes_sf set *slowaxis1, *slowaxis2, and *slowaxis3 to the 3 components of the slow axis and *fastaxis1, *fastaxis2, and *fastaxis3 to the 3 components of the fast axis of the specified detector at the current settings of all axes. cbf_get_detector_surface_axes sets *axis_id1 and *axis_id2 to the names of the two surface axes of the detector or ".",

ARGUMENTS

detector	Detector handle.
slowaxis1	Pointer to the destination x component of the slow axis vector.
slowaxis2	Pointer to the destination y component of the slow axis vector.
slowaxis3	Pointer to the destination z component of the slow axis vector.
fastaxis1	Pointer to the destination x component of the fast axis vector.
fastaxis2	Pointer to the destination y component of the fast axis vector.
fastaxis3	Pointer to the destination z component of the fast axis vector.
axis_id1	Pointer to the destination first surface axis name.
axis_id1	Pointer to the destination first surface axis name.
axis_id2	Pointer to the destination second surface axis name.

2.4.44 cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs, cbf_get_pixel_coordinates_sf

int cbf_get_pixel_coordinates (cbf_detector detector, double indexslow, double indexfast, double *coordinate1, double *coordinate2, double *coordinate3);
int cbf_get_pixel_coordinates_fs (cbf_detector detector, double indexfast, double indexslow, double *coordinate1, double *coordinate2, double *coordinate3);
int cbf_get_pixel_coordinates_sf (cbf_detector detector, double indexslow, double indexfast, double *coordinate1, double *coordinate2, double *coordinate3);

cbf_get_pixel_coordinates, cbf_get_pixel_coordinates_fs and cbf_get_pixel_coordinates_sf ses *coordinate1, *coordinate2, and *coordinate3 to the vector position of pixel (indexfast, indexslow) on the detector surface. If indexslow and indexfast are integers then the coordinates correspond to the center of a pixel.

ARGUMENTS

detector	Detector handle.
indexslow	Slow index.
indexfast	Fast index.
coordinate1	Pointer to the destination x component.
coordinate2	Pointer to the destination y component.
coordinate3	Pointer to the destination z component.

2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs, cbf_get_pixel_normal_sf

int cbf_get_pixel_normal (cbf_detector detector, double indexslow, double indexfast, double *normal1, double *normal2, double *normal3);
int cbf_get_pixel_normal_fs (cbf_detector detector, double indexfast, double indexslow, double *normal1, double *normal2, double *normal3);
int cbf_get_pixel_normal (cbf_detector detector, double indexslow, double indexfast, double *normal1, double *normal2, double *normal3);

cbf_get_detector_normal, cbf_get_pixel_normal_fs and cbf_get_pixel_normal_sf set *normal1, *normal2, and *normal3 to the 3 components of the of the normal vector to the pixel at (indexfast, indexslow). The vector is normalized.

ARGUMENTS

detector	Detector handle.
indexslow	Slow index.
indexfast	Fast index.
normal1	Pointer to the destination x component of the normal vector.
normal2	Pointer to the destination y component of the normal vector.
normal3	Pointer to the destination z component of the normal vector.

2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs, cbf_get_pixel_area_sf

int cbf_get_pixel_area (cbf_detector detector, double indexslow, double indexfast, double *area, double *projected_area);
int cbf_get_pixel_area_fs(cbf_detector detector, double indexfast, double indexslow, double *area, double *projected_area);
int cbf_get_pixel_area_sf(cbf_detector detector, double indexslow, double indexfast, double *area, double *projected_area);

cbf_get_pixel_area, cbf_get_pixel_area_fs and cbf_get_pixel_area_sf set *area to the area of the pixel at (indexfast, indexslow) on the detector surface and *projected_area to the apparent area of the pixel as viewed from the sample position, with indexslow being the slow axis and indexfast being the fast axis.

ARGUMENTS

detector	Detector handle.
indexfast	Fast index.
indexslow	Slow index.
area	Pointer to the destination area in mm2.
projected_area	Pointer to the destination apparent area in mm2.

2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs, cbf_get_pixel_size_sf

int cbf_get_pixel_size (cbf_handle handle, unsigned int element_number, int axis_number, double *psize);
int cbf_get_pixel_size_fs(cbf_handle handle, unsigned int element_number, int axis_number, double *psize);
int cbf_get_pixel_size_sf(cbf_handle handle, unsigned int element_number, int axis_number, double *psize);

cbf_get_pixel_size and cbf_get_pixel_size_sf set *psize to point to the double value in millimeters of the axis axis_number of the detector element element_number. The axis_number is numbered from 1, starting with the slowest axis. cbf_get_pixel_size_fs sets *psize to point to the double value in millimeters of the axis axis_number of the detector element element_number. The axis_number is numbered from 1, starting with the fastest axis.

If a negative axis number is given, the order of axes is reversed, so that -1 specifies the slowest axis for cbf_get_pixel_size_fs and the fastest axis for cbf_get_pixel_size_sf.

If the pixel size is not given explcitly in the "array_element_size" category, the function returns CBF_NOTFOUND.

ARGUMENTS

handle	CBF handle.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
axis_number	The number of the axis, starting from 1 for the fastest for cbf_get_pixel_size and cbf_get_pixel_size_fs and the slowest for cbf_get_pixel_size_sf.
psize	Pointer to the destination pixel size.

2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs, cbf_set_pixel_size_sf

int cbf_set_pixel_size (cbf_handle handle, unsigned int element_number, int axis_number, double psize);
int cbf_set_pixel_size_fs(cbf_handle handle, unsigned int element_number, int axis_number, double psize);
int cbf_set_pixel_size_sf(cbf_handle handle, unsigned int element_number, int axis_number, double psize);

cbf_set_pixel_size and cbf_set_pixel_size_sf set the item in the "e;size"e; column of the "array_structure_list" category at the row which matches axis axis_number of the detector element element_number converting the double pixel size psize from meters to millimeters in storing it in the "size" column for the axis axis_number of the detector element element_number. The axis_number is numbered from 1, starting with the slowest axis. cbf_set_pixel_size_fs sets the item in the "e;size"e; column of the "array_structure_list" category at the row which matches axis axis_number of the detector element element_number converting the double pixel size psize from meters to millimeters in storing it in the "size" column for the axis axis_number of the detector element element_number. The axis_number is numbered from 1, starting with the fastest axis.

If a negative axis number is given, the order of axes is reversed, so that -1 specifies the slowest axis for cbf_get_pixel_size_fs and the fastest axis for cbf_get_pixel_size_sf.

If the appropriate row in the "array_structure_list" catgeory does not already exist, it is created.

If the pixel size is not given explcitly in the "array_element_size category", the function returns CBF_NOTFOUND.

ARGUMENTS

handle	CBF handle.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
axis_number	The number of the axis, fastest first, starting from 1.
psize	The pixel size in millimeters.

2.4.49 cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_fs, cbf_get_inferred_pixel_size_sf

int cbf_get_inferred_pixel_size (cbf_detector detector, int axis_number, double *psize);
int cbf_get_inferred_pixel_size_fs(cbf_detector detector, int axis_number, double *psize);
int cbf_get_inferred_pixel_size_sf(cbf_detector detector, int axis_number, double *psize);

cbf_get_inferred_pixel_size, cbf_get_inferred_pixel_size_sf set *psize to point to the double value in millimeters of the pixel size for the axis axis_number value. The slow index is treated as axis 1 and the next faster index is treated as axis 2. cbf_get_inferred_pixel_size_fs sets *psize to point to the double value in millimeters of the pixel size for the axis axis_number value. The fast index is treated as axis 1 and the next slower index is treated as axis 2.

If the axis number is negative, the axes are used in the reverse order so that an axis_number of -1 indicates the fast axes in a call to cbf_get_inferred_pixel_size or cbf_get_inferred_pixel_size_sf and indicates the fast axis in a call to cbf_get_inferred_pixel_size_fs.

ARGUMENTS

detector	Detector handle.
axis_number	The number of the axis.
area	Pointer to the destination pizel size in mm.

2.4.50 cbf_get_unit_cell

int cbf_get_unit_cell (cbf_handle handle, double cell[6], double cell_esd[6] );

cbf_get_unit_cell sets cell[0:2] to the double values of the cell edge lengths a, b and c in Ångstroms, cell[3:5] to the double values of the cell angles α, β and γ in degrees, cell_esd[0:2] to the double values of the estimated strandard deviations of the cell edge lengths a, b and c in Ångstroms, cell_esd[3:5] to the double values of the estimated standard deviations of the the cell angles α, β and γ in degrees.

The values returned are retrieved from the first row of the "cell" category. The value of "_cell.entry_id" is ignored.

If the "cell" category is present, but some of the values are missing, zeros are returned for the missing values.

ARGUMENTS

handle	CBF handle.
cell	Pointer to the destination array of 6 doubles for the cell parameters.
cell_esd	Pointer to the destination array of 6 doubles for the cell parameter esds.

Returns an error code on failure or 0 for success. No errors is returned for missing values if the "cell" category exists.

2.4.51 cbf_set_unit_cell

int cbf_set_unit_cell (cbf_handle handle, double cell[6], double cell_esd[6] );

cbf_set_unit_cell sets the cell parameters to the double values given in cell[0:2] for the cell edge lengths a, b and c in Ångstroms, the double values given in cell[3:5] for the cell angles α, β and γ in degrees, the double values given in cell_esd[0:2] for the estimated strandard deviations of the cell edge lengths a, b and c in Ångstroms, and the double values given in cell_esd[3:5] for the estimated standard deviations of the the cell angles α, β and γ in degrees.

The values are placed in the first row of the "cell" category. If no value has been given for "_cell.entry_id", it is set to the value of the "diffrn.id" entry of the current data block.

If the "cell" category is not present, it is created. If any of the necessary columns are not present, they are created.

ARGUMENTS

handle	CBF handle.
cell	Pointer to the array of 6 doubles for the cell parameters.
cell_esd	Pointer to the array of 6 doubles for the cell parameter esds.

2.4.52 cbf_get_reciprocal_cell

int cbf_get_reciprocal_cell (cbf_handle handle, double cell[6], double cell_esd[6] );

cbf_get_reciprocal_cell sets cell[0:2] to the double values of the reciprocal cell edge lengths a^*, b^* and c^* in Ångstroms^-1, cell[3:5] to the double values of the reciprocal cell angles α^*, β^* and γ^* in degrees, cell_esd[0:2] to the double values of the estimated strandard deviations of the reciprocal cell edge lengths a^*, b^* and c^* in Ångstroms^-1, cell_esd[3:5] to the double values of the estimated standard deviations of the the reciprocal cell angles α^*, β^* and γ^* in degrees.

The values returned are retrieved from the first row of the "cell" category. The value of "_cell.entry_id" is ignored.

If the "cell" category is present, but some of the values are missing, zeros are returned for the missing values.

ARGUMENTS

handle	CBF handle.
cell	Pointer to the destination array of 6 doubles for the reciprocal cell parameters.
cell_esd	Pointer to the destination array of 6 doubles for the reciprocal cell parameter esds.

Returns an error code on failure or 0 for success. No errors is returned for missing values if the "cell" category exists.

2.4.53 cbf_set_reciprocal_cell

int cbf_set_reciprocal_cell (cbf_handle handle, double cell[6], double cell_esd[6] );

cbf_set_reciprocal_cell sets the reciprocal cell parameters to the double values given in cell[0:2] for the reciprocal cell edge lengths a^*, b^* and c^* in Ångstroms^-1, the double values given in cell[3:5] for the reciprocal cell angles α^*, β^* and γ^* in degrees, the double values given in cell_esd[0:2] for the estimated strandard deviations of the reciprocal cell edge lengths a^*, b^* and c^* in Ångstroms, and the double values given in cell_esd[3:5] for the estimated standard deviations of the reciprocal cell angles α^*, β^* and γ^* in degrees.

The values are placed in the first row of the "cell" category. If no value has been given for "_cell.entry_id", it is set to the value of the "diffrn.id" entry of the current data block.

If the "cell" category is not present, it is created. If any of the necessary columns are not present, they are created.

ARGUMENTS

handle	CBF handle.
cell	Pointer to the array of 6 doubles for the reciprocal cell parameters.
cell_esd	Pointer to the array of 6 doubles for the reciprocal cell parameter esds.

2.4.54 cbf_compute_cell_volume

cbf_compute_cell_volume sets *volume to point to the volume of the unit cell computed from the double values in cell[0:2] for the cell edge lengths a, b and c in Ångstroms and the double values given in cell[3:5] for the cell angles α, β and γ in degrees.

ARGUMENTS

cell	Pointer to the array of 6 doubles giving the cell parameters.
volume	Pointer to the doubles for cell volume.

2.4.55 cbf_compute_reciprocal_cell

cbf_compute_reciprocal_cell sets rcell to point to the array of reciprocal cell parameters computed from the double values cell[0:2] giving the cell edge lengths a, b and c in Ångstroms, and the double values cell[3:5] giving the cell angles α, β and γ in degrees. The double values rcell[0:2] will be set to the reciprocal cell lengths a^*, b^* and c^* in Ångstroms^-1 and the double values rcell[3:5] will be set to the reciprocal cell angles α^*, β^* and γ^* in degrees.

ARGUMENTS

cell	Pointer to the array of 6 doubles giving the cell parameters.
rcell	Pointer to the destination array of 6 doubles giving the reciprocal cell parameters.
volume	Pointer to the doubles for cell volume.

2.4.56 cbf_get_orientation_matrix, cbf_set_orientation_matrix

int cbf_get_orientation_matrix (cbf_handle handle, double ub_matrix[9]);
int cbf_set_orientation_matrix (cbf_handle handle, double ub_matrix[9]);

cbf_get_orientation_matrix sets ub_matrix to point to the array of orientation matrix entries in the "diffrn" category in the order of columns:

cbf_set_orientation_matrix sets the values in the "diffrn" category to the values pointed to by ub_matrix.

ARGUMENTS

handle	CBF handle.
ubmatric	Source or destination array of 9 doubles giving the orientation matrix parameters.

2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes

int cbf_get_bin_sizes(cbf_handle handle, unsigned int element_number, double * slowbinsize, double * fastbinsize);
int cbf_set_bin_sizes(cbf_handle handle, unsigned int element_number, double slowbinsize_in,double fastbinsize_in);

cbf_get_bin_sizes sets slowbinsize to point to the value of the number of pixels composing one array element in the dimension that changes at the second-fastest rate and fastbinsize to point to the value of the number of pixels composing one array element in the dimension that changes at the fastest rate for the dectector element with the ordinal element_number. cbf_set_bin_sizes sets the the pixel bin sizes in the "array_intensities" category to the values of slowbinsize_in for the number of pixels composing one array element in the dimension that changes at the second-fastest rate and fastbinsize_in for the number of pixels composing one array element in the dimension that changes at the fastest rate for the dectector element with the ordinal element_number.

In order to allow for software binning involving fractions of pixels, the bin sizes are doubles rather than ints.

ARGUMENTS

handle	CBF handle.
element_number	The number of the detector element counting from 0 by order of appearance in the "diffrn_data_frame" category.
slowbinsize	Pointer to the returned number of pixels composing one array element in the dimension that changes at the second-fastest rate.
fastbinsize	Pointer to the returned number of pixels composing one array element in the dimension that changes at the fastest rate.
slowbinsize_in	The number of pixels composing one array element in the dimension that changes at the second-fastest rate.
fastbinsize_in	The number of pixels composing one array element in the dimension that changes at the fastest rate.

2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise, cbf_get_reference_poise

int cbf_get_axis_poise(cbf_handle handle, double ratio, double * vector1, double * vector2, double * vector3, double * offset1, double * offset2, double * offset3, double * angle, const char * axis_id, const char * frame_id);
int cbf_get_goniometer_poise(cbf_goniometer goniometer, double ratio, double * vector1, double * vector2, double * vector3, double * offset1, double * offset2, double * offset3, double * angle);
int cbf_get_axis_reference_poise(cbf_handle handle, double * vector1, double * vector2, double * vector3, double * offset1, double * offset2, double * offset3, const char * axis_id);

cbf_get_axis_poise sets vector1, vector2, vector3 to point to the components of the axis vector for axis axis_id, offset1, offset2, offset3 to point to the components of the axis base offset vector for axis axis_id, and angle to point to the angle of rotation of axis axis_id after application of the axis settings for frame frame_id, using ratio, a value between 0 and 1, indicating how far into the internal motion in the frame to go. If frame_id is the string ".", the first frame found is used. If there is more than one frame, which frame will be found is indeterminate. If frame_id is NULL, the overall setting for the scan are used, rather than those for any particular frame. The vector and offset reported are the reference vector and offset of the axis axis_id transformed by application of all motions of the axes on which axis_id depends.

cbf_get_goniometer_poise vector1, vector2, vector3 to point to the components of the axis vector for the goniometer axis, offset1, offset2, offset3 to point to the components of the axis base offset vector for the goniometer axis, and angle to point to the angle of rotation of the goniometer axis after application of all axis settings in the goniometer deriving the vector, offset and angle from the resulting matrix. Calculation of the vector is indeterminate if the angle is zero.

cbf_get_axis_reference_poise sets vector1, vector2, vector3 to point to the components of the axis vector for axis axis_id, offset1, offset2, offset3 to point to the components of the axis base offset vector for axis axis_id unmodified by axis rotations. Any of the pointers may be specified as NULL.

ARGUMENTS

handle	CBF handle.
ratio	A number between 0 and 1 indication how far into the frame to go
vector1	Pointer to the first component of the axis vector
vector2	Pointer to the second component of the axis vector
vector3	Pointer to the third component of the axis vector
offset1	Pointer to the first component of the axis offset
offset2	Pointer to the second component of the axis offset
offset3	Pointer to the third component of the axis offset
angle	Pointer to the rotation angle
axis_id	The specified axis
frame_id	The specified frame
positioner	CBF goniometer

2.4.59 cbf_airy_disk, cbf_airy_disk_volume

int cbf_airy_disk(double x, double y, double cenx, double ceny, double volume, double fwhm, double * value);
int cbf_airy_disk_volume(double xlo, double ylo, double xhi, double yhi, double cenx, double ceny, double volume, double fwhm, double * volumeout);

cbf_airy_disk sets value to point to the value taken at (x,y) of an truncated Airy function approximation to a point-spread function of total included volume volume and full width at half max fwhm centered on (cenx, ceny).

cbf_airy_disk_volume sets to point to the integral in the box with diagonal corners (xlo, ylo) and of (xhi, yhi) of a truncated Airy function approximation to a point-spread function of total included volume volume and full width at half max fwhm centered on (cenx, ceny).

The Airy function used is an 8-digit approximation up to the first minimum, after which it is forced to zero, so it cannot be used to simulate diffraction rings.

ARGUMENTS

x	the x-coordinate of a point in the real plane
y	the y-coordinate of a point in the real plane
xlo	the x-coordinate of a point in the real plane marking the left bound of integration
ylo	the y-coordinate of a point in the real plane marking the bottom bound of integration
xhi	the x-coordinate of a point in the real plane marking the right bound of integration
yhi	the y-coordinate of a point in the real plane marking the top bound of integration
cenx	the x-coordinate of a point in the real plane marking the PSF center
ceny	the y-coordinate of a point in the real plane marking the PSF center
volume	the total volume of the PSF
fwhm	the full-width at half max of the PSF
value	Pointer to the value of the Airy function
volumeout	Pointer to the value of the integral/TR>

2.5 F90 function interfaces

At the suggestion of W. Kabsch, Fortran 90/95 routines have been added to CBFlib. As of this writing code has been written to allow the reading of CBF_BYTE_OFFSET, CBF_PACKED and CBF_PACKED_V2 binary images. This code has been gather into FCBlib (Fortran Crystallographic Binary library) as lib/libfcb.

In general, most of the FCBlib functions return 0 for normal completion and a non-zero value in case of an error. In a few cases, such as FCB_ATOL_WCNT and FCB_NBLEN_ARRAY in order to conform to the conventions for commonly used C-equivalent functions, the function return is the value being computed.

For each function, an interface is given to be included in the declarations of your Fortran 90/95 code. Some functions in FCBlIB are not intended for external use and are subject to change: FCB_UPDATE_JPA_POINTERS_I2, FCB_UPDATE_JPA_POINTERS_I4, FCB_UPDATE_JPA_POINTERS_3D_I2, FCB_UPDATE_JPA_POINTERS_3D_I4 and CNT2PIX. These names should not be used for user routines.

The functions involving reading of a CBF have been done strictly in Fortran without the use of C code. This has required some compromises and the use of direct access I/O. Rather than putting the buffer and its control variables into COMMON these are passed as local arguments to make the routines inherently 'threadsafe' in a parallel programming environment. Note also, that a reading error could occur for the last record if it does not fill a full block. The code is written to recover from end-of-record and end-of-file errors, if possible. On many modern system, no special action is required, but on some systems it may be necessary to make use of the padding between the end of binary data and the terminal MIME boundary marker in binary sections. To ensure maximum portability of CBF files, a padding of 4095 bytes is recommended. Existing files without padding can be converted to files with padding by use of the new -p4 option for cif2cbf.

2.5.1 FCB_ATOL_WCNT

FCB_ATOL_WCNT converts INTEGER(1) bytes in ARRAY of N bytes to an INTEGER(8) value returned as the function value. The number of bytes of ARRAY actually used before encountering a character not used to form the number is returned in CNT.

The scan stops at the first byte in ARRAY that cannot be properly parsed as part of the integer result.

ARGUMENTS

ARRAY	The array of INTEGER(1) bytes to be scanned
N	The INTEGER size of ARRAY
CNT	The INTEGER size of the portion of ARRAY scanned.

Returns the INTEGER(8) value derived from the characters ARRAY(1:CNT) scanned.

2.5.2 FCB_CI_STRNCMPARR

The function FCB_CI_STRNCMPARR compares up to LIMIT characters of character string STRING and INTEGER(1) byte array ARRAY of dimension N in a case-insensitive manner, returning 0 for a match.

ARGUMENTS

STRING	A character string
ARRAY	The array of INTEGER(1) bytes to be scanned
N	The INTEGER size of ARRAY
N	The INTEGER limit on the number of characters to consider in the comparison

2.5.3 FCB_EXIT_BINARY

The function FCB_EXIT_BINARY is used to skip from the end of a binary section past any padding to the end of the text section that encloses the binary section. The values of the arguments must be consistent with those in the last call to FCB_NEXT_BINARY

ARGUMENTS

TAPIN	The INTEGER Fortran device unit number assigned to image file.
LAST_CHAR	The last character (as an INTEGER(1) byte) read.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN
PADDING	The INTEGER(8) number of bytes of padding after the binary data and before the closing MIME boundary.

Returns 0 if the function is successful. Returns whatever non-zero error value is reported by FCB_READ_LINE if a necessary next line cannot be read.

2.5.4 FCB_NBLEN_ARRAY

The function FCB_NBLEN_ARRAY returns the trimmed length of the INTEGER(1) byte array ARRAY of dimension ARRAYLEN after removal of trailing ASCII blanks, horizontal tabs (Z'09'), newlines (Z'0A') and carriage returns (Z'0D'). The resulting length may be zero.

ARGUMENTS

ARRAY	The array of bytes for which the trimmed length is required.
ARRAYLEN	The dimension of the array of bytes to be scanned.

2.5.5 FCB_NEXT_BINARY

The function FCB_NEXT_BINARY skips to the start of the next binary section in the image file on unit TAPIN leaving the file positioned for a subsequent read of the image data. The skip may prior to the text field that contains the binary section. When the text filed is reached, it will be scanned for a MIME boundary marker, and, if it is found the subsequence MIME headers will be used to populate the arguments ENCODING, SIZE, ID, DIGEST, COMPRESSION, BITS, VORZEICHEN,REELL, BYTEORDER, DIMOVER, DIM1, DIM2,DIM3, PADDING.

The value returned in ENCODING is taken from the MIME header Content-Transfer-Encoding as an INTEGER. It is returned as 0 if not specified. The reported value is one of the integer values ENC_NONE (Z'0001') for BINARY encoding, ENC_BASE64 (Z'0002') for BASE64 encoding, ENC_BASE32K (Z'0004') for X-BASE32K encoding, ENC_QP (Z'0008') for QUOTED-PRINTABLE encoding, ENC_BASE10 (Z'0010') for BASE10 encoding, ENC_BASE16 (Z'0020') for BASE16 encoding or ENC_BASE8 (Z'0040') for BASE8 encoding. At this time FCBlib only supports ENC_NONE BINARY encoding.

The value returned in SIZE is taken from the MIME header X-Binary-Size as an INTEGER. It is returned as 0 if not specified.

The value returned in ID is taken from the MIME header X-Binary-ID as an INTEGER. It is returned as 0 if not specified.

The value returned in DIGEST is taken from the MIME header Content-MD5. It is returned as a character string. If no digest is given, an empty string is returned.

The value returned in COMPRESSION is taken from the MIME header Content-Type in the conversions parameter. The reported value is one of the INTEGER values CBF_CANONICAL (Z'0050'), CBF_PACKED (Z'0060'), CBF_PACKED_V2 (Z'0090'), CBF_BYTE_OFFSET (Z'0070'), CBF_PREDICTOR (Z'0080'), CBF_NONE (Z'0040'). Two flags may be combined with CBF_PACKED or CBF_PACKED_V2: CBF_UNCORRELATED_SECTIONS (Z'0100') or CBF_FLAT_IMAGE (Z'0200'). At this time FCBlib does not support CBF_PREDICTOR or CBF_NONE compression.

The values returned in BITS, VORZEICHEN and REELL are the parameters of the data types of the elements. These values are taken from the MIME header X-Binary-Element-Type, which has values of the form "signed BITS-bit integer", "unsigned BITS-bit integer", "signed BITS-bit real IEEE" or "signed BITS-bit complex IEEE". If no value is given, REELL is reported as -1. If the value in one of the integer types, REELL is reported as 0. If the value is one of the real or complex types, REELL is reported as 1. In the current release of FCBlib only the integer types for BITS equal to 16 or 32 are supported.

The value returned in BYTEORDER is the byte order of the data in the image file as reported in the MIME header. The value, if specified, will be either the character string "LITTLE_ENDIAN" or the character string "BIG_ENDIAN". If no byte order is specified, "LITTLE_ENDIAN" is reported. This value is taken from the MIME header X-Binary-Element-Byte-Order. As of this writing, CBFlib will not generate "BIG_ENDIAN" byte-order files. However, both CBFlib and FCBlib read "LITTLE_ENDIAN" byte-order files, even on big-endian machines.

The value returned in DIMOVER is the overall number of elements in the image array, if specified, or zero, if not specified. This value is taken from the MIME header X-Binary-Number-of-Elements. The values returned in DIM1, DIM2 and DIM3 are the sizes of the fastest changing, second fastest changing and third fastest changing dimensions of the array, if specified, or zero, if not specified. These values are taken from the MIME header X-Binary-Size-Fastest-Dimension, X-Binary-Size-Second-Dimension and X-Binary-Size-Third-Dimension respectively.

The value returned in PADDING is the size of the post-data padding, if any, if specified or zero, if not specified. The value is given as a count of octets. This value is taken from the MIME header X-Binary-Size-Padding.

ARGUMENTS

TAPIN	The INTEGER Fortran device unit number assigned to image file.
LAST_CHAR	The last character (as an INTEGER(1) byte) read.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN
ENCODING	INTEGER type of encoding for the binary section as reported in the MIME header.
ID	INTEGER binary identifier as reported in the MIME header.
SIZE	INTEGER size of compressed binary section as reported in the MIME header.
DIGEST	The MD5 message digest as reported in the MIME header.
COMPRESSION	INTEGER compression method as reported in the MIME header.
BITS	INTEGER number of bits in each element as reported in the MIME header.
VORZEICHEN	INTEGER flag for signed or unsigned elements as reported in the MIME header. Set to 1 if the elements can be read as signed values, 0 otherwise.
REELL	INTEGER flag for real elements as reported in the MIME header. Set to 1 if the elements can be read as REAL
BYTEORDER	The byte order as reported in the MIME header.
DIM1	Pointer to the destination fastest dimension.
DIM2	Pointer to the destination second fastest dimension.
DIM3	Pointer to the destination third fastest dimension.
PADDING	Pointer to the destination padding size.

2.5.6 FCB_OPEN_CIFIN

The function FCB_OPEN_CIFIN opens the CBF image file given by the file name in the character string FILNAM on the logical unit TAPIN. The calling routine must provide an INTEGER(1) byte buffer BUFFER of some appropriate INTEGER size FCB_BYTES_IN_REC. The size must be chosen to suit the machine, but in most cases, 4096 will work. The values returned in LAST_CHAR, BYTE_IN_FILE, and REC_IN_FILE are for use in subsequent FCBlib I/O routines.

The image file will be checked for the initial characters "###CBF: ". If there is no match the error value CBF_FILEREAD is returned.

ARGUMENTS

FILNAM	The character string name of the image file to be opened.
TAPIN	The INTEGER Fortran device unit number assigned to image file.
LAST_CHAR	The last character (as an INTEGER(1) byte) read.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN

2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2, FCB_DECOMPRESS_PACKED_3D_I4

The functions FCB_DECOMPRESS_PACKED_I2, FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2 and FCB_DECOMPRESS_PACKED_3D_I4, decompress images compress according the the CBF_PACKED or CBF_PACKED_V2 compression described in section 3.3.2 on J. P. Abrahams CCP4 packed compression.

The relevant function should be called immediately after a call to FCB_NEXT_BINARY, using the values returned by FCB_NEXT_BINARY to select the appropriate version of the function.

ARGUMENTS

ARRAY	The array to receive the image
NELEM	The INTEGER(8) number of elements to be read
NELEM_READ	The INTEGER(8) returned value of the number of elements actually read
ELSIGN	The INTEGER value of the flag for signed (1) OR unsigned (0) data
COMPRESSION	The compression of the image
DIM1	The INTEGER(8) value of the fastest dimension of ARRAY
DIM2	The INTEGER(8) value of the second fastest dimension
DIM3	The INTEGER(8) value of the third fastest dimension
TAPIN	The INTEGER Fortran device unit number assigned to image file.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN

2.5.8 FCB_READ_BITS

The function FCB_READ_BITS gets the integer value starting at BYTE_IN_FILE from file TAPIN continuing through BITCOUNT bits, with sign extension. BYTE_IN_FILE is left at the entry value and not incremented. The resulting, sign-extended integer value is stored in the INTEGER(4) array IINT of dimension LINT with the least significant portion in IINT(1).

ARGUMENTS

TAPIN	The INTEGER Fortran device unit number assigned to image file.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
BCOUNT	The INTEGER count of bits remaining unused from the last call to FCB_READ_BITS.
BBYTE	The INTEGER(1) byte containing the unused bits from the last call to FCB_READ_BITS.
BITCOUNT	The INTEGER count of the number of bits to be extracted from the image file.
IINT	The INTEGER(4) array into which to store the value extracted from the image file.
LINT	The INTEGER length of the array IINT.

Returns 0 if the function is successful. Because of the use of direct access I/O in blocks of size FCB_BYTES_IN_REC the precise location of the end of file may not be detected.

2.5.9 FCB_READ_BYTE

The function FCB_READ_BYTE reads the byte at the position BYTE_IN_FILE in the image file TAPIN. The first byte in the file is at BYTE_IN_FILE = 1. BYTE_IN_FILE should be set to the desired value before the call to the function and is not incremented within the function.

The function attempts to suppress the error caused by a read of a short last record, and in most systems cannot determine the exact location of the end of the image file, returning zero bytes until the equivalent of a full final record has been read.

ARGUMENTS

TAPIN	The INTEGER Fortran device unit number assigned to image file.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
IBYTE	The INTEGER(1) byte found in the image file at the byte position BYTE_IN_FILE.

Returns 0 if the function is successful. Because of the use of direct access I/O in blocks of size FCB_BYTES_IN_REC the precise location of the end of file may not be detected.

2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4, FCB_READ_IMAGE_3D_I2, FCB_READ_IMAGE_3D_I4

The function FCB_READ_IMAGE_I2 reads a 16-bit twos complement INTEGER(2) 2D image. The function FCB_READ_IMAGE_I4 read a 32-bit twos complement INTEGER(4) 2D image. The function FCB_READ_IMAGE_3D_I2 reads a 16-bit twos complement INTEGER(2) 3D image. The function FCB_READ_IMAGE_3D_I4 reads a 32-bit twos complement INTEGER(4) 3D image. In each case the image is compressed either by a BYTE_OFFSET algorithm by W. Kabsch based on a proposal by A. Hammersley or by a PACKED algorithm by J. P. Abrahams as used in CCP4, with modifications by P. Ellis and H. J. Bernstein.

The relevant function automatically first calls FCB_NEXT_BINARY to skip to the next binary section and then starts to read. An error return will result if the parameters of this call are inconsistent with the values in MIME header.

ARGUMENTS

ARRAY	The array to receive the image
NELEM	The INTEGER(8) number of elements to be read
NELEM_READ	The INTEGER(8) returned value of the number of elements actually read
ELSIGN	The INTEGER value of the flag for signed (1) OR unsigned (0) data
COMPRESSION	The actual compression of the image
DIM1	The INTEGER(8) value of the fastest dimension of ARRAY
DIM2	The INTEGER(8) value of the second fastest dimension
DIM3	The INTEGER(8) value of the third fastest dimension
TAPIN	The INTEGER Fortran device unit number assigned to image file.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN

2.5.11 FCB_READ_LINE

The function FCB_READ_LINE reads successive bytes into the INTEGER(1) byte array LINE of dimension N), stopping at N bytes or the first error or the first CR (Z'0D') or LF (Z'0A'), whichever comes first. It discards an LF after a CR. The variable LAST_CHAR is checked for the last character from the previous line to make this determination.

The actual number of bytes read into the line, not including any terminal CR or LF is stored in LINELEN.

ARGUMENTS

TAPIN	The INTEGER Fortran device unit number assigned to image file.
LAST_CHAR	The INTEGER(1) byte holding the ASCII value of the last character read for each line read.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN.
LINE	The INTEGER(1) array of length N to hold the line to be read from TAPIN.
N	The INTEGER dimension of LINE.
LINELEN	The INTEGER number of characters read into LINE.

2.5.12 FCB_READ_XDS_I2

The function FCB_READ_XDS_I2 read a 32-bit integer twos complement image into a 16-bit INTEGER(2) XDS image using the CBF_BYTE_OFFSET, CBF_PACKED or CBF_PACKED_V2 compressions for the 32-bit data. The BYTE_OFFSET algorithm is a variant of the September 2006 version by W. Kabsch which was based on a suggestion by A. Hammersley and which was further modified by H. Bernstein.

The file named FILNAM is opened on the logical unit TAPIN and FCB_NEXT_BINARY is used to skip to the next binary image. The binary image is then decompressed to produce an XDS 16-bit integer image array IFRAME which is NX by NY. The dimensions must agree with the dimensions specified in MIME header.

The conversion from a 32-bit integer I32 to 16-bit XDS pixel I16 is done as per W. Kabsch as follows: The value I32 is limited to the range -1023 ≤ I32 ≤ 1048576. If I32 is outside that range it is truncated to the closer boundary. The generate I16, the 16-bit result, if I32 > 32767, it is divided by 32 (producing a number between 1024 and 32768), and then negated (producing a number between -1024 and -32768).

For CBF_BYTE_OFFSET this conversion can be done on the fly directly into the target array IFRAME, but for the CBF_PACKED or CBF_PACKED_V2, the full 32 bit precision is needed during the decompression, forcing the use of an intermediate INTEGER(4) array JFRAME to hold the 32-bit image in that case.

ARGUMENTS

FILNAM	The character string name of the image file to be opened.
TAPIN	The INTEGER Fortran device unit number assigned to image file.
NX	The INTEGER fast dimension of the image array.
NY	The INTEGER slow dimension of the image array.
IFRAME	The INTEGER(2) XDS image array.
JFRAME	The INTEGER(4) 32-bit image scratch array needed for CBF_PACKED or CBF_PACKED_V2 images.

Returns 0 if the function is successful, CBF_FORMAT (=1) if it cannot handle this CBF format (not implemented), -1 if it cannot determine endian architecture of this machine, -2: if it cannot open the image file, -3: if it finds the wrong image format and -4 if it cannot read the image.

2.5.13 FCB_SKIP_WHITESPACE

The function FCB_SKIP_WHITESPACE skips forward on the current INTEGER(1) byte array LINE of size N with valid data in LINE(1:LINELEN) from the current position ICUR moving over MIME header whitespace and comments, reading new lines into LINE if needed. The flag FRESH_LINE indicates that a fresh line should be read on entry.

ARGUMENTS

TAPIN	The INTEGER Fortran device unit number assigned to image file.
LAST_CHAR	The INTEGER(1) byte holding the ASCII value of the last character read for each line read.
FCB_BYTES_IN_REC	The INTEGER number of bytes in a record.
BYTE_IN_FILE	The INTEGER byte (counting from 1) of the byte to read.
REC_IN_FILE	The INTEGER record number (counting from 1) of next record to read.
BUFFER	The INTEGER(1) array of length FCB_BYTES_IN_REC to hold the appropriate record from TAPIN.
LINE	The INTEGER(1) array of length N to hold the line to be read from TAPIN.
N	The INTEGER dimension of LINE.
LINELEN	The INTEGER number of characters read into LINE.
ICUR	The INTEGER position within the line.
FRESH_LINE	The INTEGER flag that a fresh line is needed.

2.6 HDF5 abstraction layer and convenience functions

The HDF5 abstraction layer mostly follows the HDF5 naming convention of H5Xfunction_name, where X is usually a single letter identifying the section of the API that the function resides in. A cbf_ prefix is used on all functions to avoid naming conflicts and make it clear that all these functions use the CBFlib error handling method whenever an error may occur.

The main purpose of this API is to not to reimplement the HDF5 API, but to make common HDF5-related tasks easier when working with HDF5 files within CBFlib. The API therefore doesn't attempt to cover every possible use of HDF5, but to simplify common tasks. Use of the HDF5 API is not unexpected in library or user code, but functions in this section should be preferred in order to reduce development time and the amount of debugging required. A relatively comprehensive test program is provided, this should be used to verify that the functions in this section of the API are performing as expected and can be used as a source of example code.

This section describes functions available for working with:

Attributes:
Datasets:
Files:
- 2.6.21 cbf_H5Fopen
- 2.6.22 cbf_H5Fclose
Groups:
Identifiers:
- 2.6.27 cbf_H5Ivalid
Objects:
- 2.6.28 cbf_H5Ocmp
- 2.6.29 cbf_H5Ofree
Dataspaces:
- 2.6.30 cbf_H5Screate
- 2.6.31 cbf_H5Sfree
Datatypes:
- 2.6.32 cbf_H5Tcreate_string
- 2.6.33 cbf_H5Tfree

Rank of a dataset

Where a rank is required it must be equal to the length of the dim, max & chunk parameters, if they are given, and should be:

0, for scalar data
1, for vector data
2, for matrix data
3, for volume data
etc...

The maximum rank is defined by the HDF5 library, a negative rank makes no sense and will often be treated as an error.

HDF5-specific datatypes

Any type parameters defining types for data stored in a file should usually be a value returned by cbf_H5Tcreate_string or one of the standard or IEEE types:

`H5T_STD_I8LE`	`H5T_STD_I16LE`	`H5T_STD_I32LE`	`H5T_STD_I64LE`
`H5T_STD_U8LE`	`H5T_STD_U16LE`	`H5T_STD_U32LE`	`H5T_STD_U64LE`
`H5T_STD_I8BE`	`H5T_STD_I16BE`	`H5T_STD_I32BE`	`H5T_STD_I64BE`
`H5T_STD_U8BE`	`H5T_STD_U16BE`	`H5T_STD_U32BE`	`H5T_STD_U64BE`
`H5T_IEEE_F32LE`	`H5T_IEEE_F64LE`	`H5T_IEEE_F32BE`	`H5T_IEEE_F64BE`

Any type parameters defining types for data stored in memory should usually be a value returned by cbf_H5Tcreate_string or one of the native types:

`H5T_NATIVE_SCHAR`	`H5T_NATIVE_SHORT`	`H5T_NATIVE_INT`	`H5T_NATIVE_LONG`	`H5T_NATIVE_LLONG`
`H5T_NATIVE_UCHAR`	`H5T_NATIVE_USHORT`	`H5T_NATIVE_UINT`	`H5T_NATIVE_ULONG`	`H5T_NATIVE_ULLONG`
`H5T_NATIVE_FLOAT`	`H5T_NATIVE_DOUBLE`	`H5T_NATIVE_LDOUBLE`

Functions are rarely (if ever) limited to the above values, and can take any valid HDF5 datatype. The above is not a complete list of all available types, check the HDF5 documentation for such a list if you need one.

Comparing data

Some of the functions in this section will require a comparison function and some comparison parameters to be provided. The function should return zero if the data in the two arrays are considered equal and non-zero otherwise, note that this is the same as C's strcmp(). The signature of the comparison functions used here is:

int compare (const void * expected, const void * existing, size_t length, const void * params)

This will be called with:

Type	Name	Description
const void *	expected	A pointer to the array of requested values that was passed to the function.
const void *	existing	An array of existing values read from the object.
size_t	length	The length of the `expected` and `existing` arrays.
const void *	params	A pointer to the comparison parameters which were passed to the calling function.

The comparison parameters allow more complex comparisons to be performed, such as a check that the numbers are 'close enough' as determined by some variable measure of closeness. It is the caller's responsibility to ensure that the comparison function is appropriate for the type of data expected and that params is of the appropriate type for the comparison function. The parameters expected and existing should normally be cast to the appropriate type before being used.

An example function for comparing ints, taken from the implementation of CBFlib:


          /*
Compare two arrays of ints.
Most parameters are defined as being 'const' even though
the expected signature allows them to be mutable.
*/
int cmp_int
    (const void * const expected,
     const void * const existing,
     size_t length,
     const void * const params)
{
	/*
    Cast the array pointers to the appropriate type, preserving the const-ness of the data.
    I won't be using any parameters for this comparison, so just ignore that argument.
	*/
    const int * A = expected;
    const int * B = existing;

	/*
    Iterate through the arrays comparing each element and decrementing a counter.
    If any are not equal the loop will exit early with length being non-zero.
	*/
    while (length && *A++ == *B++) --length;

	/*
    Return a value indicating whether the arrays are equal.
	*/
    return length;
}

Some older functions use a simpler 3-argument comparison function, which doesn't have a parameter that can be used to pass some extra information to or retrieve information from the function.

2.6.1 cbf_H5Acreate

Create a new attribute.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Acreate (const hid_t location, hid_t *const attr, const char *const name, const hid_t type, const hid_t space)

DESCRIPTION

Creates a new attribute of the object location with name given by name, optionally returning it in the attr variable. An error will occur if a similarly named attribute already exists.

ARGUMENTS

location	The hdf5 group/file in which to put the attribute.
attr	A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left untouched.
name	The name of the existing/new dataset.
type	The type of data to be stored in the attribute.
space	The dataspace of the attribute.

RETURN VALUE

An error code.

SEE ALSO

2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.2 cbf_H5Afind

Try to locate an existing attribute.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Afind (const hid_t location, hid_t *const attr, const char *const name, const hid_t type, const hid_t space)

DESCRIPTION

Checks for the existance of an attribute with the given name at location with a datatype of type and dataspace of space. Will return CBF_NOTFOUND if it cannot be found, or open it if it already exists.

If type is not a datatype then no check of the attribute datatype will be done. If space is not a dataspace then no checks of the attribute dataspace wil be done.

ARGUMENTS

location	The hdf5 group/file in which to put the attribute.
attr	A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left untouched.
name	The name of the existing/new attribute.
type	The type of data stored in the attribute, or an invalid identifier if it should not be checked.
space	The dataspace of the attribute, or an invalid identifier if it should not be checked.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.3 cbf_H5Aread

Read an entire attribute from a file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Aread (const hid_t attr, const hid_t type, void *const buf)

DESCRIPTION

Reads all of the data from attr into buf, which should have been allocated as the native type indicated by mem_type.

ARGUMENTS

attr	A valid hdf5 handle for an attribute.
type	The type of data in memory.
buf	The location where the data is to be stored.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.4 cbf_H5Aread_string

Read an entire string attribute from a file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Aread_string (const hid_t attr, const char **const val)

DESCRIPTION

Read a string attribute into memory, returning a pointer that must be free'd by the caller in val.

ARGUMENTS

attr	The attribute to read from.
val	A pointer to a place the string may be stored.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.5 cbf_H5Awrite

Write an entire attribute to a file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Awrite (const hid_t attr, const hid_t type, void *const buf)

DESCRIPTION

Writes all of the data from buf, which should contain data if the type indicated by mem_type, into attr.

ARGUMENTS

attr	A valid hdf5 handle for an attribute.
type	The type of data in memory.
buf	The address of the data to be written.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.6 cbf_H5Arequire_cmp2

Check for an attribute with the given space/type/value, or set one if it doesn't exist.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Arequire_cmp2 (const hid_t ID, const char *const name, const int rank, const hsize_t *const dim, const hid_t fileType, const hid_t memType, const void *const value, void *const buf, int(*cmp)(const void *, const void *, size_t))

DESCRIPTION

Checks the existance of an attribute of the given name, size, type and value. Equal value is determined by a custom comparison function which may use some extra data for more sophisticated tests. A new attribute with the given properties will be created if none currently exist, the function will fail if an incompatible attribute exists.

ARGUMENTS

ID	The HDF5 object that the attribute will be applied to.
name	The name of the attribute.
rank	The number of dimensions of the attribute data, 0 for scalar data.
dim	The length of each dimension, not used for scalar data.
fileType	The HDF5 type of the attribute data in the file.
memType	The HDF5 type of the attribute data in memory.
value	The data to be written to the attribute.
buf	A buffer to be used when reading an existing attribute of the same size.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.7 cbf_H5Arequire_cmp2_ULP

Check for an attribute with the given space/type/value, or set one if it doesn't exist.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Arequire_cmp2_ULP (const hid_t ID, const char *const name, const int rank, const hsize_t *const dim, const hid_t fileType, const hid_t memType, const void *const value, void *const buf, int(*cmp)(const void *, const void *, size_t, const void *), const void *const cmp_params)

DESCRIPTION

ARGUMENTS

ID	The HDF5 object that the attribute will be applied to.
name	The name of the attribute.
rank	The number of dimensions of the attribute data, 0 for scalar data.
dim	The length of each dimension, not used for scalar data.
fileType	The HDF5 type of the attribute data in the file.
memType	The HDF5 type of the attribute data in memory.
value	The data to be written to the attribute.
buf	A buffer to be used when reading an existing attribute of the same size.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.
cmp_params	A pointer to a data structure which may be used by the comparison function.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.8 cbf_H5Arequire_string
2.6.9 cbf_H5Afree

2.6.8 cbf_H5Arequire_string

Check for a scalar string attribute with a given value, or set one if it doesn't exist.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Arequire_string (const hid_t location, const char *const name, const char *const value)

DESCRIPTION

Forwarding function that calls cbf_H5Arequire_cmp2_ULP with the appropriate arguments to compare two strings. The strcmp function is used for string comparison, with a small wrapper to verify array length:


          /** a possible implementation of a function to compare two strings for equality */
static int cmp_string
    (const void * const a,
     const void * const b,
     const size_t N,
     const void * const params)
{
	/* first ensure the arrays have one element each */
    if (1 != N) return 1;
	/* then forward to 'strcmp' for the actual comparison */
    else return strcmp(a,b);
}

ARGUMENTS

location	HDF5 object to which the string attribute should/will belong.
name	The name of the attribute.
value	The value which the attribute should/will have.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.9 cbf_H5Afree

2.6.9 cbf_H5Afree

Close a HDF5 attribute.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Afree (const hid_t ID)

DESCRIPTION

Attempt to close an attribute, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 attribute to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.1 cbf_H5Acreate
2.6.2 cbf_H5Afind
2.6.3 cbf_H5Aread
2.6.4 cbf_H5Aread_string
2.6.5 cbf_H5Awrite
2.6.6 cbf_H5Arequire_cmp2
2.6.7 cbf_H5Arequire_cmp2_ULP
2.6.8 cbf_H5Arequire_string

2.6.10 cbf_H5Dcreate

Creates a new dataset in the given location.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dcreate (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const dim, const hsize_t *const max, const hsize_t *const chunk, const hid_t type)

DESCRIPTION

The dataset parameter gives a location to store the dataset for use by the caller, for example to add an attribute to it. If non-zero the returned handle MUST be free'd by the caller with cbf_H5Dfree.

The dimensions of the dataset to create are given in dim. The maximum extents of the dataset are given in max, which uses the values in dim as defaults if set to a null pointer. Each element of max must be at least as large as the corresponding element of dim. The dataset created will be a fixed-size dataset unless one of the elements of max is set to H5S_UNLIMITED.

A chunk size must be given in the chunk argument if any element of max is set to H5S_UNLIMITED or is greater than the corresponding element of dim. If the dataset should not be chunked then a null pointer should be given.

The dim, max and chunk arrays - if given - must each contain rank elements.

This function will fail if a link with the same name already exists in location.

ARGUMENTS

location	The hdf5 group/file in which to put the dataset.
dataset	An optional pointer to a location where the dataset handle should be stored.
name	The name of the new dataset.
rank	The rank of the data.
dim	The dimensions of the dataset to create. Unused if `rank == 0`.
max	The maximum size of each dimension. Unused if `rank == 0`.
chunk	The chunk size for the dataset.
type	The type of each data element in the file.

RETURN VALUE

An error code.

SEE ALSO

2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.11 cbf_H5Dfind2

Look for a dataset with the given properties.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dfind2 (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const max, hsize_t *const buf, const hid_t type)

DESCRIPTION

Returns CBF_NOTFOUND without modifying dataset if no dataset exists and fails without modifying dataset if one with different properties exists. A dataset will be 'found' if it has the same name and a maximum size which is at least as big as the size requested in max.

A buffer of rank elements pointed to by buf may be used to store the array of maximum extents for a potentially matching dataset, in order to avoid the use of malloc & free for very small amounts of memory.

Use as:


          /* Get the return code from the function call, */
const int found = cbf_H5Dfind(location, &dataset, ...);
/* and check what it was: */
if (CBF_SUCCESS==found) {
	/* A dataset already existed and I have a handle for it: */
    use_existing_dataset(dataset);
} else if (CBF_NOTFOUND==found) {
	/* No matching dataset existed, so I can create one: */
	cbf_H5Dcreate(location, &dataset, ...);
    use_new_datset(dataset);
} else {
	/*
    The function call failed, do something with the error.
    In this case, store it for later use and print a message.
	*/
    error |= found;
     cbf_debug_print(cbf_strerror(error));
}
/* clean up: */
cbf_H5Dfree(dataset);

ARGUMENTS

location	The hdf5 group/file in which to put the dataset.
dataset	A pointer to a HDF5 object identifier that is set to the location of a valid object if the function succeeds, otherwise is left in an undefined state.
name	The name of the existing/new dataset.
rank	The rank of the data, must be equal to the length of the `max` and `buf` arrays, if they are given.
max	The (optional) maximum size of each dimension, pointer or an array of length `rank` where `0 <= max[i] <= H5S_UNLIMITED` for `i = [0, rank)`, unused if `rank == 0`.
buf	An optional buffer with `rank` elements which may be used to store the current maximum dimensions of a potential match to avoid a malloc/free call.
type	The type of each data element in the file. If an invalid type is given a dataset of any type may be returned.

RETURN VALUE

CBF_SUCCESS if a matching dataset was found, CBF_NOTFOUND if nothing with the same name was found, some other error code otherwise.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.12 cbf_H5Drequire

Ensure that a dataset exists, returning a handle to an existing dataset or creating a new dataset if needed.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire (const hid_t location, hid_t *const dataset, const char *const name, const int rank, const hsize_t *const max, const hsize_t *const chunk, hsize_t *const buf, const hid_t type)

DESCRIPTION

Ensure a dataset of the given rank exists and can hold at least as many elements as specified in max. If no dataset exists then one will be created with dimensions of [0, 0, ... 0]. cbf_H5Dfind and cbf_H5Dcreate are used in the implementation of this function.

An existing dataset may be found using cbf_H5Dfind2(location, dataset, name, rank, max, buf, type). If no dataset can be found then a dataset will be created by setting each element of a buffer of length rank to zero and using cbf_H5Dcreate(location, dataset, name, rank, buffer, max, chunk, type). A buffer of rank elements may be provided to avoid using malloc to allocate memory for a small array whose size may already be known.

The value pointed to by dataset should be a valid object identifier if the function exits successfully, and will be left in an undefined state otherwise.

This is roughly equivalent to:


          const int error = cbf_H5Dfind2(location, dataset, name, rank, max, buf, type);
if (CBF_NOTFOUND==error) {
	int i;
	for (i = 0; i != rank; ++i) buf[i] = 0;
	return cbf_H5Dcreate(location, dataset, name, rank, buf, max, chunk, type);
} else {
	/* 'error' may be 'CBF_SUCCESS' or could indicate an error: */
	return error;
}

but contains more sophisticated error handling code and allows for some parameters to be omitted.

ARGUMENTS

location	The hdf5 group/file in which to put the dataset.
dataset	A pointer to a location to store the dataset.
name	The name of the existing/new dataset.
rank	The rank of the data.
max	The (optional) maximum size of each dimension.
chunk	The chunk size used if creating a new dataset.
buf	An optional buffer with `rank` elements.
type	The type of each data element in the file.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.13 cbf_H5Dinsert

Add some data to a datset, expanding the dataset to the appropriate size if needed.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dinsert (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, hsize_t *const buf, const void *const value, const hid_t type)

DESCRIPTION

Insert a slice of data into dataset with the appropriate offset & stride, ensuring that no existing data is lost due to resizing the dataset but not checking that previous data isn't being overwritten.

The offset, stride, count and buf arrays must each have rank elements. If stride is set to the null pointer then a default of [1, 1, 1, ..., 1] will be used. An optional buffer may be provided in buf to avoid using malloc to allocate a small amount of memory whose size may actually be known at compile time.

The value array should contain count[0] * count[1] * ... * count[rank-1] === product(count) elements of data.

ARGUMENTS

dataset	The dataset to write the data to.
offset	Where to start writing the data.
stride	The number of elements in the dataset to step for each element to be written.
count	The number of elements in each dimension to be written.
buf	An optional buffer to avoid using the heap for small amounts of memory.
value	The address of the data to be written.
type	The type of data in memory.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.14 cbf_H5Dset_extent

Change the extent of a chunked dataset to the values in dim.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dset_extent (const hid_t dataset, const hsize_t *const dim)

DESCRIPTION

Forwards to a HDF5 function to change the extent of dataset. The dim array must have the same number of elements as the rank of the dataset, but this can't be checked within this function.

ARGUMENTS

dataset	A handle for the dataset whose extent is to be changed.
dim	The new extent of the dataset, if the function succeeds.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.15 cbf_H5Dwrite2

Add some data to the specified position in the dataset, without checking what (if anything) was there before.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dwrite2 (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, const void *const value, const hid_t type)

DESCRIPTION

Assumes the dataset has the appropriate size to contain all the data and overwrites any existing data that may be there. The rank of the dataset is assumed to be known, and the size of the array parameters is not tested. When rank is zero - in the case of scalar datasets - the offset, stride and count parameters are meaningless and should be omitted by setting them to zero.

ARGUMENTS

dataset	The dataset to write the data to.
offset	Where to start writing the data, as an array of `rank` numbers.
stride	The number of elements in the dataset to step for each element to be written, where null is equivalent to a stride of [1, 1, 1, ..., 1], as an array of `rank` numbers.
count	The number of elements in each dimension to be written, as an array of `rank` numbers.
value	The address of the data to be written.
type	The type of data in memory.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.16 cbf_H5Dread2

Extract some existing data from a dataset at a known position with memtype.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dread2 (const hid_t dataset, const hsize_t *const offset, const hsize_t *const stride, const hsize_t *const count, void *const value, const hid_t type)

DESCRIPTION

Read some data from a given location in the dataset to an existing location in memory. Does not check the length of the array parameters, which should all have rank elements or (in some cases) be null. When rank is zero - in the case of scalar datasets - the offset, stride and count parameters are meaningless and should be omitted by setting them to zero.

ARGUMENTS

dataset	The dataset to read the data from.
offset	Where to start writing the data, as an array of `rank` numbers.
stride	The number of elements in the dataset to step for each element to be written, where null is equivalent to a stride of [1, 1, 1, ..., 1], as an array of `rank` numbers.
count	The number of elements in each dimension to be written, as an array of `rank` numbers.
value	The location where the data is to be stored.
type	The type of data in memory.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.17 cbf_H5Drequire_scalar_F64LE2

Write a scalar 64-bit floating point number as a dataset with comparison.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire_scalar_F64LE2 (const hid_t location, hid_t *const dataset, const char *const name, const double value, int(*cmp)(const void *, const void *, size_t))

DESCRIPTION

Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset.It ensures that a scalar 64-bit IEEE floating point dataset exists with the appropriate name and (for an existing dataset) the correct value as determined by the comparison function cmp.

ARGUMENTS

location	The group containing the new dataset.
dataset	An optional pointer to a place to store the new dataset.
name	The name of the new dataset.
value	The value of the new dataset.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP

Write a scalar 64-bit floating point number as a dataset with a user-defined comparison.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire_scalar_F64LE2_ULP (const hid_t location, hid_t *const dataset, const char *const name, const double value, int(*cmp)(const void *, const void *, size_t, const void *), const void *const cmp_params)

DESCRIPTION

Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset. It ensures that a scalar 64-bit IEEE floating point dataset exists with the appropriate name and (for an existing dataset) the correct value as determined by the user-supplied comparison function cmp.

It is implemented using some of the other dataset functions:

cbf_H5Dfind2
cbf_H5Dcreate
cbf_H5Dread2
cbf_H5Dwrite2

ARGUMENTS

location	The group containing the new dataset.
dataset	An optional pointer to a place to store the new dataset.
name	The name of the new dataset.
value	The value of the new dataset.
cmp	A comparison function to test if a previously set value is equal to the value I asked for.
cmp_params	Some extra data which may be required by the comparison function.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.19 cbf_H5Drequire_flstring
2.6.20 cbf_H5Dfree

2.6.19 cbf_H5Drequire_flstring

Write a single fixed-length string as a dataset.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Drequire_flstring (const hid_t location, hid_t *const dataset, const char *const name, const char *const value)

DESCRIPTION

Convenience function using the HDF5 abstraction layer to avoid the need to consider array-related parameters for a scalar dataset and to automatically set the string type to the correct size.

ARGUMENTS

location	The group containing the new dataset.
dataset	An optional pointer to a place to store the new dataset.
name	The name of the new dataset.
value	The value of the new dataset.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.20 cbf_H5Dfree

2.6.20 cbf_H5Dfree

Close a HDF5 dataset.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Dfree (const hid_t ID)

DESCRIPTION

Attempt to close a dataset, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 dataset to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.10 cbf_H5Dcreate
2.6.11 cbf_H5Dfind2
2.6.12 cbf_H5Drequire
2.6.13 cbf_H5Dinsert
2.6.14 cbf_H5Dset_extent
2.6.15 cbf_H5Dwrite2
2.6.16 cbf_H5Dread2
2.6.17 cbf_H5Drequire_scalar_F64LE2
2.6.18 cbf_H5Drequire_scalar_F64LE2_ULP
2.6.19 cbf_H5Drequire_flstring

2.6.21 cbf_H5Fopen

Attempt to open an HDF5 file by file name.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Fopen (hid_t *const file, const char *const name)

DESCRIPTION

Will try to open a file of the given name with suitable values for some of it's properties to make memory leaks less likely.

Warning: this function will destroy any existing data in the file, do not pass the name of any file containing data you want to keep.

ARGUMENTS

file	A pointer to an HDF5 ID where the newly opened file should be stored.
name	The name of the file to attempt to open.

RETURN VALUE

An error code.

SEE ALSO

2.6.22 cbf_H5Fclose

2.6.22 cbf_H5Fclose

Close a HDF5 file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Fclose (const hid_t ID)

DESCRIPTION

Attempt to close a file, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 file to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.21 cbf_H5Fopen

2.6.23 cbf_H5Gcreate

Attempt to create a group.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Gcreate (const hid_t location, hid_t *const group, const char *const name)

DESCRIPTION

Helper function to attempt to create a HDF5 group identified by name and return an error code, to make error handling more consistant. This will fail if a link with the same name already exists in parent.

ARGUMENTS

location	The group that will contain the newly created group.
group	A pointer to a HDF5 ID type where the group will be stored.
name	The name that the group will be given.

RETURN VALUE

An error code.

SEE ALSO

2.6.24 cbf_H5Gfind
2.6.25 cbf_H5Grequire
2.6.26 cbf_H5Gfree

2.6.24 cbf_H5Gfind

Check if a group exists.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Gfind (const hid_t location, hid_t *const group, const char *const name)

DESCRIPTION

Checks for the existance of a group with the given name and parent. Will return CBF_NOTFOUND if it cannot be found, or open it if it already exists. An error code will be returned if something other than a group exists at the specified location.

ARGUMENTS

location	The group to be searched.
group	A pointer to a HDF5 ID type where the group will be stored.
name	The path (ie, name) of the group to be found.

RETURN VALUE

An error code.

SEE ALSO

2.6.23 cbf_H5Gcreate
2.6.25 cbf_H5Grequire
2.6.26 cbf_H5Gfree

2.6.25 cbf_H5Grequire

Ensure a group exists.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Grequire (const hid_t location, hid_t *const group, const char *const name)

DESCRIPTION

Checks for the existance of a group with the given name and parent. Will create the group if it cannot be found, or open it if it already exists. It is an error if a matching group cannot be found or created. This uses cbf_H5Gcreate to create any new groups.

ARGUMENTS

location	The group that will contain the newly created group.
group	A pointer to a HDF5 ID type where the group will be stored.
name	The name that the group will be given.

RETURN VALUE

An error code.

SEE ALSO

2.6.23 cbf_H5Gcreate
2.6.24 cbf_H5Gfind
2.6.26 cbf_H5Gfree

2.6.26 cbf_H5Gfree

Close a HDF5 group.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Gfree (const hid_t ID)

DESCRIPTION

Attempt to close a group, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 group to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.23 cbf_H5Gcreate
2.6.24 cbf_H5Gfind
2.6.25 cbf_H5Grequire

2.6.27 cbf_H5Ivalid

Check the validity of an object identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Ivalid (const hid_t ID)

DESCRIPTION

Function to check validity of a HDF5 identifier. HDF5's predefined types are never counted as valid by this function, so it can't be used to test the validity of a type constant. Types obtained by using H5Tcopy are safe to test.

ARGUMENTS

ID	An HDF5 object identifier.

RETURN VALUE

Non-zero if the type is valid, zero otherwise.

SEE ALSO

2.6.28 cbf_H5Ocmp

2.6.28 cbf_H5Ocmp

A missing HDF5 function.

PROTOTYPE

#include "cbf_hdf5.h"
htri_t cbf_H5Ocmp (const hid_t id0, const hid_t id1)

DESCRIPTION

Compare two HDF5 object ID's for equality. This follows the standard practice of returning zero if objects should be considered equal, and the HDF5 practice of returning a negative number if there is an error.

ARGUMENTS

id0	An HDF5 identifier.
id1	An HDF5 identifier.

RETURN VALUE

0 if equal, a positive value if not equal, or a negative value if there is an error.

SEE ALSO

2.6.27 cbf_H5Ivalid

2.6.29 cbf_H5Ofree

Close a HDF5 object identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Ofree (const hid_t ID)

DESCRIPTION

Attempt to close an object identifier of unknown type, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 object to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.28 cbf_H5Ocmp
2.6.27 cbf_H5Ivalid

2.6.30 cbf_H5Screate

Create a dataspace with some given values.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Screate (hid_t *const ID, const int rank, const hsize_t *const dim, const hsize_t *const max)

DESCRIPTION

Helper function which creates a HDF5 dataspace.

Maximum dimensions can be set to infinity by passing H5S_UNLIMITED in the appropriate slot of the max parameter. If rank is zero then neither dim nor max are used and a scalar dataspace is created. If rank is non-zero and dim is a null pointer then ID will not be modified and the function will fail. If rank is non-zero and max is a null pointer the maximum length is set to the current length as given by dim.

ARGUMENTS

ID	A pointer to a HDF5 identifier that will contain the new dataspace.
rank	The number of dimensions of the new dataspace.
dim	The current size of each dimension of the dataspace, should be an array of length `rank` .
max	The maximum size of each dimension, should be an array of length `rank` .

RETURN VALUE

An error code.

SEE ALSO

2.6.31 cbf_H5Sfree

2.6.31 cbf_H5Sfree

Close a HDF5 dataspace identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Sfree (const hid_t ID)

DESCRIPTION

Attempt to close a dataspace identifier, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 dataspace to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.30 cbf_H5Screate

2.6.32 cbf_H5Tcreate_string

Get a HDF5 string datatype to describe a sting of the specified length.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Tcreate_string (hid_t *const type, const size_t len)

DESCRIPTION

Convenience function to create a string datatype suitable for use when storing a string of length len, returning it in the identifier pointed to by type.

ARGUMENTS

type	A pointer to a the HDF5 handle of the new datatype, which should be free'd with `cbf_H5Tfree`
len	The length of the string datatype - should be `strlen()` or `H5T_VARIABLE`

RETURN VALUE

An error code.

SEE ALSO

2.6.33 cbf_H5Tfree

2.6.33 cbf_H5Tfree

Close a HDF5 datatype identifier.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_H5Tfree (const hid_t ID)

DESCRIPTION

Attempt to close a datatype identifier, but don't modify the identifier that described it.

ARGUMENTS

ID	The HDF5 datatype to be closed.

RETURN VALUE

An error code.

SEE ALSO

2.6.32 cbf_H5Tcreate_string

2.7 High-level NeXus-related functions

These functions primarily allow interaction with a cbf_h5handle without being exposed to its structure or the complexities of using it correctly. Wherever possible these functions should be used instead of directly accessing a cbf_h5handle or cbf_config_t in order make code easier to read, to maintain the integrity of the data structures and to ensure all resources allocated to these object are correctly cleaned up.

This section describes functions available for working with:

CBF's HDF5 handles:
miniCBF configuration settings:

Reading miniCBF configuration settings

This example demonstrates how a miniCBF configuration file should be parsed, what should be checked before the extracted settings are used and what should be cleaned up by the caller afterwards:


          /* Declare some important variables */
int configError = cbf_configError_success;
FILE * configFile = fopen("config.txt","r");
cbf_config_t * const configSettings = cbf_config_create();

/*
Read and check the configuration settings,
writing any error messages to stderr.
*/
configError = cbf_config_parse(configFile,stderr,configSettings);
/* I no longer need to keep the file open */
fclose(configFile);

/* Check if I could read the file successfully */
if (cbf_configError_success != configError) {
    fprintf(stderr,"Error parsing configuration file 'config.txt': %s\n",
            cbf_config_strerror(configError));
} else {
	/* Use the configuration settings here... */
}

/* Clean up the settings to avoid memory leaks */
cbf_config_free(configSettings);

2.7.1 cbf_h5handle_get_file

Get the current id of the file within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_file (const cbf_h5handle nx, hid_t *const file)

DESCRIPTION

Check the handle for the presence of a file, optionally returning it.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
file	A place to store the file (if found), or null if the file isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.2 cbf_h5handle_set_file

2.7.2 cbf_h5handle_set_file

Set the id of the file within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_file (const cbf_h5handle nx, const hid_t file)

DESCRIPTION

Sets the file id within the handle to the given value. Doesn't check or modify any attributes in any way.

ARGUMENTS

nx	The handle to add information to.
file	The file to be set as the current file id.

RETURN VALUE

An error code.

SEE ALSO

2.7.1 cbf_h5handle_get_file

2.7.3 cbf_h5handle_get_entry

Get the current id and name of the entry group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_entry (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an entry group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.4 cbf_h5handle_set_entry
2.7.5 cbf_h5handle_require_entry

2.7.4 cbf_h5handle_set_entry

Set the id and name of the entry group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_entry (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the entry group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current entry group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.3 cbf_h5handle_get_entry
2.7.5 cbf_h5handle_require_entry

2.7.5 cbf_h5handle_require_entry

Ensure I have an entry in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_entry (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the entry group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"entry"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.3 cbf_h5handle_get_entry
2.7.4 cbf_h5handle_set_entry

2.7.6 cbf_h5handle_require_entry_definition

Ensure I have an entry in the hdf5 handle with definition.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_entry_definition (const cbf_h5handle nx, hid_t *const group, const char *name, const char *definition, const char *version, const char *URL)

DESCRIPTION

This will check if the entry group and definition within the handle matches any existing group of the same name within the current file and has a definition designation that agrees. If the group name doesn't match a new group is opened or created and added to the handle. If the definition does not match, it is replaced with the new one. If the version attribute does not match it is replaced with the new one. If the URL> attribute does not match it is replace with the new one. The NX_class attributes are not checked, but if a new entry is created it will be created with NX_class NXentry.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group ID should be stored.
name	The group name, or null to use the default name of `"entry"`.
definition	The definition name, or null to not specify a definition name.
version	The version string, or null to not specify a version string.
URL	The URL at which the definition is stored, or null to not specify a URL

RETURN VALUE

An error code.

SEE ALSO

2.7.3 cbf_h5handle_get_entry
2.7.4 cbf_h5handle_set_entry
2.7.5 cbf_h5handle_require_entry

2.7.7 cbf_h5handle_get_sample

Get the current id and name of the sample group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_sample (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an sample group and its name, optionally returning any combination of them.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.8 cbf_h5handle_set_sample
2.7.9 cbf_h5handle_require_sample

2.7.8 cbf_h5handle_set_sample

Set the id and name of the sample group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_sample (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the sample group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current sample group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.7 cbf_h5handle_get_sample
2.7.9 cbf_h5handle_require_sample

2.7.9 cbf_h5handle_require_sample

Ensure I have a sample in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_sample (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the sample group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"sample"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.7 cbf_h5handle_get_sample
2.7.8 cbf_h5handle_set_sample

2.7.10 cbf_h5handle_get_beam

Get the current id and name of the beam group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_beam (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of a beam group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.11 cbf_h5handle_set_beam
2.7.12 cbf_h5handle_require_beam

2.7.11 cbf_h5handle_set_beam

Set the id and name of the beam group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_beam (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the beam group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current beam group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.10 cbf_h5handle_get_beam
2.7.12 cbf_h5handle_require_beam

2.7.12 cbf_h5handle_require_beam

Ensure I have a beam in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_beam (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the beam group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"beam"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.10 cbf_h5handle_get_beam
2.7.11 cbf_h5handle_set_beam

2.7.13 cbf_h5handle_get_instrument

Get the current id and name of the instrument group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_instrument (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an instrument group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.14 cbf_h5handle_set_instrument
2.7.15 cbf_h5handle_find_instrument
2.7.16 cbf_h5handle_require_instrument

2.7.14 cbf_h5handle_set_instrument

Set the id and name of the instrument group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_instrument (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the instrument group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current instrument group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.13 cbf_h5handle_get_instrument
2.7.15 cbf_h5handle_find_instrument
2.7.16 cbf_h5handle_require_instrument

2.7.15 cbf_h5handle_find_instrument

Find an existing instrument group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_find_instrument (const cbf_h5handle nx, hid_t *const group, const char **const name)

ARGUMENTS

nx
group
name

2.7.16 cbf_h5handle_require_instrument

Ensure I have an instrument in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_instrument (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the instrument group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"instrument"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.13 cbf_h5handle_get_instrument
2.7.14 cbf_h5handle_set_instrument
2.7.15 cbf_h5handle_find_instrument

2.7.17 cbf_h5handle_get_detector

Get the current id and name of the detector group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_detector (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an detector group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.18 cbf_h5handle_set_detector
2.7.19 cbf_h5handle_find_detector
2.7.20 cbf_h5handle_require_detector

2.7.18 cbf_h5handle_set_detector

Set the id and name of the detector group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_detector (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the detector group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current detector group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.17 cbf_h5handle_get_detector
2.7.19 cbf_h5handle_find_detector
2.7.20 cbf_h5handle_require_detector

2.7.19 cbf_h5handle_find_detector

Find an existing detector group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_find_detector (const cbf_h5handle nx, hid_t *const group, const char **const name)

ARGUMENTS

nx
group
name

2.7.20 cbf_h5handle_require_detector

Ensure I have a detector in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_detector (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the detector group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"detector"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.17 cbf_h5handle_get_detector
2.7.18 cbf_h5handle_set_detector
2.7.19 cbf_h5handle_find_detector

2.7.21 cbf_h5handle_get_goniometer

Get the current id and name of the goniometer group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_goniometer (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an goniometer group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.22 cbf_h5handle_set_goniometer
2.7.23 cbf_h5handle_require_goniometer

2.7.22 cbf_h5handle_set_goniometer

Set the id and name of the goniometer group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_goniometer (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the goniometer group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current goniometer group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.21 cbf_h5handle_get_goniometer
2.7.23 cbf_h5handle_require_goniometer

2.7.23 cbf_h5handle_require_goniometer

Ensure I have a goniometer in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_goniometer (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the goniometer group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"goniometer"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.21 cbf_h5handle_get_goniometer
2.7.22 cbf_h5handle_set_goniometer

2.7.24 cbf_h5handle_get_monochromator

Get the current id and name of the monochromator group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_monochromator (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an monochromator group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.25 cbf_h5handle_set_monochromator
2.7.26 cbf_h5handle_require_monochromator

2.7.25 cbf_h5handle_set_monochromator

Set the id and name of the monochromator group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_monochromator (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the monochromator group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current monochromator group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.24 cbf_h5handle_get_monochromator
2.7.26 cbf_h5handle_require_monochromator

2.7.26 cbf_h5handle_require_monochromator

Ensure I have a monochromator in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_monochromator (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the monochromator group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"monochromator"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.24 cbf_h5handle_get_monochromator
2.7.25 cbf_h5handle_set_monochromator

2.7.27 cbf_h5handle_get_source

Get the current id and name of the source group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_get_source (const cbf_h5handle nx, hid_t *const group, const char **const name)

DESCRIPTION

Check the handle for the presence of an source group and its name, optionally returning any combination of them. The error code 'CBF_NOTFOUND' will be returned if any of the requested items of data cannot be found.

The handle retains ownership of the returned object and/or string, neither of them should be free'd by the caller.

ARGUMENTS

nx	A handle to query for the presence of the requested information.
group	A place to store the group (if found), or null if the group isn't wanted.
name	A place to store the name of the group (if found), or null if the name isn't wanted.

RETURN VALUE

An error code.

SEE ALSO

2.7.28 cbf_h5handle_set_source
2.7.29 cbf_h5handle_require_source

2.7.28 cbf_h5handle_set_source

Set the id and name of the source group within the given handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_set_source (const cbf_h5handle nx, const hid_t group, const char *const name)

DESCRIPTION

Sets the source group and name within the handle to the given values. Doesn't check or modify the NX_class attribute in any way. The handle will take ownership of the group id iff this function succeeds.

ARGUMENTS

nx	The handle to add information to.
group	The group to be set as the current source group
name	The name which the group should be given.

RETURN VALUE

An error code.

SEE ALSO

2.7.27 cbf_h5handle_get_source
2.7.29 cbf_h5handle_require_source

2.7.29 cbf_h5handle_require_source

Ensure I have a source in the hdf5 handle.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_h5handle_require_source (const cbf_h5handle nx, hid_t *const group, const char *name)

DESCRIPTION

This will check if the source group within the handle matches any existing group of the same name within the current file. If they don't match a new group is opened or created and added to the handle. The NX_class attributes are not checked.

ARGUMENTS

nx	The HDF5 handle to use.
group	An optional pointer to a place where the group should be stored.
name	The group name, or null to use the default name of `"source"`.

RETURN VALUE

An error code.

SEE ALSO

2.7.27 cbf_h5handle_get_source
2.7.28 cbf_h5handle_set_source

2.7.30 cbf_free_h5handle

Free a handle for an HDF5 file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_free_h5handle (cbf_h5handle h5handle)

DESCRIPTION

Checks if the handle appears to be valid, the free's the handle and any data that the handle owns.

ARGUMENTS

h5handle

The handle to be free'd.

RETURN VALUE

An error code

SEE ALSO

2.7.31 cbf_create_h5handle3

2.7.31 cbf_create_h5handle3

Allocates space for a HDF5 file handle and associates it with the given file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_create_h5handle3 (cbf_h5handle *handle, hid_t file)

DESCRIPTION

This function expects the user to create or open a hdf5 file with the appropriate parameters for what they are trying to do, replacing older functions which would create a file with the H5F_ACC_TRUNC flag and H5F_CLOSE_STRONG property.

ARGUMENTS

handle	A pointer to a handle which is to be allocated.
file	A HDF5 file to store within the newly created handle.

RETURN VALUE

An error code

SEE ALSO

2.7.30 cbf_free_h5handle

2.7.32 cbf_write_cbf_h5file

Extract the data from a CBF file & put it into a NeXus file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_cbf_h5file (cbf_handle handle, cbf_h5handle h5handle)

DESCRIPTION

Equivalent to cbf_write_cbf2nx(handle,h5handle,0,0,0).

ARGUMENTS

handle	The CBF file to extract data from.
h5handle	The NeXuS file to write data to.

RETURN VALUE

An error code.

SEE ALSO

2.7.34 cbf_write_minicbf_h5file
2.7.33 cbf_write_cbf2nx
2.7.35 cbf_write_nx2cbf

2.7.33 cbf_write_cbf2nx

Extract the data from a CBF file & put it into a NeXus file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_cbf2nx (cbf_handle handle, cbf_h5handle h5handle, const char *const datablock, const char *const scan, const int list)

DESCRIPTION

Extracts data from handle and generates a NeXus file in h5handle. This will attempt to extract metadata and image data from each scan (or the named scan) within each datablock (or the the named datablock) and insert it into a given index into the NXentry group specified in h5handle.

Each scan in the CBF file corresponds to one NXentry in NeXus, so a CBF datablock with multiple scans must be converted by calling this function with the appropriate value of scan once for each scan in the datablock.

The flags (within h5handle) determine:

Compression algorithm: zlib/CBF/none
Plugin registration method: automatic/manual

The strings given by h5handle->scan_id and h5handle->sample_id define:

The presence and value of an identifier for the scan, stored in /*:NXentry/entry_identifier.
The presence and value of an identifier for the sample, stored in /*:NXentry/*:NXsample/sample_identifier.

ARGUMENTS

handle	The CBF file to extract data from.
h5handle	The NeXuS file to write data to.
datablock	The name of the datablock to convert, or NULL to convert all datablocks.
scan	The name of the scan to convert, or NULL if there is only one scan in the datablock.
list	Boolean flag to determine if a list of processed items is printed.

RETURN VALUE

An error code.

SEE ALSO

2.7.32 cbf_write_cbf_h5file
2.7.34 cbf_write_minicbf_h5file
2.7.35 cbf_write_nx2cbf

2.7.34 cbf_write_minicbf_h5file

Extract the data from a miniCBF file & put it into a NeXus file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_minicbf_h5file (cbf_handle handle, cbf_h5handle h5handle, const cbf_config_t *const axisConfig)

DESCRIPTION

Extracts the miniCBF data directly - by parsing the header - and uses that plus the configuration options from axisConfig to generate a NeXus file in h5handle. This can extract metadata and image data from miniCBF files containing multiple datablocks which each contain a single image and insert it into a given index into the NXentry group specified in h5handle.

Currently, only Pilatus 1.2 format headers are supported.

The flags determine:

Compression algorithm: zlib/CBF/none
Plugin registration method: automatic/manual

ARGUMENTS

handle	The miniCBF file to extract data from.
h5handle	The NeXus file to write data to.
axisConfig	The configuration settings desribing the axes and their relation to the sample and to each other.

RETURN VALUE

An error code.

SEE ALSO

2.7.32 cbf_write_cbf_h5file
2.7.35 cbf_write_nx2cbf

2.7.35 cbf_write_nx2cbf

Extract data from a nexus file and store it in a CBF file.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_write_nx2cbf (cbf_h5handle nx, cbf_handle cbf)

DESCRIPTION

Reads NeXus-format data from the entry group defined in the nx handle, extracting data related to the frame with index nx->slice and in CBF-format within the the cbf handle.

ARGUMENTS

nx	The handle defining the NeXus data to be converted.
cbf	The handle in which to store the resulting CBF data.

RETURN VALUE

An error code.

SEE ALSO

2.7.32 cbf_write_cbf_h5file
2.7.34 cbf_write_minicbf_h5file

2.7.36 cbf_config_create

Obtain a new handle for some configuration settings.

PROTOTYPE

#include "cbf_hdf5.h"
cbf_config_t* cbf_config_create ()

DESCRIPTION

Allocates a new collection of configuration settings on the heap, and initialises it. The returned pointer should be destroyed by the caller.

ARGUMENTS

This function takes no arguments.

RETURN VALUE

A newly allocated object for miniCBF configuration settings, or NULL.

2.7.37 cbf_config_parse

Read a minicbf configuration file into the given handle, writing errors to logfile.

PROTOTYPE

#include "cbf_hdf5.h"
int cbf_config_parse (FILE *const configFile, FILE *const logFile, cbf_config_t *const vec)

DESCRIPTION

Parses a configuration file to extract a collection of configuration settings for a miniCBF file, storing them in the given configuration settings object. The pointer should have been obtained by a call to cbf_config_create. The configuration file format is described in the minicbf2nexus documentation.

ARGUMENTS

configFile	The file from which the config settings should be read.
logFile	A stream to be used for logging error messages.
vec	An object describing the configuration settings.

RETURN VALUE

A parser error code.

2.7.38 cbf_config_free

Free any heap memory associated with the given cbf_hdf5_configItemVectorhandle object.

PROTOTYPE

#include "cbf_hdf5.h"
void cbf_config_free (const cbf_config_t *const vector)

DESCRIPTION

Destroys an existing collection of configuration settings. The settings should have been obtained by a call to cbf_config_create.

ARGUMENTS

vector

The configuration data to be free'd.

RETURN VALUE

Nothing.

2.7.39 cbf_config_strerror

Convert a parse error to a descriptive string.

PROTOTYPE

#include "cbf_hdf5.h"
const char* cbf_config_strerror (const int error)

DESCRIPTION

The returned string is "none" for success, "unknown error" if the given error code is not recognised and a non-empty string briefly describing the error otherwise.

The returned string must not be free'd.

ARGUMENTS

error

An error returned by a cbf_config_* function.

RETURN VALUE

A string describing the error.

3. File format

3.1 General description

With the exception of the binary sections, a CBF file is an mmCIF-format ASCII file, so a CBF file with no binary sections is a CIF file. An imgCIF file has any binary sections encoded as CIF-format ASCII strings and is a CIF file whether or not it contains binary sections. In most cases, CBFlib can also be used to access normal CIF files as well as CBF and imgCIF files.

3.2 Format of the binary sections

Before getting to the binary data itself, there are some preliminaries to allow a smooth transition from the conventions of CIF to those of raw or encoded streams of "octets" (8-bit bytes). The binary data is given as the essential part of a specially formatted semicolon-delimited CIF multi-line text string. This text string is the value associated with the tag "_array_data.data".

The specific format of the binary sections differs between an imgCIF and a CBF file.

3.2.1 Format of imgCIF binary sections

Each binary section is encoded as a semicolon-delimited string. Within the text string, the conventions developed for transmitting email messages including binary attachments are followed. There is secondary ASCII header information, formatted as Multipurpose Internet Mail Extensions (MIME) headers (see RFCs 2045-49 by Freed, et al.). The boundary marker for the beginning of all this is the special string

at the beginning of a line. The initial "--" says that this is a MIME boundary. We cannot put "###" in front of it and conform to MIME conventions. Immediately after the boundary marker are MIME headers, describing some useful information we will need to process the binary section. MIME headers can appear in different orders, and can be very confusing (look at the raw contents of a email message with attachments), but there is only one header which is has to be understood to process an imgCIF: "Content-Transfer-Encoding". If the value given on this header is "BINARY", this is a CBF and the data will be presented as raw binary, containing a count (in the header described in 3.2.2 Format of CBF binary sections) so that we'll know when to start looking for more information.

If the value given for "Content-Transfer-Encoding" is one of the real encodings: "BASE64", "QUOTED-PRINTABLE", "X-BASE8", "X-BASE10" or "X-BASE16", the file is an imgCIF, and we'll need some other headers to process the encoded binary data properly. It is a good practice to give headers in all cases. The meanings of various encodings is given in the CBF extensions dictionary, cif_img_1.5.4.dic, as one html file, or as separate pages for each defintion.

For certain compressions (e.g. CBF_PACKED) MIME headers are essential to determine the parameters of the compression. The full list of MIME headers recognized by and generated by CBFlib is:

A blank line separator immediately precedes the start of the encoded binary data. Blank spaces may be added prior to the preceding "line separator" if desired (e.g. to force word or block alignment).

Because CBFLIB may jump forward in the file from the MIME header, the length of encoded data cannot be greater than the value defined by "X-Binary-Size" (except when "X-Binary-Size" is zero, which means that the size is unknown), unless "X-Binary-Size-Padding" is specified to allow for the padding. At exactly the byte following the full binary section as defined by the length and padding values is the end of binary section identifier. This consists of the line-termination sequence followed by:

with each of these lines followed by a line-termination sequence. This brings us back into a normal CIF environment. This identifier is, in a sense, redundant because the binary data length value tells the a program how many bytes to jump over to the end of the binary data. This redundancy has been deliberately added for error checking, and for possible file recovery in the case of a corrupted file and this identifier must be present at the end of every block of binary data.

3.2.2 Format of CBF binary sections

In a CBF file, each binary section is encoded as a ;-delimited string, starting with an arbitrary number of pure-ASCII characters.

Note: For historical reasons, CIFlib has the option of writing simple header and footer sections: "START OF BINARY SECTION" at the start of a binary section and "END OF BINARY SECTION" at the end of a binary section, or writing MIME-type header and footer sections (3.2.1 Format of imgCIF binary sections). If the simple header is used, the actual ASCII text is ignored when the binary section is read. Use of the simple binary header is deprecated.

Between the ASCII header and the actual CBF binary data is a series of bytes ("octets") to try to stop the listing of the header, bytes which define the binary identifier which should match the "binary_id" defined in the header, and bytes which define the length of the binary section.

Octet	Hex	Decimal	Purpose
1	0C	12	(ctrl-L) End of Page
2	1A	26	(ctrl-Z) Stop listings in MS-DOS
3	04	04	(Ctrl-D) Stop listings in UNIX
4	D5	213	Binary section begins
5..5+n-1			Binary data (n octets)

NOTE: When a MIME header is used, only bytes 5 through 5+n-1 are considered in computing the size and the message digest, and only these bytes are encoded for the equivalent imgCIF file using the indicated Content-Transfer-Encoding.

If no MIME header has been requested (a deprecated use), then bytes 5 through 28 are used for three 8-byte words to hold the binary_id, the size and the compression type:

5..12

Binary Section Identifier
(See _array_data.binary_id)
64-bit, little endian

13..20

The size (n) of the
binary section in octets
(i.e. the offset from octet
29 to the first byte following
the data)

21..28

Compression type:

CBF_NONE	0x0040 (64)
CBF_CANONICAL	0x0050 (80)
CBF_PACKED	0x0060 (96)
CBF_PACKED_V2	0x0090 (144)
CBF_BYTE_OFFSET	0x0070 (112)
CBF_NIBBLE_OFFSET	0x00A0 (160)
CBF_PREDICTOR	0x0080 (128)
...

For historical reasons, CBFlib can read or write a binary string without a MIME header. The structure of a binary string with simple headers is:

Byte	ASCII symbol	Decimal value	Description
1	;	59	Initial ; delimiter
2	carriage-return	13
3	line-feed	10	The CBF new-line code is carriage-return, line-feed
4	S	83
5	T	84
6	A	65
7	R	83
8	T	84
9		32
10	O	79
11	F	70
12		32
13	B	66
14	I	73
15	N	78
16	A	65
17	R	83
18	Y	89
19		32
20	S	83
21	E	69
22	C	67
23	T	84
24	I	73
25	O	79
26	N	78
27	carriage-return	13
28	line-feed	10
29	form-feed	12
30	substitute	26	Stop the listing of the file in MS-DOS
31	end-of-transmission	4	Stop the listing of the file in unix
32		213	First non-ASCII value
33 .. 40			Binary section identifier (64-bit little-endien)
41 .. 48			Offset from byte 57 to the first ASCII character following the binary data
49 .. 56			Compression type
57 .. 57 + n-1			Binary data (nbytes)
57 + n	carriage-return	13
58 + n	line-feed	10
59 + n	E	69
60 + n	N	78
61 + n	D	68
62 + n		32
63 + n	O	79
64 + n	F	70
65 + n		32
66 + n	B	66
67 + n	I	73
68 + n	N	78
69 + n	A	65
70 + n	R	83
71 + n	Y	89
72 + n		32
73 + n	S	83
74 + n	E	69
75 + n	C	67
76 + n	T	84
77 + n	I	73
78 + n	O	79
79 + n	N	78
80 + n	carriage-return	13
81 + n	line-feed	10
82 + n	;	59	Final ; delimiter

3.3 Compression schemes

Two schemes for lossless compression of integer arrays (such as images) have been implemented in this version of CBFlib:

1. An entropy-encoding scheme using canonical coding
2. A CCP4-style packing scheme. 3. A simple and efficient byte-offset compression. 4. A slightly more complex nibble-offset compression.

All encode the difference (or error) between the current element in the array and the prior element or neighboring elements.

3.3.1 Canonical-code compression

The canonical-code compression scheme encodes errors in two ways: directly or indirectly. Errors are coded directly using a symbol corresponding to the error value. Errors are coded indirectly using a symbol for the number of bits in the (signed) error, followed by the error iteslf.

At the start of the compression, CBFlib constructs a table containing a set of symbols, one for each of the 2^ⁿ direct codes from -2^^(n-1) .. 2^^(n-1)-1, one for a stop code, and one for each of the maxbits -n indirect codes, where n is chosen at compress time and maxbits is the maximum number of bits in an error. CBFlib then assigns to each symbol a bit-code, using a shorter bit code for the more common symbols and a longer bit code for the less common symbols. The bit-code lengths are calculated using a Huffman-type algorithm, and the actual bit-codes are constructed using the canonical-code algorithm described by Moffat, et al. (International Journal of High Speed Electronics and Systems, Vol 8, No 1 (1997) 179-231).

Byte	Value
1 .. 8	Number of elements (64-bit little-endian number)
9 .. 16	Minimum element
17 .. 24	Maximum element
25 .. 32	(reserved for future use)
33	Number of bits directly coded, n
34	Maximum number of bits encoded, maxbits
35 .. 35+2^ⁿ-1	Number of bits in each direct code
35+2^ⁿ	Number of bits in the stop code
35+2^ⁿ+1 .. 35+2^ⁿ+maxbits-n	Number of bits in each indirect code
35+2^ⁿ+maxbits-n+1 ..	Coded data

3.3.2 CCP4-style compression

Starting with CBFlib 0.7.7, CBFlib supports three variations on CCP4-style compression: the "flat" version supported in versions of CBFlib prior to release 0.7.7, as well as both version 1 and version 2 of J. P. Abrahams "pack_c" compression.

The CBF_PACKED and CBF_PACKED_V2 compression and decompression code incorporated in CBFlib is derived in large part from the J. P. Abrahams pack_c.c compression code in CCP4. This code is incorporated in CBFlib under the GPL and the LGPL with both the permission Jan Pieter Abrahams, the original author of pack_c.c (email from Jan Pieter Abrahams of 15 January 2007) and of the CCP4 project (email from Martyn Winn on 12 January 2007). The cooperation of J. P. Abrahams and of the CCP4 project is gratefully acknowledged.

The basis for all three versions is a scheme to pack offsets (differences from a base value) into a small-endian bit stream. The stream is organized into blocks. Each block begins with a header of 6 bits in the flat packed version and version 1 of J. P. Abrahams compression, and 7 bits in version 2 of J. P. Abrahams compression. The header gives the number of offsets that follow and the number of bits in each offset. Each offset is a signed, 2's complement integer.

The first 3 bits in the header gives the logarithm base 2 of the numer of offsets that follow the header. For example, if a header has a zero in bits, only one offset follows the header. If those same bits contain the number n, the number of offsets in the block is 2ⁿ.

The following 3 bits (flat and version 1) or 4 bits (version 2) contains a number giving an index into a table of bit-lengths for the offsets. All offsets in a given block are of the same length.

Bits 3 .. 5 (flat and version 1) or bits 3 .. 6 (version 2) encode the number of bits in each offset as follows:

Value in bits 3 .. 5	Number of bits in each V1 offset	Number of bits in each V2 offset
0	0	0
1	4	3
2	5	4
3	6	5
4	7	6
5	8	7
6	16	8
7	max	9
8		10
9		11
10		12
11		13
12		14
13		15
14		16
15		max

The value "max" is determined by the compression version and the element size. If the compression used is "flat", then "max" is 65. If the compression is version 1 or version 2 of the JPA compression, then "max" is the number of bits in each element, i.e. 8, 16, 32 or 64 bits.

The major difference between the three variants of packed compression is the choice of the base value from which the offset is measured. In all cases the first offset is measured from zero, i.e. the first offset is the value of the first pixel of the image. If "flat" is chosen or if the dimensions of the data array are not given, then the remaining offset are measure against the prior value, making it similar in approach to the "byte offset" compression described in section 3.3.3 Byte offset compression, but with a more efficient representation of the offsets.

In version 1 and version 2 of the J. P. Abrahams compression, the offsets are measured against an average of earlier pixels. If there is only one row only the prior pxiel is used, starting with the same offsets for that row as for "flat". After the first row, three pixels from the prior row are used in addition to using the immediately prior pixel. If there are multiple sections, and the sections are marked as correlated, after the first section, 4 pixels from the prior section are included in the average. The CBFlib code differs from the pack_c code in the handling of the beginnings and ends of rows and sections. The pack_c code will use pixels from the other side of the image in doing the averaging. The CBFlib code drops pixels from the other side of the image from the pool. The details follow.

After dealing with the special case of the first pixel, The algorithm uses an array of pointers, trail_char_data. The assignment of pixels to the pool to be averaged begins with trail_char_data[0] points to the pixel immediately prior to the next pixel to be processed, either in the same row (fastest index) or, at the end of the prior row if the next data element to be processed is at the end of a row. The location of the pixel pointed to by trail_char_data[0] is used to compute the locations of the other pixels in the pool. It will be dropped from the pool before averaging if it is on the opposite side of the image. The pool will consist of 1, 2, 4 or 8 pixels.

Assume ndim1, ndim2, ndim3 are the indices of the same pixel as trail_char_data[0] points to. These indices are incremented to be the indices of the next pixel to be processed before populating trail_char_data.

On exit, trail_char_data[0 .. 7] will have been populated with pointers to the pixels to be used in forming the average. Pixels that will not be used will be set to NULL. Note that trail_char_data[0] may be set to NULL.

If we mark the next element to be processed with a "*" and the entries in trail_char_data with their array indices 0 .. 7, the possible patterns of settings in the general case are:

If there is no prior section (i.e. ndim3 is 0, or the CBF_UNCORRELATED_SECTIONS flag is set to indicate discontinuous sections), the values for trail_char_data[4 .. 7] will all be NULL. When there is a prior section, trail_char_data[5..7] are pointers to the pixels immediately below the elements pointed to by trail_char_data[1..3], except trail_char_data[4] is one element further along its row to be directly below the next element to be processed.

The first element of the first row of the first section is a special case, with no averaging.

In the first row of the first section (ndim2 == 0, and ndim3 == 0), after the first element (ndim1 > 0), only trail_char_data[0] is used

For subsequent rows of the first section (ndim2 > 0, and ndim3 == 0), for the first element (ndim1 == 0), two elements from the prior row are used:

while for element after the first element, but before the last element of the row, a full set of 4 elements is used:

For sections after the first section, provided the CBF_UNCORRELATED_SECTIONS flag is not set in the compression, for each non-NULL entry in trail_char_data [0..3] an entry is made in trail_char_data [4..7], except for the first element of the first row of a section. In that case an entry is made in trail_char_data[4].

The structure of the compressed data is:

Byte	Value
1 .. 8	Number of elements (64-bit little-endian number)
9 .. 16	Minumum element (currently unused)
17 .. 24	Maximum element (currently unused)
25 .. 32	(reserved for future use)
33 ..	Coded data

3.3.3 Byte_offset compression

Starting with CBFlib 0.7.7, CBFlib supports a simple and efficient "byte_offset" algorithm originally proposed by Andy Hammerley and modified by Wolgang Kabsch and Herbert Bernstein. The original proposal was called "byte_offsets". We distinguish this variant by calling it "byte_offset". The major differences are that the "byte_offsets" algorithm started with explicit storage of the first element of the array as a 4-byte signed two's integer, and checked for image edges to changes the selection of prior pixel. The CBFlib "byte_offset" alogorithm starts with an assumed zero before the first pixel and represents the value of the first pixel as an offset of whatever number of size is needed to hold the value, and for speed, treats the entire image as a simple linear array, allowing use of the last pixel of one row as the base against which to compute the offset for the first element of the next row.

The algorithm is simple and easily implemented. This algorithm can never achieve better than a factor of two compression relative to 16-bit raw data or 4 relative to 32-bit raw data, but for most diffraction data the compression will indeed be very close to these ideal values. It also has the advantage that integer values up to 32 bits (or 31 bits and sign) may be stored efficiently without the need for special over-load tables. It is a fixed algorithm which does not need to calculate any image statistics, so is fast.

The algorithm works because of the following property of almost all diffraction data and much other image data: The value of one element tends to be close to the value of the adjacent elements, and the vast majority of the differences use little of the full dynamic range. However, noise in experimental data means that run-length encoding is not useful (unless the image is separated into different bit-planes). If a variable length code is used to store the differences, with the number of bits used being inversely proportional to the probability of occurrence, then compression ratios of 2.5 to 3.0 may be achieved. However, the optimum encoding becomes dependent of the exact properties of the image, and in particular on the noise. Here a lower compression ratio is achieved, but the resulting algorithm is much simpler and more robust.

Let us look at an example, of two 1000 x 1000 flat field images presented as a mimimal imgCIF file. The first image uses 32-bit unsigned integers and the second image uses 16-bit unsigned integers.

The imgCIF file begins with some identifying comments (magic numbers) to track the version of the dictionary and library:

This is followed by the necessary syntax to start a CIF data block and by whatever tags and values are appropriate to describe the experiment. The minimum is something like

eventually we come to the actual binary data, which begins the loop header for the array_data category

with any additional tags needed, and then the data itself, which starts with the mini-header:

The binary data begins with the hex byte 80 to flag the need for a value that will not fit in one byte. That is followed by the small_endian hex value 3E8 saying that the first delta is 1000. Then 999,999 bytes of zero follow, since this is a flat field, with all values equal to zero. That gives us our entire 1000x1000 compressed flat field. However, because we asked for 4095 bytes of padding, there is an additional 4095 bytes of zero that are not part of the compressed field. They are just pad and can be ignored. Finally, after the pad, the CIF text field that began with

The only difference is that we have declared this array to be 16-bit and have chosen a different binary id (2 instead of 1). Even the checksum is the same.

3.3.4 Nibble_offset compression

The nibble offset algorithm is a variant on A. P. Hammersley's byte offset algorithm. The major differences are that the compression modes are "sticky", the compression can be reset at any point to allow for block parallelism, and the basic unit of compression is the nibble, but for very clean data, the dibit is also supported.

The data stream starts with and in general uses a mode-setting octet presented in one if three forms, a single dibit a0, two dibits a0, a1, or two dibits and a nibble a0, a1, b:

The reset to zero is followed by a new mode octet A reset to zero resets the prior value for delta to zero

The up n modes code is followed immediately by a dibit specifying 2 less than the number of modes by which to change, and then by a delta in the mode.

Note that up n modes has no effect until an actual mode has been set and can be used immediately after a reset to pad to nibble, octet or double-word boundaries.

Once a mode is established, it is followed by a stream of deltas of that size (for modes 2 or 4-64) or by one delta of that size and then a stream of deltas of the size that was in effect before an up or down giving little-endian offsets from the currently accumulated value. If the offset is one of the following in the indicated mode

it is followed by the new mode as 1 or 2 dibits or 2 dibits and a nibble a1 a1 b. If a1 is 1 or 2 or 3, that is the new mode. If a1 is zero and a2 is 1 or 2 the new mode is a2*4. If a2 is 3 the new mode is a2*2. If both a1 and a2 are zero, the new mode is b*16 unless b is 3. If b is 3 the new mode is b*4

The 0xC0 flag is followed by a second mode giving the number of bytes of image starting offset address followed by the image offset address followed by the mode of that data. 0xC0 also acts as a reset. Use of the 0xC0 flag is not required. Addresses default to sequential starting from 0, but is provided to faciliate parallel compression.

3.4 Access to CBFlib compressions from HDF5

The filter has been registered with the HDF5 group as 32006, and cbf.h includes the symbolic name for the filter CBF_H5Z_FILTER_CBF.

The source and header of the CBFlib filter plugin are cbf_hdf5_filter.c and cbf_hdf5_filter.h. To use the filter in C applications, you will need to include cbf_hdf5_filter.h in the application and have the cbflib.so library in the search path used by HDF5 1.8.11. The HDF group says

In the Makefile, tests are done by defining HDF5_PLUGIN_PATH to point to the build kit shared library directory:

In most cases that should be sufficient to allow code to read HDF5 files with datasets compressed with this filter.

In order to write files that use this filter, several relevant values must first be stored into an unsigned int array, cd_values. The header, cbf_hdf5_filter.h, defines the follwing symbolic values for the indices of this array:

Only chunked data may be written using this filter. The recommended chunk size is a single image. The filter writes the chunks using the imgCIF binary section format described in section 3.2.1 including the MIME header. If each chunk is the size of an image, programs such as XDS can use the patterns of the MIME header to skip directly to a frame even in a complex HDF5 file. Typical code to write such chunks would first define the cd_values array and an array of chunk dimensions and create the properties to be used in creating a dataset, as in

4. Installation

CBFlib should be built on a disk with at least 400 megabytes of free space. CBFlib-0.9.2.11.tar.gz is a "gzipped" tar of the code as it now stands. Place the gzipped tar in the directory that is intended to contain a new directory, named CBFlib_0.9.2.11 (the "top-level" directory) and uncompress it with gunzip and unpack it with tar:

As with prior releases, to run the test programs, you will also need Paul Ellis's sample MAR345 image, example.mar2300, and Chris Nielsen's sample ADSC Quantum 315 image, mb_LP_1_001.img as sample data. Both these files will be extracted by the Makefile from CBFlib_0.7.7_Data_Files. Do not download copies into the top level directory.

src/	CBFLIB source files
include/	CBFLIB header files
m4/	CBFLIB m4 macro files (used to build .f90 files)
examples/	Example program source files
doc/	Documentation
lib/	Compiled CBFLIB library
bin/	Executable example programs
html_images/	JPEG images used in rendering the HTML files

For instructions on compiling and testing the library, go to the top-level directory and type:

The CBFLIB source and header files are in the "src" and "include" subdirectories. The FCBLIB source and m4 files are in the "src" and "m4" subdirectories. The files are:

src/	include/	m4/	Description
cbf.c	cbf.h		CBFLIB API functions
cbf_alloc.c	cbf_alloc.h		Memory allocation functions
cbf_ascii.c	cbf_ascii.h		Function for writing ASCII values
cbf_binary.c	cbf_binary.h		Functions for binary values
cbf_byte_offset.c	cbf_byte_offset.h		Byte-offset compression
cbf_canonical.c	cbf_canonical.h		Canonical-code compression
cbf_codes.c	cbf_codes.h		Encoding and message digest functions
cbf_compress.c	cbf_compress.h		General compression routines
cbf_context.c	cbf_context.h		Control of temporary files
cbf_file.c	cbf_file.h		File in/out functions
cbf_lex.c	cbf_lex.h		Lexical analyser
cbf_packed.c	cbf_packed.h		CCP4-style packing compression
cbf_predictor.c	cbf_predictor.h		Predictor-Huffman compression (not implemented)
cbf_read_binary.c	cbf_read_binary.h		Read binary headers
cbf_read_mime.c	cbf_read_mime.h		Read MIME-encoded binary sections
cbf_simple.c	cbf_simple.h		Higher-level CBFlib functions
cbf_string.c	cbf_string.h		Case-insensitive string comparisons
cbf_stx.c	cbf_stx.h		Parser (generated from cbf.stx.y)
cbf_tree.c	cbf_tree.h		CBF tree-structure functions
cbf_uncompressed.c	cbf_uncompressed.h		Uncompressed binary sections
cbf_write.c	cbf_write.h		Functions for writing
cbf_write_binary.c	cbf_write_binary.h		Write binary sections
cbf.stx.y			bison grammar to define cbf_stx.c (see WARNING)
md5c.c	md5.h		RSA message digest software from mpack
	global.h
fcb_atol_wcnt.f90			Function to convert a string to an integer
fcb_ci_strncmparr.f90			Function to do a case-insensitive comparison of a string to a byte array
fcb_nblen_array.f90			Function to determine the non-blank length of a byte array
fcb_read_byte.f90			Function to read a single byte
fcb_read_line.f90			Function to read a line into a byte array
fcb_skip_whitespace.f90			Function to skip whitespace and comments in a MIME header
		fcb_exit_binary.m4	Function to skip past the end of the current binary text field
		fcb_next_binary.m4	Function to skip to the next binary
		fcb_open_cifin.m4	Function to open a CBF file for reading
		fcb_packed.m4	Functions to read a JPA CCP4 compressed image
		fcb_read_bits.m4	Functions to read nay number of bits as an integer
		fcb_read_image.m4	Functions to read the next image in I2, I4, 3D_I2 and 3D_I4 format
		fcb_read_xds_i2.m4	Function to read a single xds image.
		fcblib_defines.m4	General m4 macro file for FCBLIB routines.

In the "examples" subdirectory, there are 2 additional files used by the example programs (section 5) for reading MAR300, MAR345 or ADSC CCD images:

makecbf.c	Make a CBF file from an image
img2cif.c	Make an imgCIF or CBF from an image
cif2cbf.c	Copy a CIF/CBF to a CIF/CBF
convert_image.c	Convert an image file to a cbf using a template file
cif2c.c	Convert a template cbf file into a function to produce the same template in an internal cbf data structure
testcell.C	Exercise the cell functions

as well as three template files: template_adscquantum4_2304x2304.cbf, template_mar345_2300x2300.cbf, and template_adscquantum315_3072x3072.cbf.

Two additional examples (test_fcb_read_image.f90 and test_xds_binary.f90) are created from two files (test_fcb_read_image.m4 and test_xds_binary.m4) in the m4 directory.

CBFlib.html	This document (HTML)
CBFlib.txt	This document (ASCII)
CBFlib_NOTICES.html	Important NOTICES -- PLEASE READ
CBFlib_NOTICES.txt	Important NOTICES -- PLEASE READ
gpl.txt	GPL -- PLEASE READ
lgpl.txt	LGPL -- PLEASE READ
cbf_definition_rev.txt	Draft CBF/ImgCIF definition (ASCII)
cbf_definition_rev.html	Draft CBF/ImgCIF definition (HTML)
cif_img.html	CBF/ImgCIF extensions dictionary (HTML)
cif_img.dic	CBF/ImgCIF extensions dictionary (ASCII)
ChangeLog,html	Summary of change history (HTML)
ChangeLog	Summary of change history (ASCII)

5. Example programs

The example programs makecbf.c, img2cif.c and convert_image.c read an image file from a MAR300, MAR345 or ADSC CCD detector and then uses CBFlib to convert it to CBF format (makecbf) or either imgCIF or CBF format (img2cif). makecbf writes the CBF-format image to disk, reads it in again, and then compares it to the original. img2cif just writes the desired file. makecbf works only from stated files on disk, so that random I/O can be used. img2cif includes code to process files from stdin and to stdout. convert_image reads a template as well as the image file and produces a complete CBF. The program convert_minicbf reads a minimal CBF file with just and image and some lines of text specifying the parameters of the data collection as done at SLS and combines the result with a template to produce a full CBF. The program cif2cbf can be used to convert among carious compression and encoding schemes. The program sauter_test.C is a C++ test program contributed by Nick Sauter to help in resolving a memory leak he found. The programs adscimg2cbf and cbf2adscimg are a "jiffies" contributed by Chris Nielsen of ADSC to convert ADSC images to imgCIF/CBF format and vice versa.

makecbf.c is a good example of how many of the CBFlib functions can be used. To compile makecbf and the other example programs use the Makefile in the top-level directory:

makecbf

cif2cbf

The test program cif2cbf uses many of the same command line options as img2cif, but accepts either a CIF or a CBF as input instead of an image file:

convert_image

The program convert_image requires two arguments: imagefile and cbffile. Those are the primary input and output. The detector type is extracted from the image file or from the command line, converted to lower case and used to construct the name of a template cbf file to use for the copy. The template file name is of the form template_name_columnsxrows. The full set of options is:

convert_minicbf

The program convert_minicbf requires two arguments: minicbf and cbffile. Those are the primary input and output. The detector type is extracted from the image file or from the command line, converted to lower case and used to construct the name of a template cbf file to use for the copy. The template file name is of the form template_name_columnsxrows. The full set of options is:

testreals, testflat and testflatpacked

The example programs testreals, testflat and testflatpacked exercise the handling of reals, byte_offset compression and packed compression. Each is run without any arguments. testreals will read real images from the data file testrealin.cbf and write a file with real images in testrealout.cbf, which should be identical to testrealin.cbf. testflat and testflatpacked read 4 1000x1000 2D images and one 50x60x70 3D image and produce an output file that should be identical to the input. testflat reads testflatin.cbf and produces testflatout.cbf using CBF_BYTE_OFFSET compression. testflatpacked reads testflatpackedin.cbf and produces testflatpackedout.cbf. The images are:

test_fcb_read_image, test_xds_binary

The example programs test_fcb_read_image and test_xds_binary are designed read the output of testflat and testflatpacked using the FCBlib routines in lib/libfcb. test_xds_binary reads only the first image and closes the file immediately. test_fcb_read_image reads all 5 images from the input file. The name of the input file should be provided on stdin, as in:

In order to compile these programs correctly for the G95 compiler it is important to set the record size for reading to be no larger than the padding after binary images. This in controlled in Makefile by the line M4FLAGS = -Dfcb_bytes_in_rec=131072 which provides good performance for gfortran. For g95, this line must be changed to M4FLAGS = -Dfcb_bytes_in_rec=4096

sauter_test

The program sauter_test.C is a C++ test program contributed by Nick Sauter to help in resolving a memory leak he found. The program is run as bin/sauter_test and should run long enough to allow a check with top to ensure that it has constant memory demands. In addition, starting with release 0.7.8.1, the addition of -DCBFLIB_MEM_DEBUG to the compiler flags will cause detailed reports on memory use to stderr to be reported.

adscimg2cbf

The example program adscimg2cbf accepts any number of raw or compressed ADSC images with .img, .img.gz, .img.bz2 or .img.Z extensions and converts each of them to an imgCIF/CBF file with a .cbf extension.

adscimg2cbf

The example program cbf2adscimg accepts any number of cbfs of ADSC images created by adscimg1cbf or convert_image and produces raw or compressed adsc image files with .img, .img.gz or .img.bz2 extensions.

tiff2cbf

The test program tiff2cbf converts a tiff data file to a cbf data file. The program converts the tiff data samples directly into a minicbf with the tiff header stored at the value of _array_data.header_contents. This conversion is supported for the sample formats SAMPLEFORMAT_UINT (unsigned integer data), SAMPLEFORMAT_INT (unsigned integer data), SAMPLEFORMAT_INT (signed integer data), SAMPLEFORMAT_IEEEFP (IEEE floating point data), SAMPLEFORMAT_COMPLEXINT (complex signed int) and SAMPLEFORMAT_COMPLEXIEEEFP (complex ieee floating). Conversions from these formats to other CBF formats can be handled by cif2cbf. If you wish to convert and xxx.tif written with IEEE floating point samples into a CBF with integer values compressed by byte-offset compression for use by XDS, creating an xxx_view.cbf with values clipped between 0 and 100, and an xxx_xds.cbf with unclipped values for processing:

minicbf2nexus

This program takes some minicbf files describing a single scan and axis configuration settings for them and creates a nexus file containing the same data. As this is an early version of the program it lacks a lot of useful functionality and should not be assumed to be stable.

Where test files 1, 4 & 5 are each single-image miniCBF files and test file 2 & 3 is created by 'cat'ing together two single-image miniCBF files

Axes are declared by the map keyword as the name of the axis in the minicbf file, which must match exactly, followed by the keyword to and then the name that will be given to the axis in the resulting nexus file. Each axis is treated as a rotation axis and should have a vector which defines the axis of rotation in the 3D coordinate frame used by nexus, this should be 3 numbers within square brackets separated by spaces and does not need to be normalised. Each axis may also depend on a nother axis by using the keyword depends-on folowed by the name of the nexus axis it depends on, or . if it does not depend on another axis, omitting a dependency as shown on the final line of the example above is not recommended as it will eventually be a fatal error. The vector and depends-on declarations do not need to be on the same line.

The Sample keyword is used to define a dependency for the sample being scanned and should be followed by a depends-on declaration which defines the name of the nexus axis that the sample depends on.

The final line of the config file should be blank to allow for some simple integrity tests.

A continuous chain of dependencies should be formed from the sample to the nexus coordinate system, otherwise there is insufficient information available to properly describe the orientation of the sample. This will be enforced in later versions, with a fatal error if insufficient information is provided.

cbf2nexus

This program takes some CBF files describing a single scan and converts them to a single NeXus file containing the same data. It can also be used to merge a CBF file into an existing NeXus file.

This creates a single NeXus file containing two copies of the 'adscconverted' CBF file.

nexus2cbf

This program converts a single frame of data from a nexus file to a cbf file with a given name. The primary purpose of this program is to help verify that data can be recovered after being converted to NeXus format, to check that it hasn't been lost or mangled.

testhdf5

This program runs a set of unit tests on the HDF5 abstraction layer. These are designed to ensure everything is working correctly, to help locate bugs and prevent regressions. A short summary will be printed detailing the number of tests passed, the number of tests failed and the number of components skipped. If any tests fail or are skipped then some additional output should be produced to help identify the cause of the error so that it is easier to fix.

The program does not take any command-line arguments, and creates a file called testfile.h5 in its working directory for use in the tests.

testulp

This program runs a set of unit tests on the ULP comparison functions. These are designed to ensure everything is working correctly, to help locate bugs and prevent regressions. A short summary will be printed detailing the number of tests passed, the number of tests failed and the number of components skipped. If any tests fail or are skipped then some additional output should be produced to help identify the cause of the error so that it is easier to fix.

CBF_FORMAT	The file format is invalid
CBF_ALLOC	Memory allocation failed
CBF_ARGUMENT	Invalid function argument
CBF_ASCII	The value is ASCII (not binary)
CBF_BINARY	The value is binary (not ASCII)
CBF_BITCOUNT	The expected number of bits does not match the actual number written
CBF_ENDOFDATA	The end of the data was reached before the end of the array
CBF_FILECLOSE	File close error
CBF_FILEOPEN	File open error
CBF_FILEREAD	File read error
CBF_FILESEEK	File seek error
CBF_FILETELL	File tell error
CBF_FILEWRITE	File write error
CBF_IDENTICAL	A data block with the new name already exists
CBF_NOTFOUND	The data block, category, column or row does not exist
CBF_OVERFLOW	The number read cannot fit into the destination argument. The destination has been set to the nearest value.
CBF_UNDEFINED	The requested number is not defined (e.g. 0/0; new for version 0.7).
CBF_NOTIMPLEMENTED	The requested functionality is not yet implemented (New for version 0.7).

MSG_DIGEST:	Instructs CBFlib to check that the digest of the binary section matches any header digest value. If the digests do not match, the call will return CBF_FORMAT. This evaluation and comparison is delayed (a "lazy" evaluation) to ensure maximal processing efficiency. If an immediately evaluation is required, see MSG_DIGESTNOW, below.
MSG_DIGESTNOW:	Instructs CBFlib to check that the digest of the binary section matches any header digeste value. If the digests do not match, the call will return CBF_FORMAT. This evaluation and comparison is performed during initial parsing of the section to ensure timely error reporting at the expense of processing efficiency. If a more efficient delayed ("lazy") evaluation is required, see MSG_DIGEST, above.
MSG_DIGESTWARN:	Instructs CBFlib to check that the digest of the binary section matches any header digeste value. If the digests do not match, a warning message will be sent to stderr, but processing will attempt to continue. This evaluation and comparison is first performed during initial parsing of the section to ensure timely error reporting at the expense of processing efficiency. An mismatch of the message digest usually indicates a serious error, but it is sometimes worth continuing processing to try to isolate the cause of the error. Use this option with caution.
MSG_NODIGEST:	Do not check the digest (default).
PARSE_BRACKETS:	Accept DDLm bracket-delimited [item,item,...item] or {item,item,...item} or (item,item,...item) constructs as valid, stripping non-quoted embedded whitespace and comments. These constructs may span multiple lines.
PARSE_LIBERAL_BRACKETS:	Accept DDLm bracket-delimited [item,item,...item] or {item,item,...item} or (item,item,...item) constructs as valid, stripping embedded non-quoted, non-separating whitespace and comments. These constructs may span multiple lines. In this case, whitespace may be used as an alternative to the comma.
PARSE_TRIPLE_QUOTES:	Accept DDLm triple-quoted """item,item,...item""" or '''item,item,...item''' constructs as valid, stripping embedded whitespace and comments. These constructs may span multiple lines. If this flag is set, then ''' will not be interpreted as a quoted apoptrophe and """ will not be interpreted as a quoted double quote mark and
PARSE_NOBRACKETS:	Do not accept DDLm bracket-delimited [item,item,...item] or {item,item,...item} or (item,item,...item) constructs as valid, stripping non-quoted embedded whitespace and comments. These constructs may span multiple lines.
PARSE_NOTRIPLE_QUOTES:	No not accept DDLm triple-quoted """item,item,...item""" or '''item,item,...item''' constructs as valid, stripping embedded whitespace and comments. These constructs may span multiple lines. If this flag is set, then ''' will be interpreted as a quoted apostrophe and """ will be interpreted as a quoted double quote mark.

handle	CBF handle.
file	Pointer to a file descriptor.
headers	Controls interprestation of binary section headers.

MIME_HEADERS	Use MIME-type headers (default).
MIME_NOHEADERS	Use a simple ASCII headers.
MSG_DIGEST	Generate message digests for binary data validation.
MSG_NODIGEST	Do not generate message digests (default).
PARSE_BRACKETS	Do not convert bracketed strings to text fields (default).
PARSE_LIBERAL_BRACKETS	Do not convert bracketed strings to text fields (default).
PARSE_NOBRACKETS	Convert bracketed strings to text fields (default).
PARSE_TRIPLE_QUOTES	Do not convert triple-quoted strings to text fields (default).
PARSE_NOTRIPLE_QUOTES	Convert triple-quoted strings to text fields (default).
PAD_1K	Pad binary sections with 1023 nulls.
PAD_2K	Pad binary sections with 2047 nulls.
PAD_4K	Pad binary sections with 4095 nulls.

ENC_BASE64	Use BASE64 encoding (default).
ENC_QP	Use QUOTED-PRINTABLE encoding.
ENC_BASE8	Use BASE8 (octal) encoding.
ENC_BASE10	Use BASE10 (decimal) encoding.
ENC_BASE16	Use BASE16 (hexadecimal) encoding.
ENC_FORWARD	For BASE8, BASE10 or BASE16 encoding, map bytes to words forward (1234) (default on little-endian machines).
ENC_BACKWARD	Map bytes to words backward (4321) (default on big-endian machines).
ENC_CRTERM	Terminate lines with CR.
ENC_LFTERM	Terminate lines with LF (default).

handle	CBF handle.
datablockname	The name of the new data block.
saveframename	The name of the new save frame.

handle	CBF handle.
categoryname	The name of the new category.

handle	CBF handle.
rownumber	The row number of the new row.

handle	CBF handle.
datablocks	Pointer to the destination data block count.

handle	CBF handle.
categories	Pointer to the destination category count.

handle	CBF handle.
columns	Pointer to the destination column count.

handle	CBF handle.
rows	Pointer to the destination row count.

handle	CBF handle.
datablock	Number of the data block to select.

handle	CBF handle.
category	Number of the category to select.

handle	CBF handle.
columnname	Pointer to the destination column name pointer.
newcolumnname	New column name pointer.

handle	CBF handle.
row	Pointer to the destination row number.

"null"	for a null value indicated by a "." or a "?"
"bnry"	for a binary value
"word"	for an unquoted string
"dblq"	for a double-quoted string
"sglq"	for a single-quoted string
"text"	for a semicolon-quoted string (multiline text field)
"prns"	for a parenthesis-bracketed string (multiline text field)
"brcs"	for a brace-bracketed string (multiline text field)
"bkts"	for a square-bracket-bracketed string (multiline text field)
"tsqs"	for a treble-single-quote quoted string (multiline text field)
"tdqs"	for a treble-double-quote quoted string (multiline text field)

handle	CBF handle.
typeofvalue	Pointer to the destination type-of-value string pointer.

handle	CBF handle.
number	pointer to the number.
defaultvalue	default number value.

handle	CBF handle.
format	Format for the number.
number	Floating-point value.

handle	CBF handle.
binary_id	Pointer to the destination integer binary identifier.
array	Pointer to the destination array.
elsize	Size in bytes of each destination array element.
elsigned	Set to non-0 if the destination array elements are signed.
elements	The number of elements to read.
elements_read	Pointer to the destination number of elements actually read.

f	integer function to execute.
c	statement to execute on failure.

byte_order	pointer to the returned string
real_format	pointer to the returned string

handle	CBF handle.
dictionary	Pointer to CBF handle of dictionary.
dictionary_in	CBF handle of dcitionary.

handle	CBF handle.
tagname	tag name which may be an alias.
tagroot	pointer to a returned tag root name.
tagroot_in	input tag root name.

CBFlib

Before using this software, please read the for important disclaimers and the IUCr Policy on the Use of the Crystallographic Information File (CIF) and for other important information.

Version History

Known Problems

Foreword

Contents

2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf, cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf, cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image, cbf_set_real_3d_image, cbf_set_real_3d_image_fs, cbf_set_real_3d_image_sf

Before using this software, please read the

for important disclaimers and the IUCr Policy on the Use of the Crystallographic Information File (CIF) and for other important information.

2.4.27 cbf_set_image, cbf_set_image_fs, cbf_set_image_sf,
cbf_set_real_image, cbf_set_real_image_fs, cbf_set_real_image_sf,
cbf_set_3d_image, cbf_set_3d_image, cbf_set_3d_image,
cbf_set_real_3d_image, cbf_set_real_3d_image_fs, cbf_set_real_3d_image_sf

handle	Pointer to a CBF handle.
file	Pointer to a file descriptor.

handle	CBF handle.
diffrn_id	Pointer to the destination value pointer.
default_id	Character string default value.

handle	CBF handle.
crystal_id	Pointer to the destination value pointer.

handle	CBF handle.
polarizn_source_ratio	Pointer to the destination polarizn_source_ratio.
polarizn_source_norm	Pointer to the destination polarizn_source_norm.

handle	CBF handle.
div_x_source	Pointer to the destination div_x_source.
div_y_source	Pointer to the destination div_y_source.
div_x_y_source	Pointer to the destination div_x_y_source.

a0 a1 b	octet	meaning
00 00 0000	0x00	reset to zero
01	0x01	up 1 mode
10	0x02	dibit mode
11	0x03	up n modes
00 01	0x04	nibble mode
00 11	0x0C	6-bit mode
00 10	0x08	byte mode
00 00 0011	0x30	12-bit word mode
00 00 0001	0x10	16-bit word mode
00 00 0010	0x20	32-bit word mode
00 00 0100	0x40	64-bit word mode
00 00 1100	0xC0	specify starting address

symbol	value	meaning
CBF_H5Z_FILTER_CBF_NELMTS	11	size of cd_values
CBF_H5Z_FILTER_CBF_COMPRESSION	0	one of the compressions (see 3.2.2)
CBF_H5Z_FILTER_CBF_RESERVED	1	reserved for future use, should be set to zero
CBF_H5Z_FILTER_CBF_BINARY_ID	2	binary ID of the array (default 1)
CBF_H5Z_FILTER_CBF_ELSIZE	3	element size in octets
CBF_H5Z_FILTER_CBF_ELSIGN	4	1 if signed, 0 if unsigned
CBF_H5Z_FILTER_CBF_REAL	5	1 if a real array, 0 if an integer array
CBF_H5Z_FILTER_CBF_DIMOVER	6	the total number of elements in the array
CBF_H5Z_FILTER_CBF_DIMFAST	7	the fast dimension
CBF_H5Z_FILTER_CBF_DIMMID	8	the middle dimension
CBF_H5Z_FILTER_CBF_DIMSLOW	9	the slow domension
CBF_H5Z_FILTER_CBF_PADDING	10	the padding