path: root/doc/man/crystfel_geometry.5

.\"
.\" Geometry man page
.\"
.\" Copyright © 2012 Thomas White <taw@physics.org>
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"

.TH CRYSTFEL\_GEOMETRY 5

.SH CRYSTFEL DETECTOR GEOMETRY AND BEAM DESCRIPTION FILES

See below for information about CrystFEL's beam 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, \fBpattern_sim\fR and \fBpowder_plot\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 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.
.PP
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:

.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 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
.br
; any name as long as it doesn't start with "bad" (see below).
.br
; The range of pixels in the HDF5 file which correspond to a panel are given:
.br
panel0/min_fs = 0
.br
panel0/min_ss = 0
.br
panel0/max_fs = 193
.br
panel0/max_ss = 184

; The number of detector intensity units (ADU) which will arise from one eV:
.br
panel0/adu_per_eV = 0.01

; The readout direction (x, y or 0).  If more than three peaks are found in
.br
; the same readout region, they are all discarded.  This helps to avoid
.br
; problems due to streaks appearing along the readout direction.
.br
; If the badrow direction is '-', then the culling described above will not
.br
; be performed for this panel.
.br
panel0/badrow_direction = -

; The resolution (in pixels per metre) for this panel
.br
panel0/res = 9090.91

; The characteristic peak separation in pixels.  The peak detection will assume
.br
; that genuine peaks are separated by at least this amount.
.br
panel0/peak_sep = 6.0

; The camera length (in metres) for this panel
.br
; You can also specify the HDF path to a scalar floating point value containing
.br
; the camera length in millimetres.
.br
panel0/clen = /LCLS/detectorPosition

; For this panel, the fast and slow scan directions correspond to the given
.br
; directions in the lab coordinate system described above, measured in pixels.
.br
panel0/fs = +y
.br
panel0/ss = -x

; The corner of this panel, defined as the first point in the panel to appear in
.br
; the HDF5 file, is now given a position in the lab coordinate system.
.br
; Note that "first point in the panel" is a conceptual simplification.  We refer
.br
; to that corner, and to the very corner of the pixel - NOT, for example, to the
.br
; centre of the first pixel to appear.
.br
panel0/corner_x = 429.39
.br
panel0/corner_y = -17.30

; You can suppress indexing for this panel if required, by setting "no_index" to
.br
; "true" or "1".
.br
panel0/no_index = 0

; You can also specify bad regions.  Peaks with centroid locations within such
.br
; a region will not be integrated nor indexed.  Bad regions are specified in
.br
; pixel units, but in the lab coordinate system (i.e. "y" points at the ceiling,
.br
; "z" is the beam direction and "x" completes the right-handed system).
.br
badregionA/min_x = -20.0
.br
badregionA/max_x = +20.0
.br
badregionA/min_y = -100.0
.br
badregionA/max_y = +100.0

; If you have a bad pixel mask, you can include it in the HDF5 file as an
.br
; unsigned 16-bit integer array of the same size as the data.  You need to
.br
; give its path within each HDF5 file, and two bitmasks.  The pixel is
.br
; considered good if all of the bits which are set in "mask_good" are set, AND
.br
; if none of the bits which are set in "mask_bad" are set.
.br
mask = /processing/hitfinder/masks
.br
mask_good = 0x27
.br
mask_bad = 0x00

; Any of the per-panel values can be given without a panel prefix, for example:
.br
peak_sep = 6.0
.br
; in which case the value will be used for all *subsequent* panels.

.PP
See the "examples" folder for some examples (look at the ones ending in .geom).

.SH CRYSTFEL BEAM DESCRIPTION FILES
CrystFEL beam description files, usually given with fB--beam=\fR\fIfilename\fR,
describe the beam parameters.  The fields are as follows:

; Number of photons per pulse
.br
beam/fluence = 2.0e11

; Radius of X-ray beam
.br
beam/radius = 1.5e-6

; Photon energy in eV
.br
beam/photon_energy = 2000.0

; Bandwidth: FWHM(wavelength) over wavelength.
.br
; Note: current simulation code just uses a rectangular
.br
;       distribution with this as its (full) width.
.br
beam/bandwidth = 0.001

; Beam divergence (full convergence angle, \fBnot\fR the half-angle) in radians
.br
beam/divergence = 0.001

.SH AUTHOR
This page was written by Thomas White.

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

.SH COPYRIGHT AND DISCLAIMER
Copyright © 2012 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 pattern_sim (1),
.BR indexamajig (1)