:Author: Jérôme Kieffer
:Date: 27/10/2015
:Keywords: Tutorials
:Target: Scientists

Calibration of a diffraction setup using the Command Line Interface (CLI)
=========================================================================

The files needed for this cookbook can be downloaded on:
http://www.silx.org/pub/pyFAI/cookbook/calibration/
You can download them to practice:

.. code-block:: shell

   $ mkdir calibration
   $ cd calibration
   $ wget http://www.silx.org/pub/pyFAI/cookbook/calibration/LaB6_29.4keV.tif
   $ wget http://www.silx.org/pub/pyFAI/cookbook/calibration/F_K4320T_Cam43_30012013_distorsion.spline
   $ ls
   F_K4320T_Cam43_30012013_distorsion.spline  LaB6_29.4keV.tif


`The associated video is here <http://www.silx.org/pub/calibration/calibration.flv>`_


Review your calibration image
-----------------------------

As viewer, try fabio_viewer from the FabIO package

.. code-block:: shell

   $ fabio_viewer LaB6_29.4keV.tif

.. figure:: fabio_viewer.png
   :align: center
   :alt: image

You may need to pre-process your data, *pyFAI-average* is a tool to perform pixel-wise
transformation.
In this example, the image file was obtained using a "max filter" over 20 frames
with pyFAI-average:

.. code-block:: shell

    $ pyFAI-average -m max -F tif -o LaB6_29.4keV.tif ref_lab6_00??.edf



Get all additional data
-----------------------

 * calibrant used: LaB6 according to the name of the file
 * the energy or the wavelength, 29.4keV according to the name of the file
 * detector geometry: there is a spline file along with the file
 * masks, dark, flat ... are not going to be used to keep things simple.

Start pyFAI-calib
-----------------

Use the man page (or --help) to see all options, or go to the :ref:`manpage` section.

Here we just provide the energy, the detector disortion file and the calibrant
options in addition to the image file.

.. code-block:: shell

   $ pyFAI-calib -e 29.4 -s F_K4320T_Cam43_30012013_distorsion.spline -c LaB6 LaB6_29.4keV.tif
   FixedParameters(['wavelength'])
   ERROR:pyFAI.peak_picker:ControlPoint.load: No such file LaB6_29.4keV.npt
   INFO:pyFAI.massif:Image size is (2048, 2048)
   INFO:pyFAI.massif:Binning size is [2, 2]
   INFO:pyFAI.massif:Labeling found 7272 massifs.
   INFO:pyFAI.massif:Labeling found 7272 massifs.
   INFO:root:Please select rings on the diffraction image. In parenthesis, some modified shortcuts for single button mouse (Apple):
    * Right-click (click+n):         try an auto find for a ring
    * Right-click + Ctrl (click+b):  create new group with one point
    * Right-click + Shift (click+v): add one point to current group
    * Right-click + m (click+m):     find more points for current group
    * Center-click or (click+d):     erase current group
    * Center-click + 1 or (click+1): erase closest point from current group
   Please press enter when you are happy with your selection


Pick peaks
----------

To perform the calibration one needs to create control points and assign them to rings.

 * Right click on a few (5) points in the inner-most ring which has the index
   number #0
 * Increase the counter on the top right to change the ring number and pick a few
   more points on the corresponding ring (again with right click).

.. figure:: pyFAI-calib_1.png
   :align: center
   :alt: image


Review the group of peaks
-------------------------

Press Enter in the terminal to do so...
and check the ring assignment

Once done with all groups, the position of the expected rings is overlaid to the
diffraction image. You may need to unzoom to view them !

.. code-block:: shell

 Now fill in the ring number. Ring number starts at 0, like point-groups.
 Point group # a (4 points)  (1315.9,1090.1)   [default=0] Ring#
 Point group # b (5 points)  (1302.0, 926.0)   [default=0] Ring#
 Point group # c (2 points)  (1085.3,1268.1)   [default=0] Ring#
 Point group # d (2 points)  ( 850.1,1083.3)   [default=0] Ring#
 Point group # e (5 points)  ( 965.1, 825.7)   [default=0] Ring#
 Point group # f (4 points)  ( 898.2,1315.9)   [default=1] Ring#
 Point group # g (2 points)  (1244.6, 733.6)   [default=1] Ring#
 Point group # h (2 points)  (1350.1, 821.9)   [default=1] Ring#
 Optimization terminated successfully.    (Exit mode 0)

.. figure:: pyFAI-calib_2.png
   :align: center
   :alt: image


Acquire some more control points
--------------------------------

 * Use *recalib* to extract a new set of control points, specify the number of rings, first a few of them then more
 * You may want to free/fix/bound some parameter then *refine* again

.. code-block:: shell

 Fixed: wavelength
 Modify parameters (or ? for help)?   recalib 6
 [...]
 Fixed: wavelength
 Modify parameters (or ? for help)?   recalib 15
 [...]
 Fixed: wavelength
 Modify parameters (or ? for help)?   recalib 25

.. figure:: pyFAI-calib_3.png
   :align: center
   :alt: image


Visualize the integrated patterns
---------------------------------

 * integrate to view the integrated pattern
 * then extract a few extra rings ...
 * the geometry is displayed on the screen, and saved automatically in the poni-file

.. code-block:: shell

    Fixed: wavelength
    Modify parameters (or ? for help)?   integrate


.. figure:: pyFAI-calib_4.png
   :align: center
   :alt: image


Quit
----

.. code-block:: shell

    Fixed: wavelength
    Modify parameters (or ? for help)?   quit
    $

.. code-block:: shell

    ls
    F_K4320T_Cam43_30012013_distorsion.spline  LaB6_29.4keV.npt   LaB6_29.4keV.tif
    LaB6_29.4keV.azim                          LaB6_29.4keV.poni  LaB6_29.4keV.xy


All different geometries have been saved into the LaB6_29.4keV.poni file and
can directly be used with *pyFAI-integrate*.
All control points are saved into LaB6_29.4keV.npt.

**Final notes:**
In this case the calibration is far from being good and it is likely the
distortion file applied is not the proper one according to many the waves on the 2D
integration pattern.
If one flips up-down the spline file prior to the calibration, the residual error
is twice lower but the goes far beyond this cookbook.
Here is the diffraction pattern from a properly calibrated setup:

.. figure:: pyFAI-calib_5.png
   :align: center
   :alt: image

.. code-block:: python

   from pyFAI.spline import Spline
   s = Spline("F_K4320T_Cam43_30012013_distorsion.spline")
   ud = s.flipud()
   ud.write("flipud.spline")

