crystfel_geometry(5): Convert to Markdown and re-structure

Still some work to be done here, but it's already an improvement.

2 files changed, 440 insertions, 343 deletions

diff --git a/doc/man/crystfel_geometry.5 b/doc/man/crystfel_geometry.5
deleted file mode 100644
index 998aa213..00000000
--- a/doc/man/crystfel_geometry.5
+++ /dev/null
@@ -1,343 +0,0 @@
-.\"
-.\" Geometry man page
-.\"
-.\" Copyright © 2012-2023 Deutsches Elektronen-Synchrotron DESY,
-.\"                       a research centre of the Helmholtz Association.
-.\"
-.\" Part of CrystFEL - crystallography with a FEL
-.\"
-
-.TH CRYSTFEL\_GEOMETRY 5
-.SH NAME
-CRYSTFEL DETECTOR GEOMETRY DESCRIPTION FILES
-
-.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
-\fBindexamajig\fR) take an argument \fB--geometry=\fR\fIfilename\fR, where
-\fIfilename\fR contains the geometry.
-
-.PP
-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 an overall
-data block 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.
-.PP
-The job of the geometry file is to establish a relationship an 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:
-
-.IP
-+z is the beam direction, and points along the beam (i.e. away from the source)
-
-.IP
-+y points towards the zenith (ceiling).
-
-.IP
-+x completes the right-handed coordinate system.
-
-.PP
-Naively speaking, this means that CrystFEL looks 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 geometry file should contain lines of the following form:
-
-.IP
-\fIpanel\fR/clen = 0.560
-
-.PP
-\fIpanel\fR can be any name of your choosing.  You can make up names for your panels however you please, as long as the first three letters are not "\fBbad\fR" or "rigid_group" (in lower case), because these are used for special purposes (see below).
-
-.PP
-You can also specify values without a panel name, for example:
-
-.IP
-clen = 0.560
-
-.PP
-In this case, the value will be used for all \fBsubsequent\fR panels appearing in the file which do not have their own specific values for the property, or until you specify another default value further down the file.  Panel-specific values always have priority over default values, and changing the default value has no effect for panels which had already be mentioned at the point in the file where the default value was specified.
-
-.PP
-Comments start with a semicolon.  They will be ignored.
-
-.SH TOP-LEVEL ONLY PARAMETERS
-
-The parameters in this section can only appear without a panel name.
-
-.PD 0
-.IP "\fBwavelength = \fInnn\fR \fB[m|A]"
-.IP "\fBphoton_energy = \fInnn\fR \fB[eV|keV]"
-.IP "\fBelectron_voltage = \fInnn\fR \fB[V|kV]"
-.PD
-These statements specify the incident radiation wavelength.  You must include one (not more) of these statements.  \fBwavelength\fR specifies the wavelength directly, \fBphoton_energy\fR specifies the energy per photon for electromagnetic radiation (e.g. X-rays), and \fBelectron_voltage\fR specifies the accelerating voltage for an electron beam.
-.IP
-\fInnn\fR can be a literal number, or it can be a header location in the image data file.  In the latter case, the program will do what you expect in the case of multi-frame data files, e.g. a scalar value in the metadata will be applied to all frames, or an array of values can be used to provide a separate wavelength for each frame.
-.IP
-Units should be specified after the value (or location).  These can be \fBm\fR or \fBA\fR for \fBwavelength\fR, \fBeV\fR or \fBkeV\fR for \fBphoton_energy\fR, and \fBV\fR or \fBkV\fR for \fBelectron_voltage\fR.  For \fBphoton_energy\fR, if no units are given then the value will be taken to be in eV.
-
-.PD 0
-.IP "\fBbandwidth = \fIbw"
-.PD
-The bandwidth of the radiation, expressed as a fraction of the wavelength.  The bandwidth will be interpreted as the standard deviation of a Gaussian spectrum, and used for calculating reflection positions.
-
-.PD 0
-.IP "\fBdetector_shift_x = \fInnn \fB[m|mm]"
-.IP "\fBdetector_shift_y = \fInnn \fB[m|mm]"
-.PD
-These specify that the entire detector should be shifted by this amount in the x and y directions.  The units should be specified as \fBm\fR or \fBmm\fR.  If units are not specified, the value will be taken as metres.  \fInnn\fR can be a file metadata location (e.g. an HDF5 path).
-
-.PD 0
-.IP "\fBpeak_list = \fIloc"
-.PD
-This gives the location of the peak list in the data files, for peak detection methods \fBhdf5\fR and \fBcxi\fR (see \fBman indexamajig\fR).
-
-.PD 0
-.IP "\fBpeak_list_type = \fIlayout"
-.PD
-Specify the layout of the peak list.  Allowed values are \fBcxi\fR, \fBlist3\fR and \fBauto\fR.
-.IP
-\fBlist3\fR expects the peak list to be a two dimensional array whose size in the first dimension equals the number of peaks and whose size in the second dimension is exactly three.  The first two columns contain the fast scan and slow scan coordinates, the third contains the intensities.  This is the correct option for "single-frame" HDF5 files as written by older versions of Cheetah.
-.IP
-\fBcxi\fR expects the peak list to be a group containing four separate HDF5 datasets: \fBnPeaks\fR, \fBpeakXPosRaw\fR, \fBpeakYPosRaw\fR and \fBpeakTotalIntensity\fR.  See the specification for the CXI file format at http://www.cxidb.org/ for more details.  This is the correct option for "multi-event" HDF5 files as output by recent versions of Cheetah.
-.IP
-\fBauto\fR tells CrystFEL to decide between the above options based on the file extension.
-.IP
-Note that CrystFEL considers all peak locations to be distances from the corner of the detector panel, in pixel units, consistent with its description of detector geometry (see 'man crystfel_geometry').  The software which generates the HDF5 or CXI files, including Cheetah, may instead consider the peak locations to be pixel indices in the data array.  To compensate for this discrepancy, CrystFEL will, by default, add 0.5 to all peak coordinates. Use \fB--no-half-pixel-shift\fR if this isn't what you want.
-
-.SH PER-PANEL VALUES
-
-The following parameters can be set for each panel individually.  Don't forget that they can also be used at the "top level" to set default values.
-
-.PD 0
-.IP \fBdata\fR
-.PD
-The location in the HDF5 file of the data block that contains the panel's data. The default value is \fB/data/data\fR.  If the HDF5 file contains multiple events, and each event is stored in a different data block, the variable part of the path can be represented using the % character placeholder.
-
-Example:
-.IP
-data = /data/%/rawdata
-
-The CrystFEL programs will look for the first event at /data/\fIevent1_name\fR/rawdata, for the second at /data/\fIevent2_name\fR/rawdata, etc., where \fIevent_name\fR and \fIevent2_name\fR are simply whatever the program could find in the HDF5 file which matched the pattern you gave.
-
-.PD 0
-.IP \fBdim\fIn\fR\fR
-.PD
-Information about the layout of the data block identified by the 'data' property. \fIn\fR is an integer number identifying an axis in a multidimensional HDF5 data block. The property value defines the kind of information encoded by the axis. Possible values are:
-.RS
-.IP %
-.PD
-event placeholder,the axis encodes events
-.IP ss
-.PD
-the axis encoding the slow scan index
-.IP fs
-.PD
-the axis encodes the fast scan index
-.IP \fInumber\fR
-.PD
-the index in this dimension should be fixed at \fInumber\fR.
-.RE
-.IP
-CrystFEL assumes that the data block defined by the 'data' property has a dimensionality corresponding to the axis with the highest value of \fIn\fR defined by the 'dim' property.  That is, if the geometry file specifies \fBdim0\fR, \fBdim1\fR and \fBdim2\fR, then the data block is expected to be three-dimensional.  The size of the data block along each of those axes comes from the image metadata (e.g. the array sizes in the HDF5 file).
-.IP
-The lowest number of \fIn\fR corresponds to the \fImost slowly-changing\fR array index as the data block is traversed.  The default values are \fBdim0=ss\fR and \fBdim1=fs\fR.  The value of \fIn\fR corresponding to \fBfs\fR must not be lower than the value assigned to \fBss\fR, i.e. "fast scan is always fast scan".
-
-Example:
-.RS
-.PD 0
-.IP
-dim0 = %
-.IP
-dim1 = 4
-.IP
-dim2 = ss
-.IP
-dim3 = fs
-.RE
-.IP
-The above snippet specifies that the data block is 4-dimensional. The first axis represents the event number, the index in the second axis is always 4, and the remaining two axes are the image coordinates.
-
-.PD 0
-.IP \fBmin_fs\fR
-.IP \fBmin_ss\fR
-.IP \fBmax_fs\fR
-.IP \fBmax_ss\fR
-.PD
-The range of pixels in the data block specified by the 'data' property that corresponds to the panel, in fast scan/slow scan coordinates, specified \fBinclusively\fR.
-
-.PD 0
-.IP \fBadu_per_eV\fR
-.IP \fBadu_per_photon\fR
-.PD
-The number of detector intensity units (ADU) which will arise from either one electron-Volt of photon energy, or one photon.  This is used to estimate Poisson errors.  Note that setting different values for this parameter for different panels does \fBnot\fR result in the intensities being scaled accordingly when integrating data.  You should only specify one out of \fBadu_per_eV\fR and \fBadu_per_photon\fR.
-
-.PD 0
-.IP \fBres\fR
-The resolution (in pixels per metre) for this panel.  This is one over the pixel size in metres.
-
-.PD 0
-.IP \fBclen\fR
-.PD
-The camera length (in metres) for this panel. You can also specify the HDF5 path to a floating point data block containing the camera length in millimetres.  For example: "panel0/clen = /LCLS/detectorPosition".  If the HDF5 file contains more than one event, and the data block is scalar, the camera length value
-it contains will be used for all events. If, however, the data block is multidimensional and the second dimension is bigger than one, the CrystFEL programs will try to match the content of the data block with the events in the file, assigning the first value in the data block to the first event in the file,
-the second value in the data block to the second event in the file, etc. See \fBcoffset\fR as well.
-
-.PD 0
-.IP \fBcoffset\fR
-.PD
-The camera length offset (in metres) for this panel.  This number will be added to the camera length (\fBclen\fR).  This can be useful if the camera length is taken from the HDF5 file and you need to make an adjustment, such as that from a calibration experiment.
-
-.PD 0
-.IP \fBfs\fR
-.IP \fBss\fR
-.PD
-For this panel, the fast and slow scan directions correspond to the given directions in the lab coordinate system described above, measured in pixels.  Example: "panel0/fs = 0.5x+0.5y-0.0001z".  Including a component in the z direction means that the panel is not perpendicular to the X-ray beam.
-
-.PD 0
-.IP \fBcorner_x\fR
-.IP \fBcorner_y\fR
-.PD
-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. The units are pixel widths of the current panel.  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.
-
-.PD 0
-.IP \fBmax_adu\fR
-The saturation value for the panel.  You can use this to exclude saturated peaks from the peak search or to avoid integrating saturated reflections.  However, usually it's best to include saturated peaks, and exclude saturated reflections with the --max-adu option of process_hkl and partialator.  Therefore you should avoid setting this parameter - a warning will be displayed if you do.
-
-.PD 0
-.IP \fBflag_lessthan
-.IP \fBflag_morethan
-.IP \fBflag_equal
-Mark pixels as "bad" if their values are respectively less than, more than or equal to the given value.  Note carefully that the inequalities are strict, not inclusive: "less than", not "less than or equal to".
-
-.PD 0
-.IP \fBmask_edge_pixels\fR
-Mark the specified number of pixels, at the edge of the panel, as "bad".
-
-.PD 0
-.IP \fBmaskN_data\fR
-.IP \fBmaskN_file\fR
-.IP \fBmaskN_goodbits\fR
-.IP \fBmaskN_badbits\fR
-.PD
-These specify the parameters for bad pixel mask number \fIN\fR.  You can have up to 8 bad pixel masks, numbered from 0 to 7 inclusive.  Placeholders ('%') in the location (\fBmaskN_data\fR) will be substituted with the same values as used for the placeholders in the image data, although there may be fewer of them for the masks than for the image data.
-.IP
-You can optionally give a filename for each mask with \fBmaskN_file\fR.  The filename may be specified as an absolute filename, or relative to the working directory.  If you don't specify a filename, the mask will be read from the same file as the image data.
-.IP
-A pixel will be considered bad unless \fIall\fR of the bits which are set in \fBgoodbits\fR are set.  A pixel will also be considered bad if \fIany\fR of the bits which are set in \fBbadbits\fR are set.  Note that pixels can additionally be marked as bad via other mechanisms as well (e.g. \fBno_index\fR or \fBbad\fR).
-.IP
-Example:
-.RS
-.PD 0
-.IP
-mask2_data = /data/bad_pixel_map
-.IP
-mask2_file = /home/myself/mybadpixels.h5
-.IP
-mask2_goodbits = 0x00
-.IP
-mask2_badbits = 0xff
-.RE
-.PD
-.IP
-There are some older mask directives which are still understood by this version of CrystFEL.  They are synonyms of the new directives as follows:
-.RS
-.PD 0
-.IP
-mask       ----->   mask0_data
-.IP
-mask_file  ----->   mask0_file
-.IP
-mask_good  ----->   mask0_goodbits
-.IP
-mask_bad   ----->   mask0_badbits
-.RE
-
-.PD 0
-.IP \fBsaturation_map\fR
-This specifies the location of the per-pixel saturation map in the HDF5 file.  This works just like \fBmask\fR in that it can come from the current file or a separate one (see \fBsaturation_map_file\fR).  Reflections will be rejected if they contain any pixel above the per-pixel values, \fBin addition\fR to the other checks (see \fBmax_adu\fR).
-
-.PD
-.IP \fBsaturation_map_file\fR
-Specifies that the saturation map should come from the HDF5 file named here, instead of the HDF5 file being processed.  It can be an absolute filename or relative to the working directory.
-
-.PD 0
-.IP \fBno_index\fR
-Set this to 1 or "true" to ignore this panel completely.
-
-.SH BAD REGIONS
-
-Bad regions will be completely ignored by CrystFEL.  You can specify the pixels to exclude in pixel units, either in the lab coordinate system (see above) or in fast scan/slow scan coordinates (mixtures are not allowed).   In the latter case, the range of pixels is specified \fIinclusively\fR.  Bad regions are distinguished from normal panels by the fact that they begin with the three letters "bad".
-.PP
-If you specify a bad region in fs/ss (image data) coordinates, you must also specify which panel name you are referring to.
-.PP
-Note that bad regions specified in x/y (lab frame) coordinates take longer to process (when loading images) than regions specified in fs/ss (image data) coordinates.  You should use fs/ss coordinates unless the convenience of x/y coordinates outweighs the speed reduction.
-
-Examples:
-.br
-.br
-badregionA/min_x = -20.0
-.br
-badregionA/max_x = +20.0
-.br
-badregionA/min_y = -100.0
-.br
-badregionA/max_y = +100.0
-
-.br
-badregionB/min_fs = 128
-.br
-badregionB/max_fs = 160
-.br
-badregionB/min_ss = 256
-.br
-badregionB/max_ss = 512
-.br
-badregionB/panel = q0a1
-
-
-.SH RIGID GROUPS AND RIGID GROUP COLLECTIONS
-
-Some operations in CrystFEL, such as refining the detector geometry, need a group of panels to be treated as a single rigid body.  Such "rigid groups" might describe the fact that certain panels are physically connected to one another, for example, a pair of adjacent ASICs in the CSPAD detector.  Rigid groups can be defined in the geometry file by listing the panels belonging to each group and assigning the group a name, like this:
-.RS
-.IP "\fBrigid_group_\fIname\fR = \fIpanel1\fR,\fIpanel2\fR"
-.RE
-.PP
-This creates a rigid group called \fIname\fR, containing panels \fIpanel1\fR and \fIpanel2\fR.
-.PP
-You can specify multiple sets of rigid groups.  For example, as well as specifying the relationships between pairs of ASICs mentioned above, you may also want to specify that certain groups of panels belong to an independently-movable quadrant of the detector.  You can declare and name such "rigid group collections" as follows:
-.RS
-.IP "\fBrigid_group_collection_\fIname\fR = \fIrigidgroup1\fR,\fIrigidgroup2\fR"
-.RE
-.PP
-This creates a rigid group collection called \fIname\fR, containing rigid groups \fIrigidgroup1\fR and \fIrigidgroup2\fR.
-.PP
-Definitions of rigid groups and rigid group collections can appear at any place in the geometry file and can be declared using the following global properties.  They are not panel properties, and therefore don't follow the usual panel/property syntax.  You can assign any number of panels to a rigid group, and any number of rigid groups to a rigid group collection.  A panel can be a member of any number of rigid groups.
-
-.PP
-See the "examples" folder for some examples (look at the ones ending in .geom).
-
-.SH AUTHOR
-This page was written by Thomas White and Valerio Mariani.
-
-.SH REPORTING BUGS
-Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
-
-.SH COPYRIGHT AND DISCLAIMER
-Copyright © 2012-2021 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
-.P
-CrystFEL is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
-.P
-CrystFEL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
-.P
-You should have received a copy of the GNU General Public License along with CrystFEL.  If not, see <http://www.gnu.org/licenses/>.
-
-.SH SEE ALSO
-.BR crystfel (7),
-.BR indexamajig (1)
diff --git a/doc/man/crystfel_geometry.5.md b/doc/man/crystfel_geometry.5.md
new file mode 100644
index 00000000..dffc1d7f
--- /dev/null
+++ b/doc/man/crystfel_geometry.5.md
@@ -0,0 +1,440 @@
+% crystfel_geometry(5)
+
+INTRODUCTION
+============
+
+A CrystFEL "geometry file", usually named _something.geom_, is used by programs
+in the CrystFEL suite to get information about:
+
+* The physical position of the detector, including all sub-detectors if
+  applicable.
+
+* The layout of data in the file, especially if a "container format" such as
+  HDF5 is used.
+
+* The values of parameters such as the incident radiation wavelength, or a
+  description of where to get these values in the data files.
+
+
+COORDINATE SYSTEM
+=================
+
+It's important to distinguish between the **data coordinate system** and the
+**laboratory coordinate system**.
+
+The **data coordinate system** consists of the **fast scan** and **slow scan**
+directions.  **Fast scan** refers to the direction whose coordinate changes
+most quickly as the bytes in the data file are moved through.  **Slow scan**
+refers to the other dimension of the 2D data array.  Arrays in the data file
+can have more than two dimensions - see secion **DATA DIMENSIONS** below.
+
+CrystFEL's **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.
+
+The CrystFEL GUI shows +x horizontally (left to right), and +y vertically
+(bottom to top).  This means that the GUI shows images from the "into the beam"
+perspective.
+
+
+PANELS AND GEOMETRY FILE SYNTAX
+===============================
+
+CrystFEL's representation of a detector is broken down into one or more
+**panels**, each of which has its own position, size and various other
+parameters.
+
+Lines in a CrystFEL geometry file have the following general form:
+
+    parameter = value
+
+Many parameters, however, are specified for a specific panel, as follows:
+
+    panel_name/parameter = value
+
+Most parameters can theoretically be specified on a per-panel level, but in
+practice are the same for all panels.  For example, the pixel size is usually
+the same for all panels.  In this case, specify the parameter once, without
+a panel name, at the top of the geometry file.  The value will then be used
+for all panels which are *first mentioned* later in the file.
+
+The panel names can be anything of your choosing, except that the names must
+not start with **bad**, **group** or **rigid_group**.  These are reserved for
+other purposes (see below).
+
+You can also add comments, for example:
+
+    ; This is a comment
+    mypanel/min_fs = 34    ; This is also a comment
+
+
+SPECIFYING THE WAVELENGTH AND BEAM PARAMETERS
+=============================================
+
+To specify the incident beam wavelength, you need to use one of the following
+forms (only one):
+
+**wavelength** = _nnn_ [**m**|**A**]
+: Specifies a wavelength directly, in meters or Angstroms according to the
+: suffix.
+
+**photon_energy** = _nnn_ [**eV**|**keV**]
+: Specifies the energy per photon of electromagnetic radiation (e.g. X-rays).
+: If no units suffix is given, **eV** (electron volts) will be assumed.
+
+**electron_voltage** = _nnn_ [**V**|**kV**]
+: Specifies the accelerating voltage in an electron microscope.  This should be
+: the accelerating voltage, not the relativistically-corrected energy of the
+: accelerated electrons (the difference is small).
+
+For all of these, a data location in the input files can be given instead of
+a literal number.  For example, with data in HDF5 format:
+
+    wavelength = /data/LCLS/wavelength m
+
+If there are multiple frames per input file, the program will do what you
+expect depending on the type of `/data/LCLS/wavelength`.  For example, a scalar
+value in the metadata will be applied to all frames, or an array of values can
+be used to provide a separate wavelength for each frame.
+
+You can also specify the radiation bandwidth, as follows:
+
+**bandwidth** = _bw_
+: The bandwidth of the radiation, expressed as a fraction of the wavelength.
+: The bandwidth will be interpreted as the standard deviation of a Gaussian
+: spectrum, and used for calculating reflection positions.
+
+
+PHYSICAL PANEL LOCATIONS
+========================
+
+For each panel, the physical location is controlled by the **fs**, **ss**,
+**corner_x**, **corner_y** and **clen** parameters, for example:
+
+    q3a15/fs = -0.0010058292x +0.9999995232y
+    q3a15/ss = -0.9999995232x -0.0010058292y
+    q3a15/corner_x = 575.475
+    q3a15/corner_y = -221.866
+    q3a15/coffset = 0.01
+
+
+**fs**, **ss**
+: The vectors in the lab coordinate system of the fast and slow scan directions
+: of the panel data, measured in pixels.  Inclusion of a component in the z
+: direction means that the panel is not perpendicular to the X-ray beam.
+
+**corner_x**, **corner_y**
+: The position in x and y (lab coordinate system) of the corner of this panel.
+: The corner is defined as the first point in the panel to appear in the image
+: data. The units are pixel widths of the current panel.  This should be the
+: location of the very corner of the panel (not the center of the first pixel).
+
+**coffset**
+: The offset of the panel along the z-direction from the position given by
+: **clen**.
+
+The overall detector position in the z-direction is given by **clen**, which
+can only be specified once in the geometry file (not for each panel):
+
+**clen** = _nnn_ [mm|m]
+: The overall z-position ("camera length") for the detector, or a data file
+: location, and units (m or mm).  If no units are given, **m** will be assumed
+: if the value is given as a literal number, or **mm** if it's a data file
+: header location.  This discrepancy is for historical reasons, and you should
+: always specify the units.  Like when specifying the wavelength (see above),
+: CrystFEL should do what you expect with multi-frame data files.
+
+### Per-frame beam center position
+
+You can specify an overall detector shift.  The most common use of this is for
+serial scanning electron diffraction experiments, where the beam center moves
+from frame to frame.  You should avoid using this feature, especially with a
+metadata location, because it limits CrystFEL's ability to pre-calculate
+certain data structures.  This feature is likely to be removed in future
+versions.
+
+**detector_shift_**[x,y] = _nnn_ [m|mm]
+: These specify that the entire detector should be shifted by this amount in the
+: x and y directions.  The units should be specified as m or mm.  If units are
+: not specified, the value will be taken as metres.  nnn can be a file metadata
+: location (e.g. an HDF5 path).
+
+
+PANEL DATA LOCATIONS
+====================
+
+data
+: The location in the HDF5 file of the data block that contains the panel's data.
+: The default value is /data/data.  If the HDF5 file contains multiple events,
+: and each event is stored in a different data block, the variable part of the
+: path can be represented using the % character placeholder.
+:
+: Example:
+:
+:     data = /data/%/rawdata
+:
+: The CrystFEL programs will look for the first event at
+: /data/event1_name/rawdata, for the second at /data/event2_name/rawdata, etc.,
+: where event_name and event2_name are simply whatever the program could find in
+: the HDF5 file which matched the pattern you gave.
+
+dimn
+: Information about the layout of the data block identified by the 'data'
+: property. n is an integer number identifying an axis in a multidimensional HDF5
+: data block. The property value defines the kind of information encoded by the
+: axis. Possible values are:
+: % - event placeholder,the axis encodes events
+: ss - the axis encoding the slow scan index
+: fs - the axis encodes the fast scan index
+: number -  the index in this dimension should be fixed at number.
+:
+: CrystFEL assumes that the data block defined by the 'data' property has a
+: dimensionality corresponding to the axis with the highest value of n defined by
+: the 'dim' property.  That is, if the geometry file specifies dim0, dim1 and
+: dim2, then the data block is expected to be three-dimensional.  The size of the
+: data block along each of those axes comes from the image metadata (e.g. the
+: array sizes in the HDF5 file).
+:
+: The lowest number of n corresponds to the most slowly-changing array index as
+: the data block is traversed.  The default values are dim0=ss and dim1=fs.  The
+: value of n corresponding to fs must not be lower than the value assigned to ss,
+: i.e. "fast scan is always fast scan".
+:
+: Example:
+:
+:     dim0 = %
+:     dim1 = 4
+:     dim2 = ss
+:     dim3 = fs
+:
+: The above snippet specifies that the data block is 4-dimensional. The first
+: axis represents the event number, the index in the second axis is always 4, and
+: the remaining two axes are the image coordinates.
+
+min_fs, min_ss, max_fs, max_ss
+: The range of pixels in the data block specified by the 'data' property that
+: corresponds to the panel, in fast scan/slow scan coordinates, specified
+: inclusively.
+
+
+PEAK LISTS
+==========
+
+peak_list = loc
+: This gives the location of the peak list in the data files, for peak detection
+: methods hdf5 and cxi (see man indexamajig).
+
+peak_list_type = layout
+: Specify the layout of the peak list.  Allowed values are cxi, list3 and auto.
+:
+: list3 expects the peak list to be a two dimensional array whose size in the
+: first dimension equals the number of peaks and whose size in the second
+: dimension is exactly three.  The first two columns contain the fast scan and
+: slow scan coordinates, the third contains the intensities.  This is the correct
+: option for "single-frame" HDF5 files as written by older versions of Cheetah.
+:
+: cxi expects the peak list to be a group containing four separate HDF5 datasets:
+: nPeaks, peakXPosRaw, peakYPosRaw and peakTotalIntensity.  See the specification
+: for the CXI file format at http://www.cxidb.org/ for more details.  This is the
+: correct option for "multi-event" HDF5 files as output by recent versions of
+: Cheetah.
+:
+: auto tells CrystFEL to decide between the above options based on the file extension.
+:
+: Note that CrystFEL considers all peak locations to be distances from the corner
+: of the detector panel, in pixel units, consistent with its description of
+: detector geometry (see 'man crystfel_geometry').  The software which generates
+: the HDF5 or CXI files, including Cheetah, may instead consider the peak
+: locations to be pixel indices in the data array.  To compensate for this
+: discrepancy, CrystFEL will, by default, add 0.5 to all peak coordinates. Use
+: --no-half-pixel-shift if this isn't what you want.
+
+
+DETECTOR RESPONSE PROPERTIES
+============================
+
+adu_per_eV, adu_per_photon
+: The number of detector intensity units (ADU) which will arise from either one
+: electron-Volt of photon energy, or one photon.  This is used to estimate
+: Poisson errors.  Note that setting different values for this parameter for
+: different panels does not result in the intensities being scaled accordingly
+: when integrating data.  You should only specify one out of adu_per_eV and
+: adu_per_photon.
+
+res
+: The resolution (in pixels per metre) for this panel.  This is one over the
+: pixel size in metres.
+
+max_adu
+: The saturation value for the panel.  You can use this to exclude saturated
+: peaks from the peak search or to avoid integrating saturated reflections.
+: However, usually it's best to include saturated peaks, and exclude saturated
+: reflections with the --max-adu option of process_hkl and partialator.
+: Therefore you should avoid setting this parameter - a warning will be displayed
+: if you do.
+
+saturation_map
+: This specifies the location of the per-pixel saturation map in the HDF5 file.
+: This works just like mask in that it can come from the current file or a
+: separate one (see saturation_map_file).  Reflections will be rejected if they
+: contain any pixel above the per-pixel values, in addition to the other checks
+: (see max_adu).
+
+saturation_map_file
+: Specifies that the saturation map should come from the HDF5 file named here,
+: instead of the HDF5 file being processed.  It can be an absolute filename or
+: relative to the working directory.
+
+
+BAD REGIONS
+===========
+
+Bad regions will be completely ignored by CrystFEL.  You can specify the pixels
+to exclude in pixel units, either in the lab coordinate system (see above) or
+in fast scan/slow scan coordinates (mixtures are not allowed).   In the latter
+case, the range of pixels is specified inclusively.  Bad regions are
+distinguished from normal panels by the fact that they begin with the three
+letters "bad".
+
+If you specify a bad region in fs/ss (image data) coordinates, you must also
+specify which panel name you are referring to.
+
+Note that bad regions specified in x/y (lab frame) coordinates take longer to
+process (when loading images) than regions specified in fs/ss (image data)
+coordinates.  You should use fs/ss coordinates unless the convenience of x/y
+coordinates outweighs the speed reduction.
+
+no_index
+: Set this to 1 or "true" to ignore this panel completely.
+
+flag_lessthan, flag_morethan, flag_equal
+: Mark pixels as "bad" if their values are respectively less than, more than or
+: equal to the given value.  Note carefully that the inequalities are strict, not
+: inclusive: "less than", not "less than or equal to".
+
+mask_edge_pixels
+: Mark the specified number of pixels, at the edge of the panel, as "bad".
+
+maskN_data, maskN_file, maskN_goodbits, maskN_badbits
+: These specify the parameters for bad pixel mask number N.  You can have up to 8
+: bad pixel masks, numbered from 0 to 7 inclusive.  Placeholders ('%') in the
+: location (maskN_data) will be substituted with the same values as used for the
+: placeholders in the image data, although there may be fewer of them for the
+: masks than for the image data.
+: 
+: You can optionally give a filename for each mask with maskN_file.  The filename
+: may be specified as an absolute filename, or relative to the working directory.
+: If you don't specify a filename, the mask will be read from the same file as
+: the image data.
+: 
+: A pixel will be considered bad unless all of the bits which are set in goodbits
+: are set.  A pixel will also be considered bad if any of the bits which are set
+: in badbits are set.  Note that pixels can additionally be marked as bad via
+: other mechanisms as well (e.g. no_index or bad).
+
+Example:
+
+    mask2_data = /data/bad_pixel_map
+    mask2_file = /home/myself/mybadpixels.h5
+    mask2_goodbits = 0x00
+    mask2_badbits = 0xff
+
+There are some older mask directives which are still understood by this version
+of CrystFEL.  They are synonyms of the new directives as follows:
+
+    mask       ----->   mask0_data
+    mask_file  ----->   mask0_file
+    mask_good  ----->   mask0_goodbits
+    mask_bad   ----->   mask0_badbits
+
+Examples:
+
+    badregionA/min_x = -20.0
+    badregionA/max_x = +20.0
+    badregionA/min_y = -100.0
+    badregionA/max_y = +100.0
+
+    badregionB/min_fs = 128
+    badregionB/max_fs = 160
+    badregionB/min_ss = 256
+    badregionB/max_ss = 512
+    badregionB/panel = q0a1
+
+
+DETECTOR HIERARCHY
+==================
+
+Detector panels can be combined into **groups**.  Certain operations,
+especially detector geometry refinement, use these groups to conveniently move
+panels.  Groups are specified as follows:
+
+    group_abc = panel1,panel2
+    group_def = panel3,panel4
+
+This creates a group called **abc**, containing panels **panel1** and
+**panel2**, and a group **def** containing **panel3** and **panel4**.
+
+Groups can themselves be combined into higher-level groups, for example:
+
+    group_all = abc,def
+
+This defines a group called *all** which contains both of the groups created
+above.
+
+The highest-level group should always be called **all**.
+
+If the detector consists of only one panel, CrystFEL will automatically create
+the **all** group containing it.
+
+The **group** system replaces the **rigid_group** system used in older versions
+of CrystFEL.  If the geometry file contains any **rigid_group** lines, they
+will be ignored in this version.
+
+
+EXAMPLES
+========
+
+For examples, look in the **examples** folder, which can be found online at
+https://gitlab.desy.de/thomas.white/crystfel/-/tree/master/doc/examples
+
+
+AUTHOR
+======
+
+This page was written by Thomas White and Valerio Mariani.
+
+
+REPORTING BUGS
+==============
+
+Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
+
+
+COPYRIGHT AND DISCLAIMER
+========================
+
+Copyright © 2023 Deutsches Elektronen-Synchrotron DESY, a research centre of
+the Helmholtz Association.
+
+CrystFEL is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+CrystFEL is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+CrystFEL.  If not, see <http://www.gnu.org/licenses/>.
+
+
+SEE ALSO
+========
+
+**crystfel**(7), **indexamajig**(1), **adjust_detector**(1),
+**align_detector**(1)