pyFAI calibration GUI operations for InstantPlot

To accurately display raw detector images and nominal scattering plots in InstantPlot, the appropriate mask and PONI files must be provided for each detector. The steps below describe how to generate these required files after collecting detector images from calibration standards.

InstantPlot documentation is here.

Running the pyFAI Calibration GUI

1. If you are using the analysis computer at the beamline (not the station computer running SPEC), you may skip this step. If you are working on your own device, connect to lnx201 using NoMachine, open a terminal window, and then connect to a CLASSE Compute Farm node by following the steps below.
   1. Run qrsh -q interactive.q -pe sge_pe 32 for a parallel processing node (recommended); or
   2. Run qrsh -q chess_fmb.q for FMB node (usually reserved for automated data processing).
      
      
2. Enter the "saxswaxs-viewer" environment:
   1. On the analysis computer: open a terminal window and run activate_instantplot.
   2. On a compute farm node: run source /nfs/chess/sw/miniconda3_msnc/bin/activate; conda activate saxswaxs-viewer.
      
      
3. Run pyFAI-calib2 to open the pyFAI Calibration GUI. It will open to the “Experiment settings” screen.
   
   
   
   
4. In the Experimental settings section:
   1. Enter beam energy in keV (typically 9.7 keV). The corresponding wavelength will be entered automatically.
   2. Choose the calibrant (typically AgBh or LaB6). In the example shown below, AgBh was selected for calibrating the PIL5 detector for SAXS. For calibrating PIL9 and PIL11 with LaB6, refer to abbreviated instructions here.
      
      
      
      
5. In the Detector section:
   1. Enter the detector information per guideline below. In the example shown below, we are continuing with the calibration steps for the PIL5 detector.
      1. For the PIL5 detector (typically SAXS): Dectris > Pilatus 300k
      2. For the PIL9 and PIL11 detectors (typically WAXS): Dectris > Pilatus 200k
         
         
         
         
6. In the Acquisition section:
   1. Select the ellipsis (horizontal three dots) beside the "Image file" field.
   2. Navigate to the data file (typically in /nfs/chess/raw/current/id3b/[btr-id]/Cal/[detector image folder]). Ensure that the “PIL#” string in the filename to the detector you intend to calibrate. The example shown below is a raw image of AgBh collected on the PIL5 detector, with the sample-to-detector distance of approximately 1.4 m.
   3. Once the selected image is displayed, click on the vertical orientation icon in the top toolbar, and choose "Orient Y-axis downward", as shown below. Confirm that the pixel number along the vertical axis increases from top to bottom when "Orient Y-axis downward" is selected.
      
      
      
      
7. Click Next to navigate to Mask screen. The stripe between the detector panels should automatically be masked in magenta.
   1. In the Threshold section: Enter 0 for Min.
   2. Click "Mast below" button. This should remove any dead pixels that may be present in the detector.
      
      
      
      
8. In the Draw tools section:
   1. Click the Polygon Selection tool. Select points on the image to define the area to be masked. Use the mouse wheel to zoom in and out. You may right‑click at any time and select "Zoom back" to return to the default view.
   2. You may select areas outside the detector image (i.e., the gray area) when defining a region. The final mask will be automatically cropped to the detector panel area.
   3. Click the starting point to complete the polygon. The selected area will be highlighted in magenta. If you are not satisfied with the selection, click the Back Arrow icon under found in the Mask section to undo the selection.
   4. Continue selecting additional areas to be masked.
      
      
   5. Once all areas to be masked have been defined, click the Save icon under the Mask section to create a mask file. Save the mask as a .tif file.
      1. The recommended save location is: /nfs/chess/aux/reduced_data/cycles/current/id3b/[BTR-ID]/setup.
      2. Use the following naming convention for the mask file: PILx_mask_mm.dd.yyyy.tif, where x = 5, 9 or 11.
         
         
9. Click Next to navigate to the Peak picking screen.
   1. In the Picked rings section, click the green Plus button to prevent the program from automatically assigning a ring number. The ring number field should no longer be greyed out.
   2. Select the ring number (typically start with 1).
   3. Use one of the peak-picking icons to mark the ring corresponding to the selected ring number:
      • The first icon: Selects peaks with reasonable intensities around the full ring, without being constrained by the masked stripe positions.
      • The second icon: Selects peaks with reasonable intensities along an arc defined by the masked stripe positions.
      • The third icon: Allows you to select peaks individually by hand.
   4. Press the left arrow to undo the most recent selection. Use the eraser icon to remove a group of picked peaks.
   5. If applicable, repeat the steps above for other rings.
      
      
      
      
10. Click Next to navigate to the Geometry Fitting screen and review the fitting results. If anything appears incorrect, return to the Peak Picking screen and verify that there are no outlier points or misnumbered rings. When possible, ensure that peaks on rings near the edges of the detector have been selected.
    
    • For PIL11 only: The detector is above the beam and rotated by 90 degrees on its side. In the Geometry section, set rot3 to 1.57 rad, then click "Fit" to rerun the fitting routine.
      
      
      
      
11. Click Next to navigate to the Cake & integration screen to see the cake and integrated plots
    • In the Integration parameters section: the typical parameter to select is Scattering vector in inverse Angstroms.
    • On the top toolbar, click the Log icon to view the plots in log scale.
      
      
      
      
12. If the results are acceptable, click “Save as PONI file...” to save a .poni file for the detector.
    1. The recommended save location is: /nfs/chess/aux/reduced_data/cycles/current/id3b/[BTR-ID]/setup.
    2. Use the following naming convention for the PONI file: [calibrant]_PILx_mm.dd.yyyy.poni, where x = 5, 9 or 11.

The resulting PONI file produced by this example is shown below:

# Nota: C-Order, 1 refers to the Y axis, 2 to the X axis
# Calibration done at Mon Apr 6 16:55:17 2026
poni_version: 2
Detector: Pilatus300k
Detector_config: {}
Distance: 1.4058486842876698
Poni1: 0.05760824668012185
Poni2: 0.037950532481965046
Rot1: -0.00037257379261019727
Rot2: 0.00017862283084029942
Rot3: 3.089241885211403e-12
Wavelength: 1.2781876127134048e-10

Official documentation

Official documentation for the GUI is here: pyFAI-calib2