Skip to content

Commit

Permalink
Merge pull request #287 from European-XFEL/documentation
Browse files Browse the repository at this point in the history 
[DOC] Update documentation
  • Loading branch information
@zhujun98
zhujun98 authored Oct 29, 2020
2 parents e3fff48 + e964f2e commit 976bce5
Show file tree
Hide file tree
Showing 6 changed files with 79 additions and 25 deletions.
70 changes: 53 additions & 17 deletions docs/image_tool.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ IMAGE TOOL
The *ImageTool* window is the second control window which provides various image-related
information and controls.

.. image:: images/ImageTool.png
.. image:: images/image_tool.jpg
:width: 800

Image control
Expand All @@ -26,13 +26,28 @@ Image control
| ``Update automatically`` | Automatically update the current displayed image in the |
| | *ImageTool* window. |
+----------------------------+--------------------------------------------------------------------+
| ``Moving average`` | Apply moving average to the image data. It affects both the |
| | individual images in a train and the averaged image, as well as |
| | the subsequent analysis. If a new window size is smaller than |
| | the old one, the moving average calculation will start from the |
| | scratch. |
+----------------------------+--------------------------------------------------------------------+
| ``Auto level`` | Update the detector images (not only in the *ImageTool* window, |
| | but also in other plot windows) by automatically selecting levels |
| | based on the maximum and minimum values in the data. |
+----------------------------+--------------------------------------------------------------------+
| ``Save image`` | Save the current image to file. Please also see ImageFileFormat_ |
+----------------------------+--------------------------------------------------------------------+

.. Warning::

The moving average here is not calculated by nanmean_, which means that if a pixel of the image
in a certain pulse is *NaN*, the moving average of that pixel will be *NaN* for that pulse.

.. Warning::

Please be aware that there is another moving average setup in the :ref:`Global setup` in the
main GUI.

Mask panel
""""""""""
Expand Down Expand Up @@ -173,6 +188,8 @@ Gain / offset

.. _nanmean: https://docs.scipy.org/doc/numpy/reference/generated/numpy.nanmean.html

.. image:: images/gain_offset_correction.jpg

Apply pixel-wised gain and offset correction, where

.. math::
Expand All @@ -183,26 +200,45 @@ Users can record a "dark run" whenever data is available. The dark run consists
of trains. The moving average of the each "dark pulse" in the train will be calculated,
which will then be used to apply dark subtraction to image data pulse-by-pulse.

+----------------------------+--------------------------------------------------------------------+
| Input | Description |
+============================+====================================================================+
| ``Gain correction`` | Check to activate gain correction. |
+----------------------------+--------------------------------------------------------------------+
| ``Offset correction`` | Check to activate offset correction. |
+----------------------------+--------------------------------------------------------------------+
| ``Use dark as offset`` | Check to use recorded dark images as offset. The already loaded |
| | offset constants will be ignored. |
+----------------------------+--------------------------------------------------------------------+
| ``Record dark`` | Start and stop dark run recording. |
+----------------------------+--------------------------------------------------------------------+
| ``Remove dark`` | Remove the recorded dark run. |
+----------------------------+--------------------------------------------------------------------+

.. Note::
+-----------------------------+--------------------------------------------------------------------+
| Input | Description |
+=============================+====================================================================+
| ``Apply gain correction`` | Check to activate gain correction. |
+-----------------------------+--------------------------------------------------------------------+
| ``Apply offset correction`` | Check to activate offset correction. Since version 1.10, a |
| | variation of offset correction has been introduced: |
| | |
| | - ``+intra-dark``: |
| | |
| | After the pulse-by-pulse offset correction, every other pulse |
| | will be subtracted by the following one starting from the |
| | first pulse. For instance, imaging a pulse train consisting of |
| | four pulses *ABAB*, the extra intra-dark correction will |
| | result in a train *A'BA'B*, where *A'* = *A* - *B*. |
| | Then one can make use of the pulse slicer in the |
| | :ref:`Data source tree` to remove the intra-dark pulses. |
+-----------------------------+--------------------------------------------------------------------+
| ``Use dark as offset`` | Check to use recorded dark images as offset. The already loaded |
| | offset constants will be ignored. |
+-----------------------------+--------------------------------------------------------------------+
| ``Record dark`` | Start and stop dark run recording. |
+-----------------------------+--------------------------------------------------------------------+
| ``Remove dark`` | Remove the recorded dark run. |
+-----------------------------+--------------------------------------------------------------------+

.. Warning::

The moving average here is not calculated by nanmean_, which means that if a pixel of the image
in a certain pulse is *NaN*, the moving average of that pixel will be *NaN* for that pulse.

.. Note::

Some detectors have its own special treatment for gain/offset correction:

- DSSC:

Due to the readout issue, pixels with value 0 will be converted to 256.


Reference image
---------------
Expand Down
Binary file removed docs/images/ImageTool.png
View file
Binary file not shown.
Binary file added docs/images/gain_offset_correction.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/image_tool.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
10 changes: 4 additions & 6 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,11 +66,9 @@ accelerate your analysis, please feel free to dig into the code and ask question
# Now you should be able to load the newly created kernel on max-jhub.
Install C++ API of **EXtra-foam** only
--------------------------------------
Install C++ API only
--------------------

.. code-block:: bash
.. _foamalgo: https://github.com/zhujun98/foamalgo

$ mkdir build && cd build
$ cmake -DFOAM_USE_XSIMD=ON -DCMAKE_INSTALL_PREFIX=/YOUR/INSTALL/PREFIX
$ make && make install
Please check foamalgo_.
24 changes: 22 additions & 2 deletions docs/main_gui.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@


MAIN GUI
========

Expand Down Expand Up @@ -80,6 +82,8 @@ Namely, only one connection should be checked.
| ``Port`` | Port number of the TCP connection. |
+----------------------------+--------------------------------------------------------------------+

.. _Data source tree:

Data source tree
""""""""""""""""

Expand Down Expand Up @@ -137,6 +141,7 @@ online analysis in the hutch, or in the :ref:`File streamer` when you are stream
General analysis
----------------

.. _Global setup:

Global setup
""""""""""""
Expand All @@ -154,14 +159,29 @@ Define analysis parameters used globally.
+----------------------------+--------------------------------------------------------------------+
| ``Moving average window`` | Moving average window size. If the moving average window size is |
| | larger than 1, moving average will be applied to all the |
| | registered analysis types. If the new window size is smaller than |
| | registered analysis types. If a new window size is smaller than |
| | the old one, the moving average calculation will start from the |
| | scratch. |
| | scratch. Currently, this setup will affect the calculations of: |
| | |
| | - Pulse intensity of XGM |
| | - Pulse integral of Digitizer |
| | - Train-resolved (pump/probe) azimuthal integration |
| | - Train-resolved (pump/probe) ROI FOM |
| | - Train-resolved (pump/probe) ROI 1D projection |
| | |
+----------------------------+--------------------------------------------------------------------+
| ``Reset`` | Reset the moving average counts of all registered analysis types. |
+----------------------------+--------------------------------------------------------------------+


.. Warning::

Since version 1.10, another moving average was re-activated in :ref:`Image tool`. If both the
moving averages are set, the result of azimuthal integration, ROI FOM and ROI 1D projection
will be a moving average on top of the moving averaged image! This is due to some historical
reason and it will be fixed in the future.


Pump-probe setup
""""""""""""""""

Expand Down

0 comments on commit 976bce5

Please sign in to comment.