diff options
Diffstat (limited to 'doc/man/crystfel_geometry.5')
| -rw-r--r-- | doc/man/crystfel_geometry.5 | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/doc/man/crystfel_geometry.5 b/doc/man/crystfel_geometry.5 new file mode 100644 index 00000000..4b3b7aee --- /dev/null +++ b/doc/man/crystfel_geometry.5 @@ -0,0 +1,169 @@ +.\" +.\" Geometry man page +.\" +.\" Copyright © 2012 Thomas White <taw@physics.org> +.\" +.\" Part of CrystFEL - crystallography with a FEL +.\" + +.TH CRYSTFEL\_GEOMETRY 5 + +.SH CRYSTFEL DETECTOR GEOMETRY FILES + +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) +.br ++y points towards the zenith (ceiling). +.br ++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 +.br +; any name as long as it doesn't start with "bad" (see below). +.br +; The range of pixels in the HDF5 file which correspond to a panel are given: +.br +panel0/min_fs = 0 +.br +panel0/min_ss = 0 +.br +panel0/max_fs = 193 +.br +panel0/max_ss = 184 + +; The readout direction (x, y or 0). If more than three peaks are found in +.br +; the same readout region, they are all discarded. This helps to avoid +.br +; problems due to streaks appearing along the readout direction. +.br +; If the badrow direction is '-', then the culling described above will not +.br +; be performed for this panel. +.br +panel0/badrow_direction = - + +; The resolution (in pixels per metre) for this panel +.br +panel0/res = 9090.91 + +; The characteristic peak separation in pixels. The peak detection will assume +.br +; that genuine peaks are separated by at least this amount. +.br +panel0/peak_sep = 6.0 + +; You need to specify the peak integration radius, which should be a little +.br +; larger than the actual radii of the peaks in pixels +.br +panel0/integr_radius = 2.0 + +; The camera length (in metres) for this panel +.br +; You can also specify the HDF path to a scalar floating point value containing +.br +; the camera length in millimetres. +.br +panel0/clen = /LCLS/detectorPosition + +; For this panel, the fast and slow scan directions correspond to the given +.br +; directions in the lab coordinate system described above, measured in pixels. +.br +panel0/fs = +y +.br +panel0/ss = -x + +; The corner of this panel, defined as the first point in the panel to appear in +.br +; the HDF5 file, is now given a position in the lab coordinate system. +.br +; Note that "first point in the panel" is a conceptual simplification. We refer +.br +; to that corner, and to the very corner of the pixel - NOT, for example, to the +.br +; centre of the first pixel to appear. +.br +panel0/corner_x = 429.39 +.br +panel0/corner_y = -17.30 + +; You can suppress indexing for this panel if required, by setting "no_index" to +.br +; "true" or "1". +.br +panel0/no_index = 0 + +; You can also specify bad regions. Peaks with centroid locations within such +.br +; a region will not be integrated nor indexed. Bad regions are specified in +.br +; pixel units, but in the lab coordinate system (i.e. "y" points at the ceiling, +.br +; "z" is the beam direction and "x" completes the right-handed system). +.br +badregionA/min_x = -20.0 +.br +badregionA/max_x = +20.0 +.br +badregionA/min_y = -100.0 +.br +badregionA/max_y = +100.0 + +; If you have a bad pixel mask, you can include it in the HDF5 file as an +.br +; unsigned 16-bit integer array of the same size as the data. You need to +.br +; give its path within each HDF5 file, and two bitmasks. The pixel is +.br +; considered good if all of the bits which are set in "mask_good" are set, AND +.br +; if none of the bits which are set in "mask_bad" are set. +.br +mask = /processing/hitfinder/masks +.br +mask_good = 0x27 +.br +mask_bad = 0x00 + +; Any of the per-panel values can be given without a panel prefix, for example: +.br +peak_sep = 6.0 +.br +; 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). |