Grain Plot
===========

.. image:: icons/grainplot.png

Widget to compute, display and export moments of the grain. 

This widget can display the following grain maps:

* **Center of mass (COM)**: Shows the map of COM for every motor. The center of mass looks at the intensity as a function of a motor position, using the intensity values of the images as a statistical weight
* **Full width half maximum (FWHM)**: Same as COM but with the standard deviation
* **Skewness, Kurtosis**: third and fourth-order computed `standardized moments <https://en.wikipedia.org/wiki/Standardized_moment>`_

There is also a dedicate tab to the mosaicity and the orientation distribution for 2D and 3D scans. 

.. hint:: Have a look an the :ref:`Mosaicity tab tutorial` below for more explanations about mosaicity tab.


Mosaicity tab tutorial
======================

This tutorial is dedicated to the mosaicity tab.

The Mosaicity tab is organized around two complementary plots:

- **Mosaicity** A 2D view of the center‑of‑mass (CoM)
- **Orentation distribution** 2D heat-map. Obtained from weighted 2D histogram based on Center of Mass of the first and the second dimension and ZSum of the detector data as the weight.

.. note:: Several new features are available since 4.1 version

Plots Common Toolbars.
---------------------------------

.. image:: img/grainplot/toolbar.png


**Interactive toolbar**

First toolbar contains three tools **zoom**, **pan** and **flashlight**.

This toolbar is available from both the mosaicity (left) and the Orientation Distribution (right) plots.

- **zoom** and **pan** are casual actions available in any plot widget.
- **flashlight** is a new interactive action that lets the user defining a rectangular Region Of Interest (ROI) that follows the mouse cursor.
  * ROI can be resized by maintaining left button pressed. 
  * ROI center and size is shown below the selection.
  The **flashlight** selection from the right plot illuminate the corresponding range of values in the left plot.
  The same mapping is done from the left plot to the right plot.

.. image:: img/grainplot/flashlight.gif

**Common utils toolbar**

Second toolbar ; accessible from both plots ; contains four tools relative to data saving, export and aspect ratio.

- **copy**: Take a screenshot of the plot and place it on the system clipboard.
- **save**: Save the plot. Different format available.

    .. note:: this is different from the **export maps** button because this only save the content of one plot.

- **print** : Similar to save.

    .. warning:: An exception occurs with last version of silx dependencies ! (Need to be fixed)
      
- **aspect ratio**: Enable or disable the Keep aspect ratio option, which forces the plot’s X‑ and Y‑axes to maintain a fixed proportional scaling (e.g., 1 : 1).

**Orientation distribution configuration toolbar**

Third toolbar is specific to the right plot.

The **Orientation distribution** data is a heat-map (2D - histogram) of the **Center of Mass** values.

.. note:: This view is only available for dataset at least 2D.

Contours are drawn to reveal area of the distribution with the highest intensity value.


- **Normalization** Data colormap and contours normalization (**linear** or **log**).
- **Axis** allow to select horizontal and vertical axis representation.
  Default are the motor coordinates. Options are `move origin to 0` (Substract min motor coordinate) and `centered` (Substract (min + max) / 2).

- **Color key tool** This tool allow user to adjust the blend between data intensity layer and HSV key layer.

  If **checked**, Orientation Distribution only shows a HSV layer relative to X and Y dimension.
  
  To determine intensity of an area of the plot you can use the contours. 

  Area with zero intensity values have a lower brightness. You can play with the slider of the tool to change this brightness.

  .. image:: img/grainplot/tune_key.gif

  If **unchecked**, Orientation Distribution show the two layers: ``Data intensity`` as an alpha layer and ``HSV key`` as a background layer.

  The visibility of the `Data intensity` layer can be tuned from the slider.

  .. image:: img/grainplot/tune_data.gif

- **Contour tool** This tool allow user to configure contours. Can be unchecked (No contours) and a slider can be use to define the number of contours.

- **Median Filter** Whether a media filter should be applied on the data. Note that contours are always base on a median filter of the data (no matter this option).


Threshold and range
-------------------

.. image:: img/grainplot/threshold_and_range.png

**Threshold** spinbox allow user to discard values above a certain threshold in the ZSum. 
These values will be shown as black in the mosaicity and less darker in the orientation distribution plot (Depending on **Color key tool** tuning).

The two **range sliders** allow to fix manually a axis range in the orientation distribution. 
Values outside this range in the mosaicity plot are shown with a dark grey color.