:Author: Jérôme Kieffer
:Date: 02/04/2020
:Keywords: Tutorials
:Target: Scientists

.. _cookbook_calibration_gui:

Calibration of a diffraction setup using the Graphical User Interface (GUI)
===========================================================================

Here is the *cookbook* which will explain you how to calibrate the setup of a
diffraction experiment within five minutes.
No advanced features are presented.

Video
-----

.. raw:: html

	<center>
	<video width="640" height="360" controls>
		<source src="http://www.silx.org/pub/pyFAI/video/Calibration_15mn.mp4" type="video/mp4">
		This 15mn tutorial presents the usage of pyFAI-calib2
	</video>
	</center>


The graphical tool for geometry calibration is called ``pyFAI-calib2``,
just open a terminal and type its name plus return to start up the application
which looks like this:

.. code-block:: shell

   $ pyFAI-calib2

.. figure:: 0_startup.png
   :align: center
   :alt: startup of calib2

The windows is divided in 3 vertical tiles (panels) containing:

* On the left side, a list of tasks to be performed: setting-up, masking,
  peak-picking, ring-fitting and caking.
* A large central panel to display the image. Note the zoom, pan and colormap
  buttons on the top of the central panel.
* The right side panel contains a set of tools dedicated to each task and
  finishes with the ``Next`` button to switch to the next task.

We will now describe shortly every task by following a simple example.

Experiment settings
-------------------

This task contains all entries relative to the experiment setup.
It is the place where you can enter the energy of the beam (or the wavelength),
the calibrant and the detector used.

You have to provide the calibration image which is then displayed in the central panel.
For example the file used in this cookbook can be downloaded from this link:
`Eiger4M_Al2O3_13.45keV.edf <http://www.silx.org/pub/pyFAI/cookbook/calibration/Eiger4M_Al2O3_13.45keV.edf>`_.
Click on the ``...`` on the right of ``Image file`` to open the file-browser
which will allow you selecting the file you just downloaded.

Finally, select the type of detector, here the image has been acquired using an Eiger4M manufactured by Dectris.
Once the detector is selected, its shape is overlaid to the image allowing a
direct validation of the detector size.
Mask and dark-current files can be provided in a similar way.

.. figure:: 1_experiment.png
   :align: center
   :alt: Experiment setup
   
Finally set the ``energy`` of the experiment (or the ``wavelength``) and select the
reference compound used in the ``calibrant`` drop-down menu.
For this image, the beam was at 13.45 keV and the calibrant was corundum, which
is referenced ``alpha_Al2O3`` as in the figure.

You are now ready to define the mask, click on the ``Next>`` button.

Defining the mask
-----------------

The mask defines the list of pixels which are considered invalid.
It is displayed in green by default.
There are 3 drawing tools:

* rectangular selection
* polygonal selection (click on the first point to finish edition)
* pencil selection

In addition, the mask can often be setup easily using one or two thresholds, or
by discarding infinite values or `NaN`.
Finally, masks can be inverted, saved and restored.

In our test-image, the Eiger detector has flagged overflow pixel with a very high value.
Discarding pixel values above 65000 removes automatically all invalid pixels.
To remove pixels with some shadow, like the beam stop, the easiest is to use the
polygon tool (click on the square of the first point to finish the edition)
as in the figure below:


.. figure:: 2_mask.png
   :align: center
   :alt: Draw a mask on the image
   
Once you are done, click on the ``Next>`` button to pick some rings.

Peak-picking and ring assignment
--------------------------------

The geometry calibration is performed in pyFAI by a least-square fitting of peak
positions on ring number.

This task consists in selecting groups of peaks by left-clicking on them in the
image, and to assign the proper ring number to each group.

You will need to pick at least two rings.
Selecting the inner-most (2 or 3) rings is advised as they are the most intense
and misassignment is unlikely.

.. figure:: 3_picking.png
   :align: center
   :alt: Select peaks and assign them to rings 


Double check the ring-number assignment in the right panel.
In the case of a difficult image (discontinuous rings, spotty signal, ...),
changing the picking mode can help.

*Nota:* this GUI tool uses 1-based numbers, unlike the command line tool which starts at 0.

We will skip the ``Recalibrate`` tool for now and go directly to the
geometry fitting by clicking on the ``Next>`` button.

Geometry fitting
----------------

When arriving on this task, the geometry is immediately fitted and you can see
the values of the 3 translation and 3 rotation.

.. figure:: 4_geometry.png
   :align: center
   :alt: Geometry optimization 


Values can be modified and fixed by clicking on the lock.
Click on the ``Fit`` button to re-fit the geometry.

Results may be displayed in various units by right-clicking on the unit.

3D rendering
------------

As soon as a geometry is computed, it can be displayed as a 3D rendering.
This view is available from the fitting screen, as a dedicated dialog box.

It uses the internal modelization of pyFAI: each pixel of the detector is
spatialized. It textures them using the mask and the calibration image.

The beam is displayed a red cylinder smaller than the detector pixel size.
It hits a symbol of the sample on one side, and according to the geometry can hit
the detector on the other side.

.. figure:: 4_3d_view.png
   :align: center
   :alt: 3D rendering of the experience

Automatic peak-extraction
-------------------------

Depending on the result, one may want to come back on the ``Peak picking`` task to
re-assign the ring numbers or select different peaks.

Or if it looks good, extracting many rings will allow for a more reliable fit.
For this, set the ``number of rings`` in the ``Recalibrate`` part and click ``Extract``,
like in this figure:

.. figure:: 3_extract.png
   :align: center
   :alt: Extract many rings 

The selected peaks with their ring assignment can be exported at this stage,
by clicking on the ``floppy disk`` icon.
This is used in the case of a goniometer calibration.

Cake and Integration
--------------------

The last task displays the 1D and 2D integrated image with the ring position
overlaid to validate the quality of the calibration.

The radial unit can be customized and the images/curves can be saved.

.. figure:: 5_cake.png
   :align: center
   :alt: Azimuthal integration 

Last but not least, do not forget to save the geometry as a PONI-file for
subsequent integrations.

Feedback from integrated result to improve the mask
---------------------------------------------------

The 1D integration result can be used to notice misplaced peaks coming from hot
pixels.

.. figure:: improve_mask_1.png
   :align: center
   :alt: Azimuthal integration 

Once this hot pixel is located on the 1D spectrum, use the 2D view to localize
it, then mark it using the right mouse button.

.. figure:: improve_mask_2.png
   :align: center
   :alt: Azimuthal integration 

Back to the mask task.

.. figure:: improve_mask_3.png
   :align: center
   :alt: Azimuthal integration 

Zoom onto the mark.

.. figure:: improve_mask_4.png
   :align: center
   :alt: Azimuthal integration 

You can mask the defective area using one of the mask tools.

.. figure:: improve_mask_5.png
   :align: center
   :alt: Azimuthal integration 

Back to the integration task, the result will be updated.

Conclusion
----------

This tutorial explained the 5 steps needed to perform the calibration of the
detector position prior to any diffraction experiment on a synchrotron.

Advanced video tutorial
-----------------------

This tutorial was given at the **Hercules** courses in 2020, the data files used are here:
`Calibration_Al2O3.h5 <http://www.silx.org/pub/pyFAI/pyFAI_UM_2020/data_ID13/Calibration_Al2O3.h5>`_ and
`kevlar.h5 <http://www.silx.org/pub/pyFAI/pyFAI_UM_2020/data_ID13/kevlar.h5>`_. 
This 65mn tutorial presents also *silx view*, *pyFAI-average* and *pyFAI-integrate*.


.. raw:: html

	<center>
	<video width="640" height="360" controls>
		<source src="http://www.silx.org/pub/pyFAI/video/pyFAI_example_ID13.mp4" type="video/mp4">
		65 mn tutorial with preprocessing, calibration and integration.
	</video>
	</center>