forked from dials/cbflib
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
executable file
·436 lines (422 loc) · 18.1 KB
/
README.html
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
<html>
<head>
<title>
CBFlib
</title>
</head>
<body background="html_graphics/cbflibbackground.jpg">
<table border=2>
<tr>
<td><a href="http://www.iucr.org/iucr-top/welcome.html">
<img alt="[IUCr Home Page]" src="html_graphics/iucrhome.jpg"></a>
</td>
<td><a href="http://www.iucr.org/iucr-top/cif/home.html">
<img alt="[CIF Home Page]" src="html_graphics/cifhome.jpg"></a>
</td>
<td><A HREF="doc/cbf_definition_rev.html"><IMG SRC="html_graphics/CBFbutton.jpg"
ALT="[CBF/imgCIF]"></A>
</td>
<td><A HREF="doc/CBFlib.html"><IMG SRC="html_graphics/cbflibbutton.jpg"
ALT="[CBFlib]"></A>
<td><a href="http://sourceforge.net/projects/cbflib"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=167912&type=13" width="120" height="30" alt="Get CBFlib at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</td>
</tr>
</table>
<hr>
<CENTER>
| <a href="http://www.iucr.org/iucr-top/welcome.html">IUCr Home Page</a>
| <a href="http://www.iucr.org/iucr-top/cif/home.html">CIF Home Page</a>
| <A HREF="doc/cbf_definition_rev.html">CBF/imgCIF</a>
| CBFlib
|<br />
| <A HREF = "doc/CBFlib_NOTICES.html">NOTICE</A>
| <a href=doc/gpl.txt>doc/GPL</a>
| <a href=doc/lgpl.txt>doc/LGPL</a>
| <a href="doc/cif_img_1.7.11.html">imgCIF dictionary</a>
| <a href = "http://sf.net/projects/cbflib">SourceForge CBFlib site</a>
|<br />
| <a href="http://arcib.dowling.edu/donation.shtml">Click Here to Make a Donation</a>
|<P>
<IMG SRC="html_graphics/cbflibbig.jpg" ALT="CBFlib">
</CENTER>
<font color="#0808A0">
<H2 ALIGN=CENTER>README</H2>
<H3 ALIGN=CENTER>
Information for CBFlib 0.9.6 release of 4 December 2018<br />
</H3>
</font><font color="#000000">
<CENTER>
by<BR>
Paul J. Ellis<BR>
Stanford Synchrotron Radiation Laboratory<BR>
<P>
and<BR>
Herbert J. Bernstein<BR>
Bernstein + Sons<br />
<script language="javascript" type="text/javascript">
<!--
var name = "yayahjb@";
var domain = "gmail";
var domext = ".com";
document.write ("(<a href=\"mailto:" + name + domain + domext + "\">" + name + domain + domext+"</a>)");
// -->
</script>
<noscript>
yaya <b>at</b> bernstein-plus-sons <b>dot</b> com
</noscript>
<p>
© Copyright 2006 -- 2018 Herbert J. Bernstein
<P>
<hr>
<b>YOU MAY REDISTRIBUTE THE CBFLIB PACKAGE UNDER THE TERMS OF THE <a href=doc/gpl.txt>GPL</a>.
<P>
ALTERNATIVELY YOU MAY REDISTRIBUTE THE CBFLIB API UNDER THE TERMS
OF THE <a href=doc/lgpl.txt>LGPL<a/>.</b>
<p>All functions in the src, include and examples directories are included in the term
"API"
unless explicitly placed under a diferent license in the header comments of that
particular source code.
</CENTER>
<HR>
<H3 ALIGN=CENTER>
Before using this software, please read the <BR>
<A HREF = "doc/CBFlib_NOTICES.html"> <IMG SRC="html_graphics/noticeButton.jpg"
ALT="NOTICE"></A><BR>
for important disclaimers and the IUCr Policy
on the Use of the Crystallographic Information File (CIF) and other important
information.
</h3>
<P>
Work on imgCIF and CBFlib supported in part by the 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 Crystallography (IUCr) and Dectris, Ltd. The content is solely the responsibility of
the authors and does not necessarily represent the official views of
DOE, NSF, NIH, NIGMS, NCRR, IUCr or Dectris.
Recent work on integration among CBF, HDF5 and NeXus supported in part
by Pandata ODI (EU 7th Framework Programme)
<P>
<HR>
<p>
CBFlib 0.9.6 is the full release supporting the integration of CBF and
NeXus, including support for the NeXus NXpdb embedding of CIF files
in NeXus files. <b>*** 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 ***</b>.
The primary development source is at <a href="https://github.com/yayahjb/cbflib">https://github.com/yayahjb/cbflib</a>.
The branch pdb_in_nexus, which was used for much of this development has been
merged, is now deprecated, and will be removed in the near future.
<p>
CBFlib 0.9.5 is the full release resulting from the interim effort on
0.9.4, reflecting significant and unfortunately somewhat disruptive
changes resulting from changes to the agreed CBF-NeXus mapping.
Axis data on the NeXus side is now in a new tranformations:NXtransformations
group. Polarization is now handled with Stokes vectors with optional esds.
Further changes are expected for full support of mapping multi-module
detectors such as FELs where module positioning may be refined, but
this mapping should work for unitary detectors.
<p>
CBFlib 0.9.4.1 has further refactoring by Jonathan Sloan, and partial documentation
with an updated dictionary. This is an interim release, expected to be become a full
release with 0.9.4.2.
<p>
CBFlib 0.9.4 provides a reasonably functional mapping of CBF files to
NeXus files that carries all essential information for monchromatic
MX processing in the NeXus file, and extends the cmake build capabilities
and refactors a lot of the mapping code. Our thanks to Jonathan Sloan for this effort.
<p>
CBFlib 0.9.3.3 added examples of the description of a multi-module FEL detector,
thanks to Aaron Brewster of LCLS. New convenience accessor functions were
been added to expose the details of axes field by field. Corrections were
been made to the handling of _axis.rotation and _axis.rotation_axis.
This was an interim release. The API version and dictionary were to be updated
on the next release.
<p>
CBFlib 0.9.3.2 has a revised API version, and, otherwise, the same code as CBFlib
0.9.3.1, but with further update to the imgCIF dictionary to avoid issues with
the PDB validation software. Because of the revised API version, many of the
data files changed to update the version in the file comments.
<p>
CBFlib 0.9.3.1 has the same code as CBFlib 0.9.3, but with an update to
the imgCIF dictionary reflecting a major technical cleanup by John Westbrook.
An explanation of the choices of regex versions has been added to the README.
<p>
CBFlib 0.9.3 is the formal base release integrating CBF, HDF5 and NeXus.
It also includes changes to support the description of FEL detectors.
More details on the integration and the new dctionary including both
NeXus information and the new FEL detector tags, _axis.rotation_axis
and _axis.rotation are avialable at
<a href="https://sites.google.com/site/nexuscbf/">https://sites.google.com/site/nexuscbf/</a>.
The commulative changes in releases 0.9.1, 0.9.2, and 0.9.3 since CBFlib 0.9.0
were:
<ul>
<li>Temporary removal of default PyCifRW support for compliance with
Fedora license requirements.
<li>Addition of a new tiff2cbf example program.
<li>Update pycbf python wraapper for CBFlib.
<li>Padding options added to adscimg2cbf by C. Nielsen.
<li>System and gnu versions of getopt replaced by cbf_getopt.
<li>Code to handle CIF2 bracketed constructs and quoted strings added.
<li>System to log errors and warnings added.
<li>Java wrapper by Peter Chang added.
<li>Dectris template code by E. Eikenberry added.
<li>Addition of nibble offset compression trial code.
<li>Addition of support for full axis poise calculations.
<li>Incorporation of hdf5-1.8.11 and the first phase of code
in CBFlib to support NeXus, including mincbf2nexus and
cbf2nexus by Jonathan Sloan of DLS
<li>Cleanup and fixes to Makefiles for more reliable builds, and
a partial preliminary CMakeLists.txt
<li>Fixes to support newer DECTRIS minicbf headers in convertminicbf
<li>The first phase of code to support
</ul>
<p>
The changes for FEL support involve major changes to the positioner logic
used in computing goniometer and detector positions. This code should
be used with caution.
<p>
The changes for the CBF-HDF5 mappings are extensive and should be used with
caution.
<p>
Please report all difficulties you may encounter with this release to
<script language="javascript" type="text/javascript">
<!--
var name = "yayahjb@";
var domain = "gmail";
var domext = ".com";
document.write ("(<a href=\"mailto:" + name + domain + domext + "\">" + name + domain + domext+"</a>)");
// -->
</script>
<noscript>
yayahjb <b>at</b> gmail <b>dot</b> com
</noscript>
<P>
Our thanks to Jonathan Sloan, Tobias Richter and Graeme Winter of
Diamond Light Source and Robert M. Sweet of Brookhaven National
Laboratory for their major contributions to this release. Without
their efforts it would not have happened.
<p>
CBFlib 0.9.2.5 in October 2012 through CBFlib 0.9.2.12 in June 2013 were an accumulation
of minor revisions to the CBFlib 0.9.2.4 release, plus the testbed
for HDF5/NeXus support and preliminary Eiger support, now released in CBFlib 0.9.3.
<p>
CBFlib 0.9.2.4 was a minor revision to the CBFlib 0.9.2.3 release
to support tiff2cbf for short in tiffs and to fix problems with
64 bit long integers uncovered on Mac OSX 10.6 and 10.7 for 64
compilers.
<p>
CBFlib 0.9.2.3 was a minor revision to the CBFlib 0.9.2.2 release
to allow use of NO_CBF_REGEX to suppress use of regex for convenience
in doing visual studio builds for cctbx as requested by Ralf
Ralf Grosse-Kunstleve for cctbx builds.
<p>
CBFlib 0.9.2.2 was a minor revision to the CBFlib 0.9.2.1 release
in July 2011 to update doc/cif_img.dic to the 1.6.4 revision.
<p>
CBFlib 0.9.2.1 was a minor revision to the CBFlib 0.9.2 release
in June 2011 to upgrade the setup script for the pycbf Python
bindings to simplify using pycbf outside the context of
the CBFlib pycbf directory.
<p>
CBFlib 0.9.2 was the recommended release of CBFlib of February 2011.
<P>
CBFlib 0.9.1 included a correction to CBFlib 0.9.0 to make axis
the cbf_simple routines apply axis rotations correctly for detectors and to
pick up corrections for byte offet compression incorporated into the upcoming
CBFlib 0.9.1 release. The earlier version had failed to apply the rotations
to the accumulated displacements.
Our thanks to Joerg Kaercher of Bruker-AXS for identifying the rotation
problem.
<p>
CBFlib 0.9.0 was a partial pre-release of CBFlib version 0.8 needed to support
changes in RasMol. This release was incomplete and used were advided to use it with caution,
but it has proven to be a reliable, stable release for 2 years.
There have been significant changes in the input/output logic and in validation.
For a ChangeLog consult the SVN of the CBFlib project on sourceforge.
<P>
CBFLIB 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. Starting with this release, CBFLIB performs validation
checks on reading of a CBF. If a dictionary is provided, values will
be validated against dictionary ranges and enumerations. Tags
missing under parent-child relationships or category key requirements
will be reported. CBFlib provides functions to create, read, modify
and write CBF binary data files and imgCIF ASCII data files.
<P>
<H3>Installation</H3>
<P>
CBFLIB should be built on a disk with at least 500 megabytes of free
space, for a full installation with complete tests. <b>Read the
instructions below carefully, if space is a problem.</b>
<p>
You may download clone the git repository with <br />
git clone https://github.com/yayahjb/cbflib.git<br />
or a gizpped tarball of this release is available on sourceforge at
<p>
<a
href="http://downloads.sf.net/cbflib/CBFlib-0.9.6.tar.gz">http://downloads.sf.net/cbflib/CBFlib-0.9.6.tar.gz</a>
<P>
In addition,
<A
href="http://downloads.sf.net/cbflib/CBFlib_0.9.6_Data_Files_Input.tar.gz">http://downloads.sf.net/cbflib/CBFlib_0.9.6_Data_Files_Input.tar.gz</a>
(13 MB) is a "gzipped" tar of the input data files needed to test the API,
<A
href="http://downloads.sf.net/cbflib/CBFlib_0.9.6_Data_Files_Output.tar.gz">http://downloads.sf.net/cbflib/CBFlib_0.9.6_Data_Files_Output.tar.gz</a>
(34 MB) is a "gzipped" tar of the output data files needed to test the API, and, if space is at a premium,
<A
href="http://downloads.sf.net/cbflib/CBFlib_0.9.6_Data_Files_Output_Sigs_Only.tar.gz">http://downloads.sf.net/cbflib/CBFlib_0.9.6_Data_Files_Output_Sigs_Only.tar.gz</a>
(1KB) is a "gzipped" tar of only the MD5 signatures of the output data files needed to test the API.
Place the CBFlib_0.9.6.tar.gz file in the directory
that is intended to contain up to 4 new directories, named
CBFlib_0.9.6 (the "top-level" directory),
CBFlib_0.9.6_Data_Files_Input and either CBFlib_0.9.6_Data_Files_Output or
CBFlib_0.9.6_Data_Files_Output_Sigs_Only.
If you have wget on your machine, you only need to download the source tarball.
If you do not have wget,
you will need to download all the tarballs into the same directory
<p>
Uncompress CBFlib_0.9.6.tar.gz with gunzip and unpack it with tar:
<p>
<PRE>
gunzip CBFlib_0.9.6.tar.gz
tar xvf CBFLIB_0.9.6.tar
</PRE>
<p>
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,
and several files related to NeXus and FEL testing.
All these files will be
dowloaded and extracted by the Makefile from CBFlib_0.9.6_Data_Files_Input. Do
not download copies into the top level directory.
<P>
After unpacking the archives, the top-level directory should contain
a makefile and a cmake file.:
<p>
<TABLE ALIGN=CENTER>
<tr><td> Makefile</td><td> Makefile for Linux</td></tr>
<tr><td> CMakeLists.txt</td><td> Top level data file for cmake
builds</td></tr>
</TABLE>
and several alternate makefiles for other systems
<p>
and the subdirectories:
<p>
<TABLE ALIGN=CENTER>
<TR><TD> doc/<TD> Documentation
<TR><TD> src/<TD> CBFLIB source files
<TR><TD> include/<TD> CBFLIB header files
<TR><TD> <TD>
<TR><TD> external_packages/<TD> For additional support kits
<TR><TD> bin/<TD> Executable example programs
<TR><TD> examples/<TD> Example program source files
<TR><TD> html_images/<TD> JPEG images used in rendering the HTML files
<TR><TD> lib/<TD> Compiled CBFLIB (libcbf.a) and FCBLIB (libfcb.a) libraries
<TR><TD> m4/<TD> CBFLIB m4 macro files (used to build .f90 files)
<TR><TD> mswin/<TD> An MS Windows CodeWarrior project file
<TR><TD> pycbf/<TD> Jon Wright's Python bindings
<TR><TD> ply-3.2/<TD> A support kit needed for dREL code
<TR><TD> drel-ply/<TD> A support kit needed for dREL code
<TR><TD> dREL-ply-0.5/<TD> A support kit needed for dREL code
</TABLE>
<p>
<p>
All the makefiles are created from
m4/Makefile.m4. Edit the closest approximation to your system,
and then copy that variant to Makefile.
<p>
In building this release there is an enviroment variable you may need to set if
you are building on an older machine with a broken dlfnc that cannot support the
HDF5 filter plugin mechanism:
<p>
HDF5REGISTER
<p>
which should be set to the string "--register manual" to disable the automatic
plugin search.
<p>
For instructions on compiling and testing the library, go to
the top-level directory and type:
<p>
<PRE>
make
</PRE>
<p>
Once you have a properly configure Makefile, compile and test the package
with
<p>
<PRE>
make tests
</PRE>
<p>
or, if space is at a premium, with
<PRE>
make tests_sigs_only
</PRE>
<h3>regex</h3>
CBFlib makes can optionally use a system regular expression library
to assist in validation of CIFS. The feature is controlled by two compile-time
defines. The possible choices are
<p>
<ul>
<li>Not to use regex. If CBF_NO_REGEX is defined, no regex will be used.
<li>To used the tradition unix regex. If CBF_REGEXLIB_REGEX is
defined, regex.h is used.
<li>To use the newer and more popular POSIX pcre regex. If neither
CBF_NO_REGEX nor CBF_REGEXLIB_REGEX is defined, pcreposix.h
is used.
</ul>
<p>
<h3>Cmake</h3>
A partial preliminary CMakeLists.txt has been included in this kit. It is not yet complete, but
on machines for which the Makefiles are not appropriate, it is worth a try. To use in,
create a directory named CBFlib-0.9.6-build on the same level as CBFlib-0.9.6, and in
the new,
empty build directory, try
<p>
<div>
<pre>
cmake ../CBFlib-0.9.6
make all
make test
</pre>
</div>
<p>
Work on improving cmake support will continue, and comments, corrections and suggestions
would be appreciated.
<p>
Depending on your system, some tests may fail mysteriously under cmake. The most likely
cause is a failure to link example programs to the HDF5 shared library or other shared
libraries when tests are run prior to those libraries having been installed in
locations known to your system's loader. This is handled automatically in the Makefiles,
but we do not yet have a reliable way to do so for cmake ctest tests.
You may need to set various system-dependent environment variables such as
DYLD_LIBRARY_PATH, LD_LIBRARY_PATH or PATH. The bash script in the kit cbflib.ini should be sourced
before testing.
<P>
Please refer to the manual <a HREF="doc/CBFlib.html">doc/CBFlib.html</a>
for more detailed information.<HR>
<HR>
Updated 4 December 2018.
<script language="javascript" type="text/javascript">
<!--
var name = "yayahjb@";
var domain = "gmail";
var domext = ".com";
document.write ("(<a href=\"mailto:" + name + domain + domext + "\">" + name + domain + domext+"</a>)");
// -->
</script>
<noscript>
yayahjb <b>at</b> gmail <b>dot</b> com
</noscript>
</font>
</BODY>
</HTML>