This note describes imaging detectors' hierarchical geometry model which is implemented in LCLS offline software since release ana-0.13.1.
Analysis of LCLS data from imaging experiments requires precise coordinate definition of the photon detection spot. In pixel array detectors photon energy usually deposited in a single pixel and hence pixel location precision should be comparable or better than its size, about 100μm. Apparently, calibration of the detector and entire experimental setup geometry with such a precision is a challenging task for many reasons;
To take into account this structure we may consider a variable length series of hierarchical objects like sensor -> sub-detector -> detector -> setup, where lower-level child object(s) is(are) embedded in its higher-level parent object. Nodes/objects of this hierarchical model form the tree which is convenient for navigation and recursion algorithms. Each child object location and orientation can be described in the parent frame. Tree-like structure can be kept in form of table saved in and retrieved from file. The last feature is practically useful for calibration purpose. All constants for detector/experiment geometry description can be saved in a single file. Relevant parts of the hierarchical table can be calibrated and updated whenever new geometry information is available, for example from optical measurement or dedicated runs with images of bright diffraction rings or Bragg peaks.
This note contains description of the implemented hierarchical geometry model, coordinate transformation algorithms, tabulation of the hierarchical objects and calibration file format, description of software interface in C++ and Python, details of calibration, etc.
In this section we list tentative objects and associated coordinate frames which may be involved in typical LCLS experimental setup and explain how they can be inscribed in the hierarchical model.
On the very top level of hierarchical structure there should be a global coordinate frame associated with entire experimental setup. All other setup components are defined relative to the global coordinate frame. In diffraction experiments origin of the coordinate frame is usually associated with IP. Choice of axes directions depends on experimental preferences. In some of LCLS experiments Cartesian coordinate system of the setup is defined by the three mutually orthogonal right-hand-indexed axes with origin in the IP:
as shown in the plot:
FIG. 1: Tentative coordinate frame of experimental setup.
In this frame photon-hit pixel coordinates (x, y, z) can be easily transformed to the photon diffraction angle θ,
On the very bottom level of hierarchy structure there should be self-sufficient components of the detector - sensors a.k.a. tiles, segments, pixel arrays/matrix etc. We assume that
For example, CSPAD 2x1 tile pixel geometry is schematically shown below
FIG. 2: Coordinate frame of CSPAD 2x1 sensor.
The CSPAD 2x1 tile has
The pixel index and coordinates in the tile memory block of size 185×388 can be evaluated as
y = k * row + y_offset
x = f(column)
where y coordinate is proportional to the row index, while x coordinate needs to be tabulated as a function of the column index due to the gap in the tile central columns braking matrix uniformity. Detector data record consists of consecutive tile-memory blocks, in accordance with numeration adopted in DAQ. For effective memory management, some of the tile-blocks may be missing due to current detector configuration. Available configuration of the detector tile-blocks should be marked in a configuratiomn bit-mask word in positional order (bit position from lower to higher is associated with the tile number in DAQ).
Full description of a composite detector (beside top and bottom level hierarchical objects) needs in definition of intermediate objects with their arbitrary location and orientation. Any geometry object coordinate system may have a translation and rotation with respect to the parent object, which can be defined by the 3 vectors in the setup frame as shown in Figure
FIG. 3: Child object position in the parent coordinate frame.
where
Third unit vector ez is assumed to be right-hand triplet component, 
. Components of these three unit vectors form the rotation matrix
where index “j” enumerates unit vectors in the object coordinate frame, and index “i” is an object unit vector component in the parent frame (ex.: eYz is a Y component of the vector ez). Within this definition 3-d pixel coordinate “c” in the object frame can be transformed to the parent coordinate frame “C” using equation
Ci=Rij·cj + Pi.
For practical reason we parametrize rotation matrix Rij in terms of Cardan’s angles R(α, β, γ). We assume that the 3-d rotation matrix R(α, β, γ) is a product of three 2-d rotations
R(α, β, γ) = Rx(α) · Ry(β) · Rz(γ),
around appropriate axes, defined as
This transformation algorithm is implemented in class PSCalib.GeometryObject as discussed below.
As an example we show how composite CXI-like CSPAD detector with moving quads can be inscribed in the hierarchical geometry model and how geometry parameters can be retrieved in each level.
FIG. 4: Example: 2x1 sensors’ positions in the CSPAD quad coordinate frame.
FIG. 5: Example: quads’ positions in the CSPAD detector coordinate frame.
FIG. 6: Example: detector position in the experiment coordinate frame with origin at IP.
Precise pixel coordinates can be retrieved in a few steps using
In this section we describe a procedure of optical measurements, its potential problem, and method to fix it.
Optical measurements with microscope give the most precise information about sensors’ positions in the parent structure. Estimated accuracy of measurements is σRMS ∼ 10μm in x-y plane, and about the same amount in z. Optical measurements provide 3-d coordinates of 4 corners for all tiles in the (sub-)detector in some arbitrary microscope plane which coincides with detector imaging array (tiles) plane within precision of installation.
Tile <#>
Point <#> <X[um]> <Y[um]> <Z[um]>
Measurements with microscope are not automated. Results are manually saved in the metrology file, which may have non-intentional typos. If the number of typos is small they can be tracked down in the quality check and fixed. Quality check of optical measurement may test for each tile:
Report table about all deviations is generated by the python script processing the metrology file. Large deviations exceeding standard precision >3σ(RMS) indicate on problem with measurement. A few corrections are usually applied for each metrology file.
In this section we discuss requirements to the geometry alignment parameters and describe chosen file format.
In the calibration file/table we need to save links between parent and child objects. Tree-like structure assumes that each parental object may have many children and each child object has only one parent. It is easier for each object to keep information about its parent and object location and orientation parameters with respect to the parent, as implemented in class PSCalib.GeometryObject. One fixed length record per object is convenient to keep this information in memory and file as a table. Scan over all objects allows to retrieve all hierarchical links and use them further in recursive processing. This algorithm is implemented in the class PSCalib.GeometryAccess.
Composite detector usually consists of similar sub-detectors. In particular, CSPAD consists of four quads, quad consists of eight 2x1 sensors. Sub-detectors of the same type should be treated by the same code. To distinguish between sub-detectors we introduce two variable for each object, name and index. For example, CSPAD quads have an arbitrary symbolic name “QUAD” and indexes from 0 to 3, their children have a symbolic name “CSPAD2X1V1” and indexes from 0 to 7. The name of low level objects, “CSPAD2X1V1”, is used in the factory method PSCalib.SegGeometryStore.Create in order to instatiate associated PSCalib.SegGeometry object. This and all other names are also used to set child-parent relations between objects.
In most cases we deal with planar detectors and we assume that:
in this plane, as explained below. These assumptions are not necessary for all algorithms. But, in many cases it may be convenient to use small angle approximation or ignore angular misalignment for image mapping between tiles and 2-d image array. For this reason in calibration file we split all angles for rotation and tilt in order to have direct access to the designed and corrected values, respectively.
From metrology file we may evaluate the tile center coordinates as an average over 4 corners. Tilt angles are defined as projected angles of the tile sides on relevant planes. Each angle is evaluated as an averaged angle for 2 sides. The tile location and orientation in the parent frame can be saved in the table record where
| Parent name | Parent index | Object name | Object index | X0[µm] | Y0[µm] | Y0[µm] | Rotation Z [°] | Rotation Y [°] | Rotation X[°] | Tilt Z[°] | Tilt Y[°] | Tilt X[°] |
|---|
Parent name - name and version of the parent object; all translation and rotation pars are defined w.r.t. parent Cartesian frame
First four fields are intended to set parent-to-child relations between geometry objects. Python script in CalibManager reads data from the metrology file and generates the geometry file consisting of records in this format. Thus tabulated geometry parameters allow to
Result of multiple geometry transformations depends on their order. In coordinate reconstruction algorithms we use particular order for rotations and translations.
CalibManager under the tabs Geometry / Metrology has a GUI which processes metrology file and generates the calibration file like shown below for CXI-like CSPAD with moving quads (see example of file: geometry/0-end.data)
All lines started with hash “#” are comments, which are also accessible through the program interface as a dictionary. XPP-like CSPAD with all sensors attached to the same plate is measured as a single detector. Its content part omits quads
Content of CSPAD2x2 geometry file consist of data for two sensors only:
If the detector pixel coordinates should be presented relative to IP or other setup component, have an offset or flipped around axis one more line must to be added, for example
#file: pyimgalgos/src/GeometryObject.py
def rotation(X, Y, C, S) :
Xrot = X*C - Y*S
Yrot = Y*C + X*S
return Xrot, Yrot
class GeometryObject :
...
def transform_geo_coord_arrays(self, X, Y, Z) :
...
# define Cx, Cy, Cz, Sx, Sy, Sz - cosines and sines of rotation + tilt angles
...
X1, Y1 = rotation(X, Y, Cz, Sz)
Z2, X2 = rotation(Z, X1, Cy, Sy)
Y3, Z3 = rotation(Y1, Z2, Cx, Sx)
Zt = Z3 + self.z0
Yt = Y3 + self.y0
Xt = X2 + self.x0
return Xt, Yt, Zt |
Pixel coordinates in the detector should be accessed by the method like
xarr, yarr, zarr = get_pixel_coords()
For example, Python interface for CSPAD
from pyimgalgos.GeometryAccess import GeometryAccess
...
fname_geometry='<path>/geometry/0-end.data'
geometry = GeometryAccess(fname_geometry)
X,Y,Z = geometry.get_pixel_coords() |
will return X,Y,Z arrays of the shape [4,8,185,388], or similar for CSPAD quad, one has to show the top object for coordinate arrays, say it is 'QUAD:V1' with index 1:
geometry = GeometryAccess(fname_geometry)
X,Y,Z = geometry.get_pixel_coords('QUAD:V1', 1) |
return X,Y,Z arrays of the shape [8,185,388].
Interface description is available in doxygen
The same package and file names as in C++ but with file name extension .py:
Pixel detector geometry generic parameterization presented in this note is implemented in LCLS analysis software releases since ana-0.13.N. Both C++ and Python interfaces are available.
Reference to doxygen documentation of classes