PILATUS CBF

Image files written in the CBF format by a PILATUS detector are by default "minimal" CBF files and contain a PILATUS CBF header. Documentation and specification of this format is available for download with the following link:

Pilatus_CBF_Header_Specification.pdf (220.5 KB)

A reference implementation written in Python for parsing of PILATUS CBF headers is available for download with the following link:

pilatus_header.py (7.2 KB)

Optionally it is possible to write PILATUS images as full CBF files using a template system developed in collaboration with Graeme Winter from Diamond Light Source. Documentation is provided in the file "cbf_template_HOWTO.txt" which comes with the detector software camserver and is also available here:

cbf_template_HOWTO.txt (10.2 KB)

For any further questions please feel free to contact support@dectris.com.

Properties of a PILATUS CBF header

PILATUS header:
_array_data.header_convention “PILATUS_1.2”
_array_data.header_contents;
header is here between semi-colons;

Elements of header:
- Hash: #
- Keyword Value(s)
- Unit(s)
- Space delimitation and space equivalent characters ‘#=:,()’ for better readability

Data values and potentially their units appear at specified positions with respect to space delimitation.
These positions are specified in the PILATUS CBF header specification.
The character positions of keywords and values within a line of the header are not part of the specification and might change in future versions of the Pilatus cbf header.

PILATUS CBF header: example

The header line

# Beam_xy (243.12, 309.12) pixels

is equivalent to all following lines:

Keyword, values, and unit always appear at the same position relative to delimitation by space or space equivalent characters ‘#=:,()’

Reference implementation

A reference implementation for parsing of PILATUS CBF headers written in Python is available:

pilatus_header.py (7.2 KB)

Full CBF files: template system

camserver supports writing of full CBF files via a “template system”.
System developed in collaboration with Graeme
Winter from Diamond. A template file is specified in camserver:

Template file has two components:
- - A “preamble” which contains:
    - Descriptive information
    - Substitution commands which match internal variables of camserver with keys in the CBF header to be substituted with dynamic values during data acquisition.
  - A template of the CBF header with all static data items and keys for dynamic data values to be substituted by camserver according to the substitution commands. An example is given below:

Parsing of parameter values

Data values and potentially their units appear at specified positions with respect to space delimitation.

These positions are specified in the PILATUS CBF header specification, available here. The following table is an excerpt to provide examples:

Keyword	Value position(s)	Unit positions	Dimension	Type
Wavelength	1	2	Å	float
Energy_range	1, 2	3	eV	integer
Detector_distance	1	2	m	float
Detector_Voffset	1	2	m	float
Beam_xy	1, 2	3	pixels	float

A header line as it appears in the header:
Conversion of all space equivalent characters to space:
Parsing of parameter values according to position with respect to space delimitation:
```
0        1       2       3         Position
  Beam_xy  243.12  309.12  pixels
```