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
|
.\"
.\" Geometry man page
.\"
.\" (c) 2009-2011 Thomas White <taw@physics.org>
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"
.TH CRYSTFEL\_GEOMETRY 1
.SH NAME
CrystFEL detector geometry files
.SH OVERVIEW
The detector geometry is taken from a text file rather than hardcoded into the
program. Programs which care about the geometry (particularly indexamajig,
pattern_sim and powder_plot) take an argument "--geometry=<file>"
(or "-g <file>"), where <file> contains the geometry.
A flexible (and pedantic) representation of the detector has been developed to
avoid all possible sources of ambiguity. CrystFEL's representation of a
detector is broken down into one or more "panels", each of which has its own
camera length, geometry, resolution and so on. Each panel fits into the overall
image taken from the HDF5 file, defined by minimum and maximum coordinates in
the "fast scan" and "slow scan" directions. "Fast scan" refers to the direction
whose coordinate changes most quickly as the bytes in the HDF5 file are moved
through. The coordinates are specified inclusively, meaning that a minimum of 0
and a maximum of 9 results in a width of ten pixels. Counting begins from zero.
All pixels in the image must be assigned to a panel - gaps are not permitted.
In the current version, panels are assumed to be perpendicular to the incident
beam and to have their edges parallel. Within these limitations, any geometry
can be constructed.
The job of the geometry file is to establish a relationship between the array
of pixel values in the HDF5 file, defined in terms only of the "fast scan" and
"slow scan" directions, and the laboratory coordinate system defined as follows:
+z is the beam direction, and points along the beam (i.e. away from the source)
+y points towards the zenith (ceiling).
+x completes the right-handed coordinate system.
Naively speaking, this means that CrystFEL at the images from the "into the
beam" perspective, but please avoid thinking of things in this way. It's much
better to consider the precise way in which the coordinates are mapped.
The syntax for a simple geometry might include several entires of the following
form:
; Lines which should be ignored start with a semicolon.
; The name before the slash indicates which panel is referred to. You can use
; any name as long as it doesn't start with "bad" (see below).
; The range of pixels in the HDF5 file which correspond to a panel are given:
panel0/min_fs = 0
panel0/min_ss = 0
panel0/max_fs = 193
panel0/max_ss = 184
; The readout direction (x, y or 0). If more than three peaks are found in
; the same readout region, they are all discarded. This helps to avoid
; problems due to streaks appearing along the readout direction.
; If the badrow direction is '-', then the culling described above will not
; be performed for this panel.
panel0/badrow_direction = -
; The resolution (in pixels per metre) for this panel
panel0/res = 9090.91
; The characteristic peak separation in pixels. The peak detection will assume
; that genuine peaks are separated by at least this amount.
panel0/peak_sep = 6.0
; You need to specify the peak integration radius, which should be a little
; larger than the actual radii of the peaks in pixels
panel0/integr_radius = 2.0
; The camera length (in metres) for this panel
; You can also specify the HDF path to a scalar floating point value containing
; the camera length in millimetres.
panel0/clen = /LCLS/detectorPosition
; For this panel, the fast and slow scan directions correspond to the given
; directions in the lab coordinate system described above, measured in pixels.
panel0/fs = +y
panel0/ss = -x
; The corner of this panel, defined as the first point in the panel to appear in
; the HDF5 file, is now given a position in the lab coordinate system.
; Note that "first point in the panel" is a conceptual simplification. We refer
; to that corner, and to the very corner of the pixel - NOT, for example, to the
; centre of the first pixel to appear.
panel0/corner_x = 429.39
panel0/corner_y = -17.30
; You can suppress indexing for this panel if required, by setting "no_index" to
; "true" or "1".
panel0/no_index = 0
; You can also specify bad regions. Peaks with centroid locations within such
; a region will not be integrated nor indexed. Bad regions are specified in
; pixel units, but in the lab coordinate system (i.e. "y" points at the ceiling,
; "z" is the beam direction and "x" completes the right-handed system).
badregionA/min_x = -20.0
badregionA/max_x = +20.0
badregionA/min_y = -100.0
badregionA/max_y = +100.0
; If you have a bad pixel mask, you can include it in the HDF5 file as an
; unsigned 16-bit integer array of the same size as the data. You need to
; give its path within each HDF5 file, and two bitmasks. The pixel is
; considered good if all of the bits which are set in "mask_good" are set, AND
; if none of the bits which are set in "mask_bad" are set.
mask = /processing/hitfinder/masks
mask_good = 0x27
mask_bad = 0x00
; Any of the per-panel values can be given without a panel prefix, for example:
peak_sep = 6.0
; in which case the value will be used for all *subsequent* panels.
See the "examples" folder for some examples (look at the ones ending in .geom).
|
