Page History

...

In this note we describe the PyCSPadImage python-package which is intended to convert the CSPad raw data from HDF5 file to the geometry-corrected 2-D image array. Alternatively, this package evaluates and provide access to the pixel coordinate arrays. This package can be used in a stand-alone python code.

...

• CSPadConfigPars.py - provides access to the CSPad configuration parameters
• CSPadImageProducer.py - receives raw CSPad data 3-D (32, 185, 388) array, uses calibration parameters, produces the 2-D image array
• CalibPars.py - provides access to the CSPad calibration parameters
• CalibParsDefault.py - defines the default CSPad calibration parameters
• CalibParsEvaluated.py - defines the evaluated CSPad parameters such as pixel coordinates
• Examples.py - contains examples of how to get the CSPad 2-D image array with corrected geometry
• Alignment.py - similar to the Examples.py, but is used for alignment purpose, its content is not guaranteed
• GlobalGraphics.py - a set of useful global methods for interactive graphic
• GlobalMethods.py - a set of miscellaneous global modulesmethods
• HDF5Methods.py - a set of global methods to work with HDF5 files

...

• Access to the CSPad geometry calibration parameters are provided by the methods of the classes CalibParsDefault, CalibPars, and CalibPars CalibParsEvaluated. It is assumed that the geometry calibration files, are available (see CSPad alignment) and located in the user-specified directory, otherwise default parameters will be used, which would not represent correctly the specific detector geometry.

• Methods of the class CalibParsEvaluated also evaluate pixel coordinates and provide access to the coordinate arrays of different shapes.

• Methods of the class CSPadImageProducer allows to get the geometry-corrected CSPad image or its part for specified 2x1 or quad.

...

Below we assume that all standard environment variable settings are done (otherwise see Analysis Workbook. Account Setup). In order to copy the PyCSPadImage package from SVN repository and run a simple test one has to use commands:

 
log in to psana<XXXX>
kinit
cd <your-favorite-directory>

newrel ana-current <your-release-directory-name>
cd <your-release-directory-name>
sit_setup
addpkg PyCSPadImage HEAD

cd PyCSPadImage/src/          <==== All source-code files are located here
python Examples.py

External parameters

CSPAD geometry is varying for different detectors, experiments, or even runs. In order to keep track on all these variations LCLS offline has a simple calibration data base, which works as explained in CSPad alignment. In order to get correct CSPAD alignment parameters the pass to the calibration directory should be specified like this:

    path_calib = '/reg/d/psdm/CXI/cxi80410/calib/CsPad::CalibV1/CxiDs1.0:Cspad.0'

If the detector configuration was changed during the experiment, then more than one calibration file should be available for the run ranges with stable configuration.
In order to access correct calibration file the run number should be provided, for example

    runnum = 628

Data for CSPAD image and the detector configuration can be obtained from the HDF5 file, dataset name, and event number for example

    fname  = '/reg/d/psdm/CXI/cxi80410/hdf5/cxi80410-r0628.h5'
    dsname = '/Configure:0000/Run:0000/CalibCycle:0000/CsPad::ElementV2/CxiDs1.0:Cspad.0/data'
    event  = 34

In further description we assume that this set of external parameters is defined.

Import modules

In code snippets below we use definitions of modules and libraries as follows

import numpy              as np

import CalibPars          as calp
import CalibParsEvaluated as cpe
import CSPadConfigPars    as ccp
import CSPadImageProducer as cip

import GlobalGraphics     as gg
import HDF5Methods        as hm

Reconstruction of CSPAD image

Entire code example for image reconstruction is

    calp.calibpars.setCalibParsForPath ( run=runnum, path=path_calib )
    ds1ev = hm.getOneCSPadEventForTest( fname, dsname, event )
    cspadimg = cip.CSPadImageProducer(rotation=0, tiltIsOn=True, mirror=True)
    arr = cspadimg.getCSPadImage( ds1ev )

First, one has to set the correct version of the calibration parameters

    calp.calibpars.setCalibParsForPath ( run=runnum, path=path_calib )

Then, one need in CSPAD dataset for event,

    ds1ev = hm.getOneCSPadEventForTest( fname, dsname, event )

this method returns the CSPAD data as a numpy array for one event, ds1ev.shape=(Nseg, 185, 388), where Nseg?32.

Then, one has to initialize the object of the class CSPadImageProducer

    cspadimg = cip.CSPadImageProducer(rotation=0, tiltIsOn=True, mirror=True)

with optional parameters

• rotation integer from 0 to 3 parameters for CSPAD orientation as 90*rotation degree.
• tiltIsOn = True or False - to account or not the tiny tilt angle of 2x1 sections.
• mirror = True or False - to mirror reflect or not the image.

Finally the method

    arr = cspadimg.getCSPadImage( ds1ev )

returns the 2-d numpy array with CSPAD image, which can be plotted using for example matplotlib.

CSPAD pixel coordinate arrays

CSPAD pixel coordinate arrays can be evaluated/returned in two different shapes:

1. for entire CSPAD with shape=(4,8,185,388)
2. for data-driven shape=(Nseg,185,388), where Nseg?32 if some quads/segments are missing in data.

To get pixel coordinate arrays shaped for entire CSPAD use code:

    calp.calibpars.setCalibParsForPath ( run=runnum, path=path_calib )
    cpe.cpeval.evaluateCSPadPixCoordinates (rotation=0)
    xpix, ypix = cpe.cpeval.getCSPadPixCoordinates_pix()

where xpix and ypix are the coordinate (in pixels) arrays with shape = (4,8,185,388).
Method xpix_um, ypix_um = cpe.cpeval.getCSPadPixCoordinates_um() returns pixel coordinates in micrometer.

To get CSPAD pixel coordinate arrays shaped as in data use code:

    calp.calibpars.setCalibParsForPath ( run=runnum, path=path_calib )
    cpe.cpeval.evaluateCSPadPixCoordinatesShapedAsData(fname,dsname,rotation=0)
    xpix, ypix = cpe.cpeval.getCSPadPixCoordinatesShapedAsData_pix()

where xpix and ypix are the coordinate (in pixels) arrays with shape = (Nseg,185,388).
Note that the fname and dsname need to be specified in order to get configuration of the data array.
Method xpix_um, ypix_um = cpe.cpeval.getCSPadPixCoordinatesShapedAsData_um() returns pixel coordinates in micrometer.

The coordinate arrays extracted for both shapes are tested in module Examples.py by the methods
example_of_image_built_from_pix_coordinate_array_shaped_as_data() and
example_of_image_built_from_pix_coordinate_array_for_entire_cspad(),
where images are reconstructed through the pixel coordinate arrays in
cpe.cpeval.getTestImageShapedAsData(ds1ev) and
cpe.cpeval.getTestImageForEntireArray(ds1ev), respectively.

Image AddedImage Added

Example

Module Examples.py demonstrates how to use the PyCSPadImage package. The essential part of the example can be presented as:

 
import sys
import os
import CalibPars          as calp
import CSPadConfigPars    as ccp
import CSPadImageProducer as cip
import GlobalGraphics     as gg # For test purpose in main only
import HDF5Methods        as hm # For test purpose in main only
#----------------------------------------------
def main_example_xpp() :

    print 'Start test in main_example_xpp()'

    path_calib = '/reg/d/psdm/xpp/xpp47712/calib/CsPad::CalibV1/XppGon.0:Cspad.0'
    fname      = '/reg/d/psdm/xpp/xpp47712/hdf5/xpp47712-r0043.h5'
    dsname     = '/Configure:0000/Run:0000/CalibCycle:0000/CsPad::ElementV2/XppGon.0:Cspad.0/data'
    event      = 0

    print 'Load calibration parameters from', path_calib 
    calp.calibpars.setCalibParsForPath ( run  = 1, path = path_calib )

    print 'Get raw CSPad event %d from file %s \ndataset %s' % (event, fname, dsname)
    ds1ev = hm.getOneCSPadEventForTest( fname, dsname, event )
    print 'ds1ev.shape = ',ds1ev.shape

    print 'Make the CSPad image from raw array'
    cspadimg = cip.CSPadImageProducer()
    arr = cspadimg.getImageArrayForCSPadElement( ds1ev )

    print 'Plot CSPad image'
    gg.plotImage(arr,range=(0,2000),figsize=(11.6,10))
    gg.move(200,100)
    gg.plotSpectrum(arr,range=(0,2000))
    gg.move(50,50)
    print 'To EXIT the test click on "x" in the top-right corner of each plot window.'
    gg.show()

...

First, all necessary modules need to be imported:

 
import CalibPars          as calp
import CSPadConfigPars    as ccp
import CSPadImageProducer as cip
import GlobalGraphics     as gg # For test purpose in main only
import HDF5Methods        as hm # For test purpose in main only

Then, the path to the calibration data types, the HDF5 data file name, and the dataset name in HDF5 structure need to be defined:

 
    path_calib = '/reg/d/psdm/xpp/xpp47712/calib/CsPad::CalibV1/XppGon.0:Cspad.0'
    fname      = '/reg/d/psdm/xpp/xpp47712/hdf5/xpp47712-r0043.h5'
    dsname     = '/Configure:0000/Run:0000/CalibCycle:0000/CsPad::ElementV2/XppGon.0:Cspad.0/data'

...

Then, calibration parameters need to be loaded:

 
    calp.calibpars.setCalibParsForPath ( run  = 1, path = path_calib )

...

Then, the raw CSPad dataset needs to be extracted:

 
    ds1ev = hm.getOneCSPadEventForTest( fname, dsname, event )

...

Finally the 2-D image array can be obtained

 
    cspadimg = cip.CSPadImageProducer()
    arr = cspadimg.getImageArrayForCSPadElement( ds1ev )

and used, for example for plotting

 
    gg.plotImage(arr,range=(0,2000),figsize=(11.6,10))
    gg.plotSpectrum(arr,range=(0,2000))
    gg.show()

...