From 924d68d951fd2750e126ce356c318aa76f589248 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Tue, 1 Mar 2011 18:10:21 +0100 Subject: Update docs --- doc/geometry.txt | 129 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 67 insertions(+), 62 deletions(-) diff --git a/doc/geometry.txt b/doc/geometry.txt index c195bb37..980dd85c 100644 --- a/doc/geometry.txt +++ b/doc/geometry.txt @@ -2,78 +2,83 @@ 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 (indexamajig, pattern_sim and -powder_plot) take an argument "--geometry=" (or "-g "), where -contains the geometry. CrystFEL's representation of a detector is broken down -into one or more "panels", each of which has its own location for the centre of -the panel (i.e. the location of the central beam), its own camera length, -resolution and so on. Each panel fits into the overall image taken from the -HDF5 file, defined by minimum and maximum coordinates in x and y. The -coordinates are specified inclusively, meaning that a minimum of 0 and a maximum -of 9 results in ten items. Counting begins from zero. All pixels in the image -must be assigned to a panel. - -See "A note on data orientation" below for important information about how -CrystFEL defines the axes. All coordinates (including the centre coordinates -for each panel) are measured according to these axes: there is no coordinate -system local to a panel. - -The syntax for a simple geometry might be as follows: - -; The number of panels -n_panels = 1 - -; "0/" specifies the first (and only) panel. If we had more panels, there would -; be a copy of the following lines but prefixes with "1/", "2/" and so on. - -; The region of the image which belongs to this panel: -0/min_x = 0 -0/max_x = 1023 -0/min_y = 512 -0/max_y = 1023 - -; The coordinates of the central beam which should be -; used for pixels in this panel: -0/cx = 491.9 -0/cy = 440.7 - -; The camera length (in metres) for this panel -0/clen = 67.8e-3 - -; The resolution (in pixels per metre) for this panel -0/res = 13333.3 ; 75 micron pixel size +program. Programs which care about the geometry (particularly indexamajig, +pattern_sim and powder_plot) take an argument "--geometry=" +(or "-g "), where 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 beginning with a semicolon are ignored. +; The number of panels must be specified first +n_panels = 64 + +; The number before the slash indicates which panel is referred to. +; The range of pixels in the HDF5 file which correspond to a panel are given: +0/min_fs = 0 +0/min_ss = 0 +0/max_fs = 193 +0/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 '0', then the culling described above will not +; If the badrow direction is '-', then the culling described above will not ; be performed for this panel. -0/badrow_direction = y - -; If "no_index" is "true", then peaks in this panel will not be used for -; indexing nor integrated and recorded in the stream. -0/no_index = false +0/badrow_direction = - -; The lower bound on true peak separation is about 50 pixels -0/peak_sep = 50 +; The resolution (in pixels per metre) for this panel +0/res = 9090.91 +; The characteristic peak separation. The peak detection will assume that +; genuine peaks are separated by at least this amount. +0/peak_sep = 6.0 -See the "examples" folder for some examples. +; 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. +0/clen = /LCLS/detectorPosition +; For this panel, the fast and slow scan directions correspond to the given +; directions in the lab coordinate system described above. +0/fs = +y +0/ss = -x -A note on data orientation --------------------------- +; 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. +0/corner_x = 429.39 +0/corner_y = -17.30 -In the image data extracted from the HDF5 file, CrystFEL defines "x" as the most -quickly varying coordinate in the data, and "y" as the second most quickly -varying coordinate in the data. It doesn't know what to do with any extra -dimensions in the HDF5 dataset beyond the second. +; You can suppress indexing for this panel if required, by setting "no_index" to +; "true" or "1". +0/no_index = 0 -The origin, which is considered the lower left corner of the image, is defined -by CrystFEL as the first element in the image data. Positive x points in a -direction to the right, and positive y points upwards. CrystFEL considers the -positive z direction to be the direction of the incident beam completing the -right-handed set of axes. -The detector surface is currently always assumed to be perpendicular to the -incident beam. +See the "examples" folder for some examples. -- cgit v1.2.3