			cbf_template_HOWTO.txt

How to Use a Template to Write Full CBF Headers Under camserver.

This system was developed in collaboration with Diamond Light Source.

Below, starting with the line "###CBF: VERSION 1.1" is an example of a CBF
header template.  It has been tested for validity against CBFlib_0.7.7.

The template consists of a "preamble" containing descriptive information and
"substitution" commands.  The preamble is ended by the "--- End of preamble" 
statement.  The preamble is followed by the body of the CBF header which
is reproduced verbatim in the image file, except for the requested variable
substitutions.  The "--- End of preamble" statement is optional, but is
required if any immediately following comments are to be reproduced.

The substitution commands each reference an internal program variable in the
DECTRIS control software and define a corresponding "key" which is to be
found in the body of the header and substituted by the running value of the
variable while data-taking proceeds.  Substitution commands take the form:

@ <DECTRIS internal variable>   <key>   <optional initial value>

(1) The character in column 0 must be '@'
(2) The DECTRIS internal variables are listed below.  Variables to be
    substituted must exist (be spelled correctly), are not case-sensitive
    and may be listed in any order.
(3) The keys may be any unique text.  We find forms like "_expt_" to be
    easy to find visually in the text.  Keys should be preceeded and
    followed by blank spaces, unless they are at the beginning or
    end of a line, where the respective leading or trailing blank can be
    omitted.
(4) Many of the variables can have an initial value specified in the line
    of the substitution command.  These are listed below.  Alternatively,
    variables may be initialized using the MXsettings command to camserver.
(5) Each key must be found one or more times in the text.  The spelling
    and orthography of the key in the substitution command must match
    the key in the body of the text.
(6) The location of the template file must be declared to camserver using,
    e.g.: "MXsettings CBF_template_file /full/path/to/file/phase_1.2.cbf"
    where the full path to the template is given.  The absence of this
    declaration indicates that the template facility is not being used.
    The location (path) of the template is arbitrary.
(7) The template can be updated dynamically between exposure series.  The
    template is reprocessed at the start of each expsoure series so that
    initial values can be set.
(8) The content of the template is completely arbitrary and therefore
    not specific for CBF.
(9) Currently the CBF template, including the preamble, must be less than
    8 kB in size; there can be up to 30 substitution points.

For more information on CBF, see:
http://arcib.dowling.edu/software/CBFlib/

DECTRIS internal variables that can be given initial values in the
substitution command line:

@ Energy_range
@ Detector_distance
@ Detector_Voffset
@ Beam_xy
@ Beam_x
@ Beam_y
@ Flux
@ Filter_transmission
@ Start_angle
@ Angle_increment
@ Detector_2theta
@ Polarization
@ Alpha
@ Kappa
@ Phi
@ Phi_increment
@ Chi
@ Chi_increment
@ Oscillation_axis
@ N_oscillations
@ Start_position
@ Position_increment
@ Shutter_time

DECTRIS internal variables that do not take initial values in the
substitution command line:

@ Wavelength
@ Timestamp
@ Exposure_period
@ Exposure_time
@ Count_cutoff
@ Compression_type
@ X_dimension
@ Y_dimension

Note that the compression type can be CBF_BYTE_OFFSET or CBF_NONE depending
on the image data.  For crystallography, the latter case almost never
happens, but SAXS data sometimes do not compress.  The X_dimension and
Y_dimension variables were added for convenience in writing more portable
templates.  The "Shutter_time" variable can be used in cases where the
shutter open time differs from the requested Exposure_time.

All text up to and including the "--- End of preamble" statement is elided
in the final header text.  If the "--- End of preamble" statement is not
used, then all text up to the first recognized CBF declaration is elided.

All variables that have been defined will also appear as comments near the
top of the CBF header, where they will show up on the first page of "more".
The header text defined by the template will be positioned below these
comments.  Below that will be the "mini-header" needed by XDS, followed
by the image data.

Disclaimer:  Although every effort has been made to make the CBF header
template system reliable, robust and easy to use, it will easily create
image files that cannot be opened by any application.  Please do **not**
contact us if this happens to you.



Eric.Eikenberry@dectris.com
Graeme.Winter@diamond.ac.uk 
6 May 2010

============================================================================

###CBF: VERSION 1.1
# Template for Diamond MX beamlines phase 1 - replacing what we currently
# have in ADSC, Rayonix and DECTRIS image headers with a standard syntax
# and description.
# 
# DECTRIS translation table follows...
# 
@ Exposure_time     _expt_
@ Exposure_period   _expp_
@ Start_angle       _omega_         3.987
@ Angle_increment   _d_omega_       0.123
@ Timestamp         _timestamp_
@ Count_cutoff      _cutoff_
@ Compression_type  _compress_
@ X_dimension       _wide_
@ Y_dimension       _high_
# 
# These items will be pre-populated in the template so need not be included:
# 
# Wavelength        
# Detector_distance 
# Beam_xy
# Alpha
# Kappa
# Phi
# Chi
# Oscillation_axis
# Pixel_size
# Detector
--- End of preamble
# This and all subsequent lines will appear in the header

_diffrn.id DLS_I03
_diffrn.crystal_id XTAL0001

# the following items will be fixed for the beamline

loop_
_diffrn_source.diffrn_id
_diffrn_source.source
_diffrn_source.type
 DLS_I03 synchrotron 'Diamond Light Source Beamline I03'

loop_
_diffrn_radiation.diffrn_id
_diffrn_radiation.wavelength_id
_diffrn_radiation.monochromator
_diffrn_radiation.polarizn_source_ratio
_diffrn_radiation.polarizn_source_norm
_diffrn_radiation.div_x_source
_diffrn_radiation.div_y_source
_diffrn_radiation.div_x_y_source
 DLS_I03 WAVELENGTH1 'Si 111' 0.8 0.0 0.08 0.01 0.00

# category DIFFRN_DETECTOR
loop_
_diffrn_detector.diffrn_id
_diffrn_detector.id
_diffrn_detector.type
_diffrn_detector.number_of_axes
 DLS_I03 ADSC_I03 'ADSC Quantum 315' 3

loop_
_diffrn_detector_axis.detector_id
_diffrn_detector_axis.axis_id
 ADSC_I03 DETECTOR_X
 ADSC_I03 DETECTOR_Y
 ADSC_I03 DETECTOR_Z

loop_
_diffrn_detector_element.id
_diffrn_detector_element.detector_id
 ELEMENT1 ADSC_I03

loop_
_diffrn_data_frame.id
_diffrn_data_frame.detector_element_id
_diffrn_data_frame.array_id
_diffrn_data_frame.binary_id
 FRAME1 ELEMENT1 ARRAY1 1

loop_
_diffrn_scan.id
_diffrn_scan.frame_id_start
_diffrn_scan.frame_id_end
_diffrn_scan.frames
 SCAN1 FRAME1 FRAME1 1

# at the moment we have only a single axis system in place - this will change 
# to a kappa at some point for I04 -> number_of_axes = 3
# GONIOMETER GONIOMETER_PHI
# GONIOMETER GONIOMETER_KAPPA

loop_
_diffrn_measurement.diffrn_id
_diffrn_measurement.id
_diffrn_measurement.number_of_axes
_diffrn_measurement.method
 DLS_I03 GONIOMETER 1 rotation

loop_
_diffrn_measurement_axis.measurement_id
_diffrn_measurement_axis.axis_id
 GONIOMETER GONIOMETER_OMEGA

# these items will be written by GDA on a scan-by-scan basis

loop_
_diffrn_radiation_wavelength.id
_diffrn_radiation_wavelength.wavelength
_diffrn_radiation_wavelength.wt
 WAVELENGTH1 0.97930 1.0

# these values should probably be updated from the results of postrefinement

loop_
_diffrn_scan_axis.scan_id
_diffrn_scan_axis.axis_id
_diffrn_scan_axis.angle_start
_diffrn_scan_axis.angle_range
_diffrn_scan_axis.angle_increment
_diffrn_scan_axis.displacement_start
_diffrn_scan_axis.displacement_range
_diffrn_scan_axis.displacement_increment
 SCAN1 GONIOMETER_OMEGA _omega_ 1.0 _d_omega_ 0.0 0.0 0.0
 SCAN1 DETECTOR_Z 0.0 0.0 0.0 -240.0 0.0 0.0
 SCAN1 DETECTOR_Y 0.0 0.0 0.0 0.6 0.0 0.0
 SCAN1 DETECTOR_X 0.0 0.0 0.0 -0.5 0.0 0.0

loop_
_diffrn_scan_frame.frame_id
_diffrn_scan_frame.frame_number
_diffrn_scan_frame.integration_time
_diffrn_scan_frame.exposure_time
_diffrn_scan_frame.scan_id
_diffrn_scan_frame.date
 FRAME1 1 _expt_ _expp_ SCAN1 _timestamp_

loop_
_diffrn_scan_frame_axis.frame_id
_diffrn_scan_frame_axis.axis_id
_diffrn_scan_frame_axis.angle
_diffrn_scan_frame_axis.displacement
 FRAME1 GONIOMETER_OMEGA 12.0 0.0
 FRAME1 DETECTOR_Z 0.0 -240.0
 FRAME1 DETECTOR_Y 0.0 0.6
 FRAME1 DETECTOR_X 0.0 -0.5

# this could also contain postrefined results

loop_
_axis.id
_axis.type
_axis.equipment
_axis.depends_on
_axis.vector[1] _axis.vector[2] _axis.vector[3]
_axis.offset[1] _axis.offset[2] _axis.offset[3]
 GONIOMETER_OMEGA rotation goniometer . 1 0 0 . . .
 SOURCE           general source . 0 0 1 . . .
 GRAVITY          general gravity . 0 -1 0 . . .
 DETECTOR_Z       translation detector . 0 0 1 0 0 0
 DETECTOR_Y       translation detector DETECTOR_Z 0 1 0 0 0 0
 DETECTOR_X       translation detector DETECTOR_Y 1 0 0 0 0 0
 ELEMENT_X        translation detector DETECTOR_X 1 0 0 157.2 157.2 0
 ELEMENT_Y        translation detector ELEMENT_X 0 1 0 0 0 0

loop_
_array_structure_list.array_id
_array_structure_list.index
_array_structure_list.dimension
_array_structure_list.precedence
_array_structure_list.direction
_array_structure_list.axis_set_id
 ARRAY1 1 _wide_ 1 increasing ELEMENT_X
 ARRAY1 2 _high_ 2 increasing ELEMENT_Y

loop_
_array_structure_list_axis.axis_set_id
_array_structure_list_axis.axis_id
_array_structure_list_axis.displacement
_array_structure_list_axis.displacement_increment
 ELEMENT_X ELEMENT_X 0.0512 0.1024
 ELEMENT_Y ELEMENT_Y 0.0512 0.1024

loop_
_array_element_size.array_id
_array_element_size.index
_array_element_size.size
 ARRAY1 1 102.4e-6
 ARRAY1 2 102.4e-6

loop_
_array_intensities.array_id
_array_intensities.binary_id
_array_intensities.linearity
_array_intensities.gain
_array_intensities.gain_esd
_array_intensities.overload
_array_intensities.undefined_value
 ARRAY1 1 linear 0.5 0.2 _cutoff_ 0

loop_
_array_structure.id
_array_structure.encoding_type
_array_structure.compression_type
_array_structure.byte_order
 ARRAY1 "signed 32-bit integer" _compress_ little_endian
