Merge pull request #188 from European-XFEL/documentation

Changelog 0.8.3
European-XFEL · May 12, 2020 · ea3e7a9 · ea3e7a9
2 parents 5097da6 + 50fd457
commit ea3e7a9
Show file tree

Hide file tree

Showing 6 changed files with 115 additions and 34 deletions.
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,6 +1,47 @@
 CHANGELOG
 =========
 
+0.8.3 (11 May 2020)
+------------------------
+
+- **Breaking change**
+    - In the terminal, "--n_modules 2" is required to run JungFrauPR with two modules. #41
+
+- **Bug Fix**
+    - Change pixel size of ePix100 from 0.11 mm to 0.05 mm. #189
+
+- **Improvement**
+    - Mask tile/ASIC edges by default. #192
+    - Improve geometry 1M and its unittest. #190
+    - Invert y axis for displayed image. #187
+    - Rename geometry to geometry_1m in C++. #186
+    - Improve tr-XAS analysis in special suite. #163 #183
+    - Improve correlating error message. #182
+    - Improve documentation for special suite. #177
+    - New reset interface in special suite. #170
+    - Regularize names of methods and attributes in special suite. #167
+    - Add new mode, start/end train ID control and progress bar, etc. in FileStreamer. #166
+    - Move definition of meta source from config to SourceCatalog. #165
+    - Use correlated queue in special suite. #164
+    - Improve shape comparing error message in C++. #160
+    - Improve mask image data implementation and interface. #157
+    - Move image assembler into image processor. # 155
+    - Refactor masking code. #149
+    - Implement generic binding for nansum and nanmean. #114
+
+- **New Feature**
+    - Add axis calibration in Gotthard analysis. #179
+    - Implement generalized geometry for multi-module detectors. #175 #196
+    - Implement streaming JungFrauPR data from files. #174
+    - Implement Gotthard pump-probe analysis in special suite. #173 #178
+    - Add ROI histogram in CameraView in special suite. #172
+    - Add ROI control in special suite. #171
+    - Implement XAS-TIM-XMCD in special suite. #162
+    - Implement MultiCameraView in special suite. #147
+    - Implement XAS-TIM in special suite. #146
+    - Implement load and save mask in pixel coordinates. #132 #154 #185 #191 #197
+
+
 0.8.2 (8 April 2020)
 ------------------------
 

diff --git a/docs/image_tool.rst b/docs/image_tool.rst
@@ -28,13 +28,6 @@ Image control
 |                            | but also in other plot windows) by automatically selecting levels  |
 |                            | based on the maximum and minimum values in the data.               |
 +----------------------------+--------------------------------------------------------------------+
-| ``Threshold mask``         | An interval that pixel values outside the interval are set to 0.   |
-|                            | Please distinguish *threshold mask* from clipping_.                |
-+----------------------------+--------------------------------------------------------------------+
-| ``Mask tile edges``        | Mask the edge pixel of each tile. *Only applicable for AGIPD, LPD  |
-|                            | and DSSC if EXtra-foam is selected as the* ``Assembler`` *in*      |
-|                            | :ref:`Geometry`.                                                   |
-+----------------------------+--------------------------------------------------------------------+
 | ``Save image``             | Save the current image to file. Please also see ImageFileFormat_   |
 +----------------------------+--------------------------------------------------------------------+
 
@@ -62,9 +55,14 @@ will also not be overwritten after loading an image mask from file.
 |                            | and DSSC if EXtra-foam is selected as the* ``Assembler`` *in*      |
 |                            | :ref:`Geometry`.                                                   |
 +----------------------------+--------------------------------------------------------------------+
-| ``Draw``                   | Draw mask in a rectangular region.                                 |
+| ``Mask ASIC edges``        | Mask the edge pixel of each ASIC. *Only applicable for JungFrau    |
+|                            | and ePix100.*                                                      |
 +----------------------------+--------------------------------------------------------------------+
-| ``Erase``                  | Erase mask in a rectangular region.                                |
+| ``Draw``                   | Draw mask in a rectangular region. *Only available in the          |
+|                            | Corrected panel.*                                                  |
++----------------------------+--------------------------------------------------------------------+
+| ``Erase``                  | Erase mask in a rectangular region. *Only available in the         |
+|                            | Corrected panel.*                                                  |
 +----------------------------+--------------------------------------------------------------------+
 | ``Remove mask``            | Remove the image mask.                                             |
 +----------------------------+--------------------------------------------------------------------+
@@ -299,31 +297,71 @@ Geometry
 
 .. _EXtra-geom : https://github.com/European-XFEL/EXtra-geom
 
-Geometry is only available for the multi-module detector which requires a geometry file to
-assemble the images from different modules, for example, AGIPD, LPD and DSSC. For details
-about geometries of those detectors, please refer to the
-`documentation <https://extra-geom.readthedocs.io/en/latest/geometry.html>`_.
+Geometry is only available for the detector which requires a geometry to
+assemble the images from different modules, for example, AGIPD, LPD, DSSC as well as
+JungFrau and ePix100 used in a combined way.
+
+For details about geometries of AGIPD, LPD and DSSC,
+please refer to this `documentation <https://extra-geom.readthedocs.io/en/latest/geometry.html>`_.
+It should be noted that the online and offline data format are different. For real-time data received
+from the `ZMQ bridge`, all the 16 modules have been stacked in a single array and the source name
+is usually a Karabo device name. However, for data streamed from files, modules data are distributed in
+different files and each module has a unique source name. For example, DSSC modules at SCS are named as
+`SCS_DET_DSSC1M-1/DET/0CH0:xtdf`, `SCS_DET_DSSC1M-1/DET/1CH0:xtdf`, ..., `SCS_DET_DSSC1M-1/DET/15CH0:xtdf`.
+**EXtra-foam** relies on the "index" (0 - 15) in the source name to find the corresponding module. Accordingly,
+in the :ref:`Data source` tree, one should use `SCS_DET_DSSC1M-1/DET/*CH0:xtdf` as the source name,
+which has a '*' at the location where the module index is expected.
+
+LPD-1M with 16 modules:
 
 .. image:: images/geometry.png
    :width: 640
 
-+----------------------------+--------------------------------------------------------------------+
-| Input                      | Description                                                        |
-+============================+====================================================================+
-| ``Quadrant positions``     | The first pixel of the first module in each quadrant,              |
-|                            | corresponding to data channels 0, 4, 8 and 12.                     |
-+----------------------------+--------------------------------------------------------------------+
-| ``Load geometry file``     | Open a *FileDialog* window to choose a geometry file from the      |
-|                            | local file system.                                                 |
-+----------------------------+--------------------------------------------------------------------+
-| ``Assembler``              | There are two assemblers available in *EXtra-foam*. One is         |
-|                            | EXtra-geom_ implemented in Python and the other is the local C++   |
-|                            | implementation. Indeed, the latter follows the assembling          |
-|                            | methodology implemented in the former but is much faster with      |
-|                            | multi-core processors.                                             |
-+----------------------------+--------------------------------------------------------------------+
-| ``Stack only``             | When the checkbox is checked, the modules will be seamlessly       |
-|                            | stacked together. Unfortunately, it does not mean that this will   |
-|                            | be faster than assembling with a geometry. It simply provides an   |
-|                            | alternative to check the data from different modules.              |
-+----------------------------+--------------------------------------------------------------------+
+**EXtra-foam** implemented a generalized geometry for detectors like JungFrau and ePix100. To allow
+more than one modules, **one must explicitly specify the number of modules in the command line at startup**.
+Similar to AGIPD, LPD and DSSC, the online and offline data format can be different. For real-time data
+received from the `ZMQ bridge`, all the modules could have been stacked in a single array and the source
+name is usually a Karabo device name. However, it also supports data arriving in modules, as data streamed
+from files. Similarly, it relies on the "index" in the source name to find the corresponding module. Different
+from AGIPD, LPD and DSSC, **the module index starts from 1**. For example, JungFrau modules at SPB are
+named as `SPB_IRDA_JNGFR/DET/MODULE_1:daqOutput`, `SPB_IRDA_JNGFR/DET/MODULE_2:daqOutput`, ...,
+`SPB_IRDA_JNGFR/DET/MODULE_8:daqOutput`. Similarly, in the :ref:`Data source` tree, one should use
+`SPB_IRDA_JNGFR/DET/MODULE_*:daqOutput` as the source name.
+
+6-module JungFrau with geometry file in the CFEL format. Module 1 is located on the top-right corner and
+all modules (1, 2, 3, 6, 7, 8) are arranged in closewise order.
+
+.. image:: images/JungFrau_6_module_geometry.jpg
+   :width: 640
+
+2-module ePix100 without geometry file. Module 1 is located on top of module 2.
+
+.. image:: images/ePix100_2_module_geometry.jpg
+   :width: 640
+
++---------------------------------+--------------------------------------------------------------------+
+| Input                           | Description                                                        |
++=================================+====================================================================+
+| ``Quadrant positions``          | The first pixel of the first module in each quadrant,              |
+|                                 | corresponding to data channels 0, 4, 8 and 12. *Only avaible for   |
+|                                 | 1M detectors, i.e. AGIPD, LPD and DSSC, with non-CFEL format       |
+|                                 | geometry file.*                                                    |
++---------------------------------+--------------------------------------------------------------------+
+| ``Module positions``            | The first pixel of each module. *Only available for JungFrau and   |
+|                                 | ePix100 with non-CFEL format geometry file. Not implemented yet*   |
++---------------------------------+--------------------------------------------------------------------+
+| ``Load geometry file``          | Open a *FileDialog* window to choose a geometry file from the      |
+|                                 | local file system. *Ignored if* ``Stack without geometry file``    |
+|                                 | *is checked.*                                                      |
++---------------------------------+--------------------------------------------------------------------+
+| ``Assembler``                   | There are two assemblers available in *EXtra-foam* for AGIPD, LPD  |
+|                                 | and DSSC. One is EXtra-geom_ implemented in Python and the other   |
+|                                 | is the local C++ implementation. Indeed, the latter follows the    |
+|                                 | assembling methodology implemented in the former but is much       |
+|                                 | faster with multi-core processors.                                 |
++---------------------------------+--------------------------------------------------------------------+
+| ``Stack without geometry file`` | When the checkbox is checked, the modules will be seamlessly       |
+|                                 | stacked together. Unfortunately, it does not mean that this will   |
+|                                 | be faster than assembling with a geometry. It simply provides an   |
+|                                 | alternative to check the data from different modules.              |
++---------------------------------+--------------------------------------------------------------------+
diff --git a/docs/images/JungFrau_6_module_geometry.jpg b/docs/images/JungFrau_6_module_geometry.jpg
diff --git a/docs/images/ePix100_2_module_geometry.jpg b/docs/images/ePix100_2_module_geometry.jpg
diff --git a/docs/start.rst b/docs/start.rst
@@ -55,6 +55,8 @@ More info on command line arguments can be obtained as
                             Address of the Redis server
 
 
+For more details about detector modules, please refer to :ref:`Geometry`.
+
 .. note::
     It sometime takes more than a minute to start **EXtra-foam** for the first time! This
     is actually an issue related to the infrastructure and not because

diff --git a/extra_foam/__init__.py b/extra_foam/__init__.py
@@ -37,7 +37,7 @@
 import os
 
 
-__version__ = "0.8.3dev"
+__version__ = "0.8.3"
 
 # root path for storing config and log files
 ROOT_PATH = os.path.join(os.path.expanduser("~"), ".EXtra-foam")