Merge remote-tracking branch 'upstream/master' into 0.18

doc/source/usage/cookbook/calib-gui/index.rst

@@ -12,7 +12,7 @@ Here is the *cookbook* which will explain you how to calibrate the setup of a
 diffraction experiment within five minutes.
 No advanced feature are presented.
 
-The graphical tool for geometry calibration is called **pyFAI-calib2**,
+The graphical tool for geometry calibration is called ``pyFAI-calib2``,
 just open a terminal and type its name plus return to startup the application
 which looks like this:
 
@@ -31,7 +31,7 @@ The windows is divided in 3 vertical tiles (panels) containing:
 * 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.
+  finishes with the ``Next`` button to switch to the next task.
 
 We will now describe shortly every task by following a simple example.
 
@@ -44,7 +44,7 @@ the calibrant and the detector used.
 
 You have to provide the calibration image which is then displayed in the cental 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>`_
+`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.
 
@@ -58,7 +58,7 @@ Mask and dark-current files can be provided in a similar way.
    :alt: Experiment setup
 
 Finally set the ``energy`` of the experiment (or the ``wavelength``) and select the
-reference compound used in the the ``calibrant`` drop-down menu.
+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.
 
@@ -135,6 +135,26 @@ 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.
+
+It uses the internal modelization of pyFAI: each pixels of the redector is
+spacialized. It textures them using the mask and the calibration image.
+
+The beam is displayed a red cylinder smaller than the detector pixel size.
+It hit 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 number or select different peaks.
 
@@ -146,7 +166,6 @@ like in this figure:
    :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.
@@ -166,6 +185,43 @@ The radial unit can be customized and the images/curves can be saved.
 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
 ----------