geoptimiser.1

.\"
.\" geoptimiser man page
.\"
.\" Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY,
.\"                       a research centre of the Helmholtz Association.
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"

.TH GEOPTIMISER 1
.SH NAME
geoptimiser \- detector geometry refinement
.SH SYNOPSIS
.PP
.BR geoptimiser
\fB-i \fIinput.stream \fB-g \fIinput.geom \fB-o \fIoutput.geom \fB-c \fIconnected_rigidgroup_coll \fB-q \fI\quadrant_rigidgroup_coll\fR
[\fBoptions\fR]
.PP
\fBgeoptimiser --help\fR

.SH DESCRIPTION

\fBgeoptimiser\fR refines and optimizes the detector geometry by comparing the locations of observed Bragg peaks in a set of indexed patterns with the spot locations predicted from the crystal indexing procedure. It can refine position, rotation and distance of each panel relative to the interaction region. It requires a stream file with indexed patterns, a geometry file with the detector geometry to refine, and some parameters to specify which panels are physically connected to each other and which are attached to the same physical support (for example, all panels in a quadrant of the CSPAD detector). The output is a geometry file with the optimized detector geometry and a set of diagnostic error maps in HDF5 format.  Several options are available to tweak the number of peaks included in the optimization procedure based on a range of criteria.
For a complete description of the optimization algorithm, see the following paper:

.IP
O. Yefanov, V. Mariani, C. Gati, T. A. White, H. N. Chapman, and A. Barty. "Accurate determination of segmented X-ray detector geometry". Optics Express 23 (2015) 28459. doi:10.1364/OE.23.028459.

.PP
For minimal basic use, you need to provide a stream file with diffraction patterns, a filename for the output optimized geometry, and the name of two rigid group collections defined in the geometry file: one describing which panels in the detector are physically connected (and hence whose geometry should be optimized as if they were a single panel), and one to describe which panels are attached to the same underlying support (whose position and orientation are likely to be correlated).

.PP
See \fBman crystfel_geometry\fR for information on how to create a file describing the detector geometry, and guidelines to define the required rigid groups and rigid groups collections.

.PP
Geoptimizer saves error maps before and after the geometry optimization. These maps show an estimation of the geometry error as average displacement, for each pixel, between the predicted and the observed positions of the Bragg peaks. The maps are color-scaled PNG files and
are named "error_map_before.png" and "error_map_after.png" respectively. In order to better visualize small local errors, the color range has been set to show all displacements bigger that 1 pixel as white (in other words, "displacement saturation" is set at 1 pixel).


.SH OPTIONS
.PD 0
.IP "\fB-i\fR \fIfilename\fR"
.IP \fB--input=\fR\fIfilename\fR
.PD
Give the filename of the stream from which to read the indexed patterns.

.PD 0
.IP "\fB-g\fR \fIfilename\fR"
.IP \fB--geometry=\fR\fIfilename\fR
.PD
Read the detector geometry to optimize from \fIfilename\fR.  If this option is omitted, the geometry file from the stream's header will be used (see \fB--input\fR), if present.

.PD 0
.IP "\fB-o\fR \fIfilename\fR"
.IP \fB--output=\fR\fIfilename\fR
.PD
Write the optimized detector geometry to \fIfilename\fR.

.PD 0
.IP "\fB-c \fIname\fR"
.IP \fB--connected=\fIname\fR
.PD
Specifies the name of the rigid group collection for connected panels.  This rigid group collection describes how the panels are physically connected in the detector.
A set of rigid groups must be defined in the geometry file, with each group containing only panels that are physically connected to each other (for example the pairs of ASICs sharing the same piece of detector silicon in the CSPAD detector).
.sp
If a given rigid group is a member of \fIname\fR, then panels which are members of that rigid group will be kept strictly in the same relative position and orientation relative to one another.

.PD 0
.IP "\fB-q\fR \fIname\fR"
.IP \fB--quadrants=\fR\fIname\fR
.PD
Specifies the name of the rigid group collection for detector 'quadrants'.  This rigid group collection describes how panels are connected to the underlying support of the detector, for example, the panels belonging to the same quadrant of the CSPAD detector.
.sp
If a given rigid group is a member of \fIname\fR, then panels which are members of that rigid group and which do not contain enough peaks for positional refinement will be moved according to the average movement of the other panels in the group.

.PD 0
.IP \fB--no-error-maps\fR
.PD
Forces geoptimiser not to save error maps.

.PD 0
.IP "\fB-x\fR \fIn\fR"
.IP \fB--min-num-peaks-per-pixel=\fR\fIn\fR
.PD
Sets the minimum number of peaks that should fall within a pixel, across all indexed patterns, to contribute to the geometry optimization. The default value is 3.

.PD 0
.IP "\fB-p\fR \fIn\fR"
.IP \fB--min-num-pixels-per-conn-group=\fR\fIn\fR
.PD
Sets the minimum number of pixels that contribute to the geometry opimization (see the \fB--min-num-peaks-per-pixel\fR option above ) that a connected group should have for the group to be optimized independently. The default value is 100.

.PD 0
.IP \fB--min-num-peaks-per-panel=\fR\fIn\fR
.PD
This option has been renamd to  \fB--min-num-pixels-per-conn-group\fR. It has been deprecated and will soon be removed. It is currently mapped to the \fB--min-num-pixels-per-conn-group\fR option.

.PD 0
.IP "\fB-l\fR"
.IP \fB--most-freq-clen\fR
.PD
Some stream files can contain patterns collected using different camera lengths. By default, detector distance is optimized using only patterns collected with the most frequent camera length in the stream file.
However, all patterns are used to compute panel shifts and rotations. With this option, shifts are rotation are computed with the same subset of patterns used for the detector distance optimization.

.PD 0
.IP "\fB-s\fR"
.IP \fB--individual-dist-offset\fR
.PD
By default, geoptimiser optimizes detector distance assuming that all panels have the same distance from the sample (i.e., a single distance is optimized for the whole detector). With this option, each panel's
distance is instead optimized independently.

.PD 0
.IP "\fB-m\fR \fIdist\fR"
.IP \fB--max-peak-dist=\fR\fIdist\fR
.PD
Geoptimiser refines detector geometry by comparing the predicted position of Bragg peaks with the location of detected peak in indexed patterns. This option sets the maximum distance in pixels between the predicted and the observed peaks for the pair
to be included in the optimization process. The default maximum distance is half of the minimum distance between Bragg peaks derived from the data.

.PD 0
.IP \fB--no-stretch\fR
.PD
By default, geoptimiser refines the distance between the detector and the sample. This option turns off this optimization.

.PD 0
.IP \fB--no-cspad\fR
.PD
If a geometry file containing 64 panels (ASICs) is provided by the user, geoptimiser assumes that the detector described by the geometry file is a CSPAD, and performs some sanity-checks on the relative distance and orientation of connected panels. If the checks fail, the geometry optimization is stopped. This option turns off these checks.

.PD 0
.IP \fB--enforce-cspad-layout\fR
.PD
When this option is used, geoptimiser tries to fix the CSPAD layout problems detected by the checks described in the entry for the \fB--no-cspad\fR option. Immediately after performing this operation, geoptimser saves the new detector layout in the output refined geometry file and exits.

.SH AUTHOR
This page was written by Valerio Mariani, Oleksandr Yefanov and Thomas White.

.SH REPORTING BUGS
Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.

.SH COPYRIGHT AND DISCLAIMER
Copyright © 2014-2020 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
.P
geoptimiser, and this manual, are part of CrystFEL.
.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 crystfel_geometry (5)