Improve documentation about file-based peak lists

2 files changed, 11 insertions, 7 deletions

diff --git a/doc/man/crystfel_geometry.5 b/doc/man/crystfel_geometry.5
index 6959e4cf..dad5d3d0 100644
--- a/doc/man/crystfel_geometry.5
+++ b/doc/man/crystfel_geometry.5
@@ -102,12 +102,20 @@ These specify that the entire detector should be shifted by this amount in the x
 .PD 0
 .IP "\fBpeak_list = \fIloc"
 .PD
-This gives the location of the peak list (for \fB--peaks=cxi\fR or \fB--peaks=hdf5\fR - see indexamajig(1)) in the data files.
+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 (peak list as used in CXI files from Cheetah), \fBlist3\fR (peak list as used in single-frame HDF5 files from Cheetah) and \fBauto\fR (determine layout from input file extension).
+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
 
diff --git a/doc/man/indexamajig.1 b/doc/man/indexamajig.1
index e400c211..98c15237 100644
--- a/doc/man/indexamajig.1
+++ b/doc/man/indexamajig.1
@@ -41,11 +41,7 @@ Indexamajig requires an input file with a list of diffraction patterns ("events"
 
 .SH PEAK DETECTION
 
-You can control the peak detection on the command line.  Firstly, you can choose the peak detection method using \fB--peaks=\fR\fImethod\fR.  There are three possibilities for "method" here.  \fB--peaks=hdf5\fR will take the peak locations from the HDF5 file.  It expects a two dimensional array, by default at /processing/hitfinder/peakinfo, whose size in the first dimension equals the number of peaks and whose size in the second dimension is three.  The first two columns contain the fast scan and slow scan coordinates, the third contains the intensity.  However, the intensity will be ignored since the pattern will always be re-integrated using the unit cell provided by the indexer on the basis of the peaks.  You can tell indexamajig where to find this table inside each HDF5 file using \fB--hdf5-peaks=\fR\fIpath\fR.
-
-\fB--peaks=cxi\fR works similarly to this, but expects four separate HDF5 datasets beneath \fIpath\fR, \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.
-
-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.  Therefore, the peak coordinates from \fB--peaks=cxi\fR or \fB--peaks=hdf5\fR will by default have 0.5 added to them.  Use \fB--no-half-pixel-shift\fR if this isn't what you want.
+You can control the peak detection on the command line.  Firstly, you can choose the peak detection method using \fB--peaks=\fR\fImethod\fR.  \fB--peaks=hdf5\fR or \fB--peaks=cxi\fR will take the peak locations from the input file.  See the documentation for \fBpeak_list\fR and \fBpeak_list_type\fR in crystfel_geometry(5) for details.
 
 If you use \fB--peaks=zaef\fR, indexamajig will use a simple gradient search after Zaefferer (2000).  You can control the overall threshold and minimum squared gradient for finding a peak using \fB--threshold\fR and \fB--min-squared-gradient\fR.  The threshold has arbitrary units matching the pixel values in the data, and the minimum gradient has the equivalent squared units.  Peaks will be rejected if the 'foot point' is further away from the 'summit' of the peak by more than the inner integration radius (see below).  They will also be rejected if the peak is closer than twice the inner integration radius from another peak.