diff options
Diffstat (limited to 'doc/man/crystfel_geometry.1')
| -rw-r--r-- | doc/man/crystfel_geometry.1 | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/doc/man/crystfel_geometry.1 b/doc/man/crystfel_geometry.1 new file mode 100644 index 00000000..0deb058e --- /dev/null +++ b/doc/man/crystfel_geometry.1 @@ -0,0 +1,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). |