-
Notifications
You must be signed in to change notification settings - Fork 21
/
Copy pathREADME
12233 lines (8821 loc) · 468 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
[IUCr Home Page] [CIF Home Page] [CBF/imgCIF]
----------------------------------------------------------------------
| IUCr Home Page | CIF Home Page | CBF/imgCIF | CBFlib |
| NOTICE | GPL | LGPL | imgCIF dictionary |
| Click Here to Make a Donation |
CBFlib
An API for CBF/imgCIF
Crystallographic Binary Files with ASCII Support
Version 0.9.8
3 April 2025
/
by
Paul J. Ellis
Stanford Synchrotron Radiation Laboratory
and
Herbert J. Bernstein
Information Systems Consultant
hbernstein at bnl dot gov
© Copyright 2006, 2007, 2008, 2011, 2013, 2014, 2025 Herbert J. Bernstein
----------------------------------------------------------------------
YOU MAY REDISTRIBUTE THE CBFLIB PACKAGE UNDER THE TERMS OF THE GPL.
ALTERNATIVELY YOU MAY REDISTRIBUTE THE CBFLIB API UNDER THE TERMS OF THE
LGPL.
----------------------------------------------------------------------
Before using this software, please read the
NOTICE
for important disclaimers and the IUCr Policy on the Use of the Crystallographic
Information File (CIF) and for other important information.
Work on imgCIF and CBFlib currentlysupported in part by the the National
Institutes of Health under grant R24-GM154040-01 and in the past by U. S.
Department of Energy (DOE) under grants ER63601-1021466-0009501 and
ER64212-1027708-0011962, by the U. S. National Science Foundation (NSF)
under grants DBI-0610407, DBI-0315281 and EF-0312612, the U. S. National
Institutes of Health (NIH) under grants 1R15GM078077 from NIGMS and
1R13RR023192 from NCRR and funding from the International Union for
Crystallographyn (IUCr). The content is solely the responsibility of the
authors and does not necessarily represent the official views of DOE, NSF,
NIH, NIGMS, NCRR or IUCr. Recent work on integration among CBF, HDF5 and
NeXus supported in part by Pandata ODI (EU 7th Framework Programme)
----------------------------------------------------------------------
Version History
Version Date By Description
0.1 Apr. PJE This was the first CBFlib release. It supported
1998 binary CBF files using binary strings.
0.2 Aug. HJB This release added ascii imgCIF support using
1998 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. PJE This release cleaned up the changes made for
1998 version 0.2, allowing multi-threaded use of the
code, and removing dependence on the mpack package.
0.4 Nov. HJB This release merged much of the message digest
1998 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. PJE This release greatly increased the speed of
1998 processing by allowing for deferred digest
evaluation.
0.6 Jan. HJB This release removed the redundant information
1999 (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. HP This release fixed a memory leak due to
2001 (per misallocation by size of cbf_handle instead of
HJB) cbf_handle_struct
0.7 Mar. PJE This release added high-level instructions based
2001 on the imgCIF dictionary version 1.1.
0.7.1 Mar. PJE The high-level functions were revised to permit
2001 future expansion to files with multiple images.
0.7.2 Apr. HJB This release adjusted cbf_cimple.c to conform to
2001 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. PJE This release modified cbf_simple.c to reorder
2002 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 HJB This release reflects changes for base 32K
2007 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 HJB This release is a patch to 0.7.7 to change the
2007 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 HJB This release is a patch to 0.7.7.1 to add testing
2007 for JPA packed compression and to respect signs
declared in the MIME header.
0.7.7.3 April HJB This release is a patch to 0.7.7.3 to add f90
2007 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, Update to 0.7.8.1 to add ADSC jiffie by Chris
HJB Nielsen, and to add ..._fs and ..._sf macros.
0.7.9 Dec 2007 CN, Identical to 0.7.8.2 except for a cleanup of
HJB deprecated examples, e.g. diffrn_frame_data
0.7.9.1 Jan 2008 CN, Update to 0.7.8.2 to add inverse ADSC jiffie by
HJB Chris Nielsen, to clean up problems in handling
maps for RasMol.
0.8.0 Jul 2008 GT, Cleanup of 0.7.9.1 to start 0.8 series.
HJB
0.8.1 Jul 2009 EZ,
CN, Release with EZ's 2008 DDLm support using JH's
PC, PyCifRW, also cbff f95 wrapper code, PC's java
GW, bindings.
JH,
HJB
0.9.1 Aug 2010 PC,
EE,
JLM, Release with EE's Dectris template software,
NS, also with vcif3, new arvai_test, sequence_match.
EZ,
HJB
0.9.2 Feb 2011 PC,
EE, New default release with updated pycbf, tiff
JLM, support, removal of default use of PyCifRW to avoid
NS, Fedora license issue.
EZ,
HJB
0.9.3 Oct 2013 JS, Added low-level 'cbf_H5*' functions for
HJB 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 JS, Refactored implementation of the NXMX application
2014 HJB 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 HJB This is a production release for single detector
2014 module single crystal MX NeXus support.
0.9.6 May 2020 HJB This is the full release supporting the
integration of CBF and NeXus, including support for
the NeXus NXpdb embedding of CIF files in NeXus
files. *** IMPORTANT: Because of the requirements
of dynamic loading to support the compressions used
by the Dectris NeXus/HDF5 format, all applications
require setting of library and plugin paths. See
the initialization file cbflib.ini, which should be
sourced before running any applications ***.. The
changes from 0.9.5 to 0.9.6 are:
improve error reporting in examples/cbf2nexus.c
improve examples/cbf_standardize_numbers.c
add bslz4 compression option to hdf5 in cif2cbf
minor cleanup in examples/convert_minicbf.c
minor cleanup in examples/nexus2cbf.c
minor cleanup in examples/sequence_match.c
minor cleanup in include/cbf_context.h
add value clipping to cbf_copy
minor cleanuo in cbf_hdf5.h
0.9.7 June HJB This is a production release with misc minor
2021 updates. The changes from 0.9.6 to 0.9.7 are:
update the manual
cleanup minor bugs is examples/adscimg2cbf.c,
adscimg2cbf_sub.c, cbf2adscimg_sub.c
fix examples/cbf_standardize_numbers.c
fix examples/testcbf.c
fix examples/testcbf.java
fix examples/testhdf5.c
fix include/cbf_hdf5.h
fix include/img.h
fix Java.txt
fix handling of hex to be int in fcblib_defines,
fcb_next_binary, fcb_packed, fcb_read_bits,
fcb_read_xds_i2
fix pycbf/cbf_autoscrolled_window.py,
cbf_axis_text.py, various wrappers, bytestrings in
tests, xmas/readmarheader.py, xmasheaders.py
fix cbf.c
fix cbf_context.c, cbf_copy.c, cbf_hdf5.c,
cbf_hdf5_filter.c, cbf_simple.c, cbf_stx.c
fix fcb_atol_wcnt.f90, fcb_nblen_array.f90,
fcb_read_line.f90, fcb_skip_whitespace.f90
fix img.c
0.9.8 April DP, This is a final CBFlib release prior to moving
2025 JH, all future development under the auspices of the
ND, DIALS project. In the past the main repository for
HJB CBFlib was at http://github.com/yayahjb/cbflib. In
the future tha main repository for CBFlib will be
at http://github.com/dials/cbflib. For the
convenience of users of legacy versions of CBFlib,
there will be legacy fork of the repository frozen
at the 0.9.8 revision level
http://github.com/nsls-ii-mx/cbflib The changes
from 0.9.7 to 0.9.8 are:
in cif2cbf add -I-1, -I-2, -I-4, and -I-8 options
for unsigned integers, --{sum|summing} sumrange
option to sum images, and
--xdsb2z|rotate-xds-beam-to-z
beamcentx,beamcenty,beamcentz assume the beam is
along [beamx, beamy, beamz] relative to the image
and rotate the image so that the beam is along
[0,0,-1]
split support for languages other than C/C++ to use
the 2022 swig-fortran kit for fortran and a recent
swig kit for python
update tiff2cbf for multiple compression options
update cbf_copy options and fix typos
drop all support for python2 in favor of python3
fix buffer overruns in
examples/dectris_cbf_template_test/cbf_template_t.c
fix errors in examples/testcbf.java
add zstd compression option for hdf5 files
update fcblib_defines
update pycbf wrappers
fix buffer overflow in cbf_binary.c
fix parens in cbf_codes.c
fix bug in cbf_nibble_offset.c
fix tab definition in fcb_skip_whitespace.f90
preliminary changes for move from make to cmake by
J. Hattne
add third dimension in examples/img2cif.c,
examples/makecbf.c, examples/nexus2cbf.c
fix bugs in examples/tiff2cbf.c
examples/tif_sprint.c
make handling of version number changes in tests
data general
fix typoi in test_cbf_airy_disk call
fix bug in pycbf_test1.py
fix regex dependency handling in cbf_hdf5.c
----------------------------------------------------------------------
Known Problems
Foreword
In order to work with CBFlib, you need: the source code from github by
downloadng a release or the lastest code from
http://github.com/dials/cbflib
Be careful about space. A full build and test can use 2GB or more.
To run the test programs, you will also need Paul Ellis's sample MAR345
image, example.mar2300, Chris Nielsen's sample ADSC Quantum 315 image,
mb_LP_1_001.img, and Eric Eikenberry's SLS sample Pilatus 6m image,
insulin_pilatus6m, as sample data. In addition there are is a PDB mmCIF
file, 9ins.cif, and 3 special test files testflatin.cbf,
testflatpackedin.cbf and testrealin.cbf. All these files will be dowloaded
and extracted by the Makefile from CBFlib_0.9.8_Data_Files_Input. Do not
download copies into the top level directory.
In addition, the kit will need tiff and hdf5 libraries.
Future versions of CBFlib will use the cmake build system. Version 0.9.8
is the last Makefile build,
The Makefiles use GNU make constructs, such as ifeq and ifneq. If you need
to use a different version of make, you will need to edit out the
conditionals
The operation of the Makefiles is sensitive to the following environment
variables:
* CBFLIB_USE_PYCIFRW If you define this environment variable, you may
rebuild the Makefiles to include James Hester's PyCifRW. The process
under bash is:
export CBFLIB_USE_PYCIFRW=yes
cd CBFlib_0.9.5
touch m4/Makefile.m4
make Makefiles
* CBF_DONT_USE_LONG_LONG If you define this environment variable, use of
the long long data type in CBFlib is replaced by use of a struct. The
Makefiles do not need to be rebuilt. Makefile_MINGW does not use the
long long data type even without defining this variable.
* NOFORTRAN If you define this environment variable, use of the fortran
compiler is suppressed.
If necessary, adjust the definition of CC and C++ and other defintions in
Makefile to point to your compilers. Set the definition of CFLAGS to an
appropriate value for your C and C++ compilers, the definition of F90C to
point to your Fortan-90/95 compiler, and the definitions of F90FLAGS and
F90LDFLAGS to approriate values for your Fortan-90/95 compilers, and then
make all
make tests
If you do not have a fortran compiler, you will need edit the Makefile or
to define the variable NOFORTRAN, either in the Makefile or in the
environment
We have included examples of CBF/imgCIF files produced by CBFlib in the
test data CBFlib_0.9.5_Data_Files_Output.tar.gz, the current best draft of
the CBF Extensions Dictionary, and of Andy Hammersley's CBF definition,
updated to become a DRAFT CBF/ImgCIF DEFINITION.
CBFlib 0.9.5 includes a program, tiff2cbf, to convert from tiff files to
CBF files, that requires an augmented version of tiff-3.9.4 called
tiff-3.9.4-rev-6Feb11, that installs into the CBFlib_0.9.2.11 directory.
If a system copy is desired, download and install
http://downloads.sf.net/cbflib/tiff-3.9.4-rev-6Feb11.tar.gz
----------------------------------------------------------------------
Contents
* 1. Introduction
* 2. Function descriptions
* 2.1 General description
* 2.1.1 CBF handles
* 2.1.2 CBF goniometer handles
* 2.1.3 CBF detector handles
* 2.1.4 CBF positioner handles
* 2.1.5 Return values
* 2.2 Reading and writing files containing binary sections
* 2.2.1 Reading binary sections
* 2.2.2 Writing binary sections
* 2.2.3 Summary of reading and writing files containing binary
sections
* 2.2.4 Ordering of array indices
* 2.3 Low-level function prototypes
* 2.3.1 cbf_make_handle
* 2.3.2 cbf_free_handle
* 2.3.3 cbf_read_file, cbf_read_widefile
* 2.3.4 cbf_write_file, cbf_write_widefile
* 2.3.5 cbf_new_datablock, cbf_new_saveframe
* 2.3.6 cbf_force_new_datablock, cbf_force_new_saveframe
* 2.3.7 cbf_new_category
* 2.3.8 cbf_force_new_category
* 2.3.9 cbf_new_column
* 2.3.10 cbf_new_row
* 2.3.11 cbf_insert_row
* 2.3.12 cbf_delete_row
* 2.3.13 cbf_set_datablockname, cbf_set_saveframename
* 2.3.14 cbf_reset_datablocks
* 2.3.15 cbf_reset_datablock, cbf_reset_saveframe
* 2.3.16 cbf_reset_category
* 2.3.17 cbf_remove_datablock, cbf_remove_saveframe
* 2.3.18 cbf_remove_category
* 2.3.19 cbf_remove_column
* 2.3.20 cbf_remove_row
* 2.3.21 cbf_rewind_datablock
* 2.3.22 cbf_rewind_category, cbf_rewind_saveframe,
cbf_rewind_blockitem
* 2.3.23 cbf_rewind_column
* 2.3.24 cbf_rewind_row
* 2.3.25 cbf_next_datablock
* 2.3.26 cbf_next_category, cbf_next_saveframe,
cbf_next_blockitem
* 2.3.27 cbf_next_column
* 2.3.28 cbf_next_row
* 2.3.29 cbf_find_datablock
* 2.3.30 cbf_find_category, cbf_find_saveframe,
cbf_find_blockitem
* 2.3.31 cbf_find_column
* 2.3.32 cbf_find_row
* 2.3.33 cbf_find_nextrow
* 2.3.34 cbf_count_datablocks
* 2.3.35 cbf_count_categories, cbf_count_saveframes,
cbf_count_blockitems
* 2.3.36 cbf_count_columns
* 2.3.37 cbf_count_rows
* 2.3.38 cbf_select_datablock
* 2.3.39 cbf_select_category, cbf_select_saveframe,
cbf_select_blockitem
* 2.3.40 cbf_select_column
* 2.3.41 cbf_select_row
* 2.3.42 cbf_datablock_name
* 2.3.43 cbf_category_name
* 2.3.44 cbf_column_name, cbf_set_column_name
* 2.3.45 cbf_row_number
* 2.3.46 cbf_get_value, cbf_require_value
* 2.3.47 cbf_set_value
* 2.3.48 cbf_get_typeofvalue
* 2.3.49 cbf_set_typeofvalue
* 2.3.50 cbf_get_integervalue, cbf_require_integervalue
* 2.3.51 cbf_set_integervalue
* 2.3.52 cbf_get_doublevalue, cbf_require_doublevalue
* 2.3.53 cbf_set_doublevalue
* 2.3.54 cbf_get_integerarrayparameters,
cbf_get_integerarrayparameters_wdims,
cbf_get_integerarrayparameters_wdims_fs,
cbf_get_integerarrayparameters_wdims_sf
cbf_get_realarrayparameters,
cbf_get_realarrayparameters_wdims,
cbf_get_realarrayparameters_wdims_fs,
cbf_get_realarrayparameters_wdims_sf
* 2.3.55 cbf_get_integerarray, cbf_get_realarray
* 2.3.56 cbf_set_integerarray,
cbf_set_integerarray_wdims,
cbf_set_integerarray_wdims_fs,
cbf_set_integerarray_wdims_sf,
cbf_set_realarray,
cbf_set_realarray_wdims, cbf_set_realarray_wdims_fs,
cbf_set_realarray_wdims_sf
* 2.3.57 cbf_failnez
* 2.3.58 cbf_onfailnez
* 2.3.59 cbf_require_datablock
* 2.3.60 cbf_require_category
* 2.3.61 cbf_require_column
* 2.3.62 cbf_require_column_value
* 2.3.63 cbf_require_column_integervalue
* 2.3.64 cbf_require_column_doublevalue
* 2.3.65 cbf_get_local_integer_byte_order,
cbf_get_local_real_byte_order, cbf_get_local_real_format
* 2.3.66 cbf_get_dictionary, cbf_set_dictionary,
cbf_require_dictionary
* 2.3.67 cbf_convert_dictionary
* 2.3.68 cbf_find_tag, cbf_find_local_tag
* 2.3.69 cbf_find_category_root, cbf_set_category_root,
cbf_require_category_root
* 2.3.70 cbf_find_tag_root, cbf_set_tag_root,
cbf_require_tag_root
* 2.3.71 cbf_find_tag_category, cbf_set_tag_category
* 2.4 High-level function prototypes (new for version 0.7)
* 2.4.1 cbf_read_template
* 2.4.2 cbf_get_diffrn_id, cbf_require_diffrn_id
* 2.4.3 cbf_set_diffrn_id
* 2.4.4 cbf_get_crystal_id
* 2.4.5 cbf_set_crystal_id
* 2.4.6 cbf_get_wavelength
* 2.4.7 cbf_set_wavelength
* 2.4.8 cbf_get_polarization
* 2.4.9 cbf_set_polarization
* 2.4.10 cbf_get_divergence
* 2.4.11 cbf_set_divergence
* 2.4.12 cbf_count_elements
* 2.4.13 cbf_get_element_number, cbf_get_element_id
* 2.4.14 cbf_get_gain
* 2.4.15 cbf_set_gain
* 2.4.16 cbf_get_overload
* 2.4.17 cbf_set_overload
* 2.4.18 cbf_get_integration_time
* 2.4.19 cbf_set_integration_time
* 2.4.20 cbf_get_time
* 2.4.21 cbf_set_time
* 2.4.22 cbf_get_date
* 2.4.23 cbf_set_date
* 2.4.24 cbf_set_current_time
* 2.4.25 cbf_get_image_size, cbf_get_image_size_fs,
cbf_get_image_size_fs,
cbf_get_3d_image_size, cbf_get_3d_image_size_fs,
cbf_get_3d_image_size_sf
* 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
* 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
* 2.4.28 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
* 2.4.29 cbf_set_axis_setting
* 2.4.30 cbf_construct_goniometer
* 2.4.31 cbf_free_goniometer
* 2.4.32 cbf_get_rotation_axis
* 2.4.33 cbf_get_rotation_range
* 2.4.34 cbf_rotate_vector
* 2.4.35 cbf_get_reciprocal
* 2.4.36 cbf_construct_detector,
cbf_construct_reference_detector,
cbf_require_reference_detector
* 2.4.37 cbf_free_detector
* 2.4.38 cbf_construct_positioner,
cbf_construct_reference_positioner
* 2.4.39 cbf_free_positioner
* 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,
cbf_set_reference_beam_center,
cbf_set_reference_beam_center_fs,
cbf_set_reference_beam_center_sf
* 2.4.41 cbf_get_detector_distance
* 2.4.42 cbf_get_detector_normal
* 2.4.43 cbf_get_detector_axis_slow,
cbf_get_detector_axis_fast, cbf_get_detector_axes,
cbf_get_detector_axes_fs, cbf_get_detector_axes_sf,
cbf_get_detector_surface_axes
* 2.4.44 cbf_get_pixel_coordinates,
cbf_get_pixel_coordinates_fs, cbf_get_pixel_coordinates_sf
* 2.4.45 cbf_get_pixel_normal, cbf_get_pixel_normal_fs,
cbf_get_pixel_normal_sf
* 2.4.46 cbf_get_pixel_area, cbf_get_pixel_area_fs,
cbf_get_pixel_area_sf
* 2.4.47 cbf_get_pixel_size, cbf_get_pixel_size_fs,
cbf_get_pixel_size_sf
* 2.4.48 cbf_set_pixel_size, cbf_set_pixel_size_fs,
cbf_set_pixel_size_sf
* 2.4.49 cbf_get_inferred_pixel_size,
cbf_get_inferred_pixel_size_fs,
cbf_get_inferred_pixel_size_sf
* 2.4.50 cbf_get_unit_cell
* 2.4.51 cbf_set_unit_cell
* 2.4.52 cbf_get_reciprocal_cell
* 2.4.53 cbf_set_reciprocal_cell
* 2.4.54 cbf_compute_cell_volume
* 2.4.55 cbf_compute_reciprocal_cell
* 2.4.56 cbf_get_orientation_matrix,
cbf_set_orientation_matrix
* 2.4.57 cbf_get_bin_sizes, cbf_set_bin_sizes
* 2.4.58 cbf_get_axis_poise, cbf_get_goniometer_poise,
cbf_get_axis_reference_poise
* 2.4.59 cbf_airy_disk, cbf_airy_disk_volume
* 2.5 F90 function interfaces
* 2.5.1 FCB_ATOL_WCNT
* 2.5.2 FCB_CI_STRNCMPARR
* 2.5.3 FCB_EXIT_BINARY
* 2.5.4 FCB_NBLEN_ARRAY
* 2.5.5 FCB_NEXT_BINARY
* 2.5.6 FCB_OPEN_CIFIN
* 2.5.7 FCB_PACKED: FCB_DECOMPRESS_PACKED_I2,
FCB_DECOMPRESS_PACKED_I4, FCB_DECOMPRESS_PACKED_3D_I2,
FCB_DECOMPRESS_PACKED_3D_I4
* 2.5.8 FCB_READ_BITS
* 2.5.9 FCB_READ_BYTE
* 2.5.10 FCB_READ_IMAGE_I2, FCB_READ_IMAGE_I4,
FCB_READ_IMAGE_3D_I2, FCB_READ_IMAGE_3D_I4
* 2.5.11 FCB_READ_LINE
* 2.5.12 FCB_READ_XDS_I2
* 2.5.13 FCB_SKIP_WHITESPACE
* 2.6 HDF5 abstraction layer and convenience functions
* 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.9 cbf_H5Afree
* 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.20 cbf_H5Dfree
* 2.6.21 cbf_H5Fopen
* 2.6.22 cbf_H5Fclose
* 2.6.23 cbf_H5Gcreate
* 2.6.24 cbf_H5Gfind
* 2.6.25 cbf_H5Grequire
* 2.6.26 cbf_H5Gfree
* 2.6.27 cbf_H5Ivalid
* 2.6.28 cbf_H5Ocmp
* 2.6.29 cbf_H5Ofree
* 2.6.30 cbf_H5Screate
* 2.6.31 cbf_H5Sfree
* 2.6.32 cbf_H5Tcreate_string
* 2.6.33 cbf_H5Tfree
* 2.7 High-level NeXus-related functions
* 2.7.1 cbf_h5handle_get_file
* 2.7.2 cbf_h5handle_set_file
* 2.7.3 cbf_h5handle_get_entry
* 2.7.4 cbf_h5handle_set_entry
* 2.7.5 cbf_h5handle_require_entry
* 2.7.6 cbf_h5handle_require_entry_definition
* 2.7.7 cbf_h5handle_get_sample
* 2.7.8 cbf_h5handle_set_sample
* 2.7.9 cbf_h5handle_require_sample
* 2.7.10 cbf_h5handle_get_beam
* 2.7.11 cbf_h5handle_set_beam
* 2.7.12 cbf_h5handle_require_beam
* 2.7.13 cbf_h5handle_get_instrument
* 2.7.14 cbf_h5handle_set_instrument
* 2.7.15 cbf_h5handle_find_instrument
* 2.7.16 cbf_h5handle_require_instrument
* 2.7.17 cbf_h5handle_get_detector
* 2.7.18 cbf_h5handle_set_detector
* 2.7.19 cbf_h5handle_find_detector
* 2.7.20 cbf_h5handle_require_detector
* 2.7.21 cbf_h5handle_get_goniometer
* 2.7.22 cbf_h5handle_set_goniometer
* 2.7.23 cbf_h5handle_require_goniometer
* 2.7.24 cbf_h5handle_get_monochromator
* 2.7.25 cbf_h5handle_set_monochromator
* 2.7.26 cbf_h5handle_require_monochromator
* 2.7.27 cbf_h5handle_get_source
* 2.7.28 cbf_h5handle_set_source
* 2.7.29 cbf_h5handle_require_source
* 2.7.30 cbf_free_h5handle
* 2.7.31 cbf_create_h5handle3
* 2.7.32 cbf_write_cbf_h5file
* 2.7.33 cbf_write_cbf2nx
* 2.7.34 cbf_write_minicbf_h5file
* 2.7.35 cbf_write_nx2cbf
* 2.7.36 cbf_config_create
* 2.7.37 cbf_config_parse
* 2.7.38 cbf_config_free
* 2.7.39 cbf_config_strerror
* 3. File format
* 3.1 General description
* 3.2 Format of the binary sections
* 3.2.1 Format of imgCIF binary sections
* 3.2.2 Format of CBF binary sections
* 3.3 Compression schemes
* 3.3.1 Canonical-code compression
* 3.3.2 CCP4-style compression
* 3.3.3 Byte_offset compression
* 3.3.4 Nibble_offset compression
* 3.4 Access to CBFlib compressions from HDF5
* 4. Installation
* 5. Example programs
1. Introduction
CBFlib (Crystallographic Binary File library) is a library of ANSI-C
functions providing a simple mechanism for accessing Crystallographic
Binary Files (CBF files) and Image-supporting CIF (imgCIF) files. The
CBFlib API is loosely based on the CIFPARSE API for mmCIF files. Like
CIFPARSE, CBFlib does not perform any semantic integrity checks; rather it
simply provides functions to create, read, modify and write CBF binary
data files and imgCIF ASCII data files.
Starting with version 0.7.7, an envolving FCBlib (Fortran Crystallographic
Binary library) has been added. As of this release it includes code for
reading byte-offset and packed compression image files created by CBFlib.
2. Function descriptions
2.1 General description
Almost all of the CBFlib functions receive a value of type cbf_handle (a
CBF handle) as the first argument. Several of the high-level CBFlib
functions dealing with geometry receive a value of type cbf_goniometer (a
handle for a CBF goniometer object) or cbf_detector (a handle for a CBF
detector object).
All functions return an integer equal to 0 for success or an error code
for failure.
2.1.1 CBF handles
CBFlib permits a program to use multiple CBF objects simultaneously. To
identify the CBF object on which a function will operate, CBFlib uses a
value of type cbf_handle.
All functions in the library except cbf_make_handle expect a value of type
cbf_handle as the first argument.
The function cbf_make_handle creates and initializes a new CBF handle.
The function cbf_free_handle destroys a handle and frees all memory
associated with the corresponding CBF object.
2.1.2 CBF goniometer handles
To represent the goniometer used to orient a sample, CBFlib uses a value
of type cbf_goniometer.
A goniometer object is created and initialized from a CBF object using the
function cbf_construct_goniometer.
The function cbf_free_goniometer destroys a goniometer handle and frees
all memory associated with the corresponding object.
2.1.3 CBF detector handles
To represent a detector surface mounted on a positioning system, CBFlib
uses a value of type cbf_detector.
A goniometer object is created and initialized from a CBF object using one
of the functions cbf_construct_detector, cbf_construct_reference_detector
or cbf_require_reference_detector.
The function cbf_free_detector destroys a detector handle and frees all
memory associated with the corresponding object.
2.1.4 CBF positioner handles
To represent an arbitrary positioning system designated by the terminal
axis, CBFlib uses a value of type cbf_positioner.
A positioner object is created and initialized from a CBF object using one
of the functions cbf_construct_positioner,
cbf_construct_reference_positioner or cbf_require_reference_positioner.
The function cbf_free_positioner destroys a positioner handle and frees
all memory associated with the corresponding object.
2.1.5 Return values
All of the CBFlib functions return 0 on success and an error code on
failure. The error codes are:
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).
If more than one error has occurred, the error code is the logical OR of
the individual error codes.
2.2 Reading and writing files containing binary sections
2.2.1 Reading binary sections
The current version of CBFlib only decompresses a binary section from disk
when requested by the program.
When a file containing one or more binary sections is read, CBFlib saves
the file pointer and the position of the binary section within the file
and then jumps past the binary section. When the program attempts to
access the binary data, CBFlib sets the file position back to the start of
the binary section and then reads the data.
For this scheme to work:
1. The file must be a random-access file opened in binary mode (fopen ( ,"
rb")).
2. The program must not close the file. CBFlib will close the file using
fclose ( ) when it is no longer needed.
At present, this also means that a program cant read a file and then write
back to the same file. This restriction will be eliminated in a future
version.
When reading an imgCIF vs a CBF, the difference is detected automatically.
2.2.2 Writing binary sections
When a program passes CBFlib a binary value, the data is compressed to a
temporary file. If the CBF object is subsequently written to a file, the
data is simply copied from the temporary file to the output file.
The output file can be of any type. If the program indicates to CBFlib
that the file is a random-access and readable, CBFlib will conserve disk
space by closing the temporary file and using the output file as the
location at which the binary value is stored.
For this option to work:
1. The file must be a random-access file opened in binary update mode
(fopen ( , "w+b")).
2. The program must not close the file. CBFlib will close the file using
fclose ( ) when it is no longer needed.
If this option is not used:
1. CBFlib will continue using the temporary file.
2. CBFlib will not close the file. This is the responsibility of the main
program.
2.2.3 Summary of reading and writing files containing binary sections
1. Open disk files to read using the mode "rb".
2. If possible, open disk files to write using the mode "w+b" and tell
CBFlib that it can use the file as a buffer.
3. Do not close any files read by CBFlib or written by CBFlib with
buffering turned on.
4. Do not attempt to read from a file, then write to the same file.
2.2.4 Ordering of array indices
There are two major conventions in the ordering of array indices:
* fs: Fast to slow. The first array index (the one numbered "1") is the
one for which the values of that index change "fastest". That is, as
we move forward in memory, the value of this index changes more
rapidly than any other.
* sf: Slow to fast. The first array index (the one numbered "1") is the
one for which the values of that index change "slowest". That is as we
move forward in memory, the value of this index changes more slowly
than any other.
During the development of CBFlib, both conventions have been used. In
order to avoid confusion, the functions for which array indices are used
are available in three forms: a default version which may used either one
convention or the other, a form in which the name of the function has an
"_fs" suffix for the fast to slow convention and a form in which the name
of the function has a "_sf" suffix for the slow to fast convention.
Designers of applications are advised to use one of the two suffix
conventions. There is no burden on performance for using one convention or
the other. The differences are resolved at compile time by use of
preprocessor macros.
----------------------------------------------------------------------
----------------------------------------------------------------------
2.3 Low-level function prototypes
2.3.1 cbf_make_handle
PROTOTYPE
#include "cbf.h"
int cbf_make_handle (cbf_handle *handle);
DESCRIPTION
cbf_make_handle creates and initializes a new internal CBF object. All
other CBFlib functions operating on this object receive the CBF handle as
the first argument.
ARGUMENTS
handle Pointer to a CBF handle.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.2 cbf_free_handle
----------------------------------------------------------------------
2.3.2 cbf_free_handle
PROTOTYPE
#include "cbf.h"
int cbf_free_handle (cbf_handle handle);
DESCRIPTION
cbf_free_handle destroys the CBF object specified by the handle and frees
all associated memory.
ARGUMENTS
handle CBF handle to free.
RETURN VALUE
Returns an error code on failure or 0 for success.
SEE ALSO
2.3.1 cbf_make_handle
----------------------------------------------------------------------
2.3.3 cbf_read_file, cbf_read_widefile
PROTOTYPE
#include "cbf.h"
int cbf_read_file (cbf_handle handle, FILE *file, int flags);
int cbf_read_widefile (cbf_handle handle, FILE *file, int flags);
DESCRIPTION
cbf_read_file reads the CBF or CIF file file into the CBF object specified
by handle, using the CIF 1.0 convention of 80 character lines.
cbf_read_widefile reads the CBF or CIF file file into the CBF object
specified by handle, using the CIF 1.1 convention of 2048 character lines.
A warning is issued to stderr for ascii lines over the limit. No test is
performed on binary sections.
Validation is performed in three ways levels: during the lexical scan,
during the parse, and, if a dictionary was converted, against the value
types, value enumerations, categories and parent-child relationships
specified in the dictionary.
flags controls the interpretation of binary section headers, the parsing
of brackets constructs and the parsing of treble-quoted strings.
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.