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: @ (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