Merge branch 'cherry-pick-4b02c5e4' into 'main'

Merge branch 'update_doc_for_tomotools_training' into '1.1'

See merge request !292

doc/development/create_your_own_sequence.rst

+How to define your own sequence to build an NXtomo
+==================================================
+
+Design
+""""""
+
+The conversion process is done as follow:
+
+.. image:: img/nxtomomill_design_1.png
+
+The first step this can be done two ways
+
+.. image:: img/nxtomomill_design_2.png
+
+Until now we were only using the title to deduce the acquisition and the type of frames of each Bliss entry.
+
+But the `FRAME_TYPE_SECTION` allow us to ignore those titles and define manually the sequence of the acquisition.
+
+
+Coming back to the `FRAME_TYPE_SECTION` section
+
+`FRAME_TYPE_SECTION` section
+''''''''''''''''''''''''''''
+
+If this section is fill then the `ENTRIES_AND_TITLES_SECTION` will be ignored. Those are mutually exclusive sections.
+
+From it we can define `data_scans` that allow us to define a sequence of scan defining an acquisition using [url](https://fr.wikipedia.org/wiki/Uniform_Resource_Locator). Like:
+
+.. code-block:: text
+
+    data_scans = (
+        (frame_type=projections, entry=silx:///path/to/file?/path/to/scan/node,),
+        (frame_type=projections, entry=/path_relative_to_file),
+    )
+
+Here we will create one acquisition from `silx:///path/to/file?/path/to/scan/node` to be used as a set of projections and `/path_relative_to_file` as a set of projections to.
+
+.. note::
+    
+    Url can be relative to different file
+
+.. warning::
+
+    The created acquisition will follow the provided order
+
+
+Example: create an NXtomo using the `data_scans` field
+""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Using the configuration file
+''''''''''''''''''''''''''''
+
+You can find a file `conversion_using_data_scans.cfg` in the `solution` folder that create an acquisition using `data_scans`:
+
+
+.. image:: img/nxtomomill_example_data_scans.png
+
+
+It can be executed by calling:
+
+.. code-block:: bash
+
+    nxtomomill h52nx --config conversion_using_data_scans.cfg
+
+Using the python API
+''''''''''''''''''''
+
+.. code-block:: python
+
+    from nxtomomill.converter import from_h5_to_nx
+    from nxtomomill.io.config import TomoHDF5Config
+    from nxtomomill.io.framegroup import FrameGroup
+    from silx.io.url import DataUrl
+
+    input_file_path = "bambou_hercules_0001.h5"
+
+    configuration = TomoHDF5Config()
+    configuration.input_file = input_file_path
+    configuration.output_file = "bambou_hercules_0001.nx"
+    configuration.data_frame_grps = (
+        FrameGroup(
+            url=DataUrl(
+                file_path=input_file_path,
+                data_path="1.1",
+                scheme="silx",
+            ),
+            frame_type="initialization",
+        ),
+        FrameGroup(
+            url=DataUrl(
+                file_path=input_file_path,
+                data_path="2.1",
+                scheme="silx",
+            ),
+            frame_type="darks",
+        ),
+        FrameGroup(
+            url=DataUrl(
+                file_path=input_file_path,
+                data_path="3.1",
+                scheme="silx",
+            ),
+            frame_type="flats",
+        ),
+        FrameGroup(
+            url=DataUrl(
+                file_path=input_file_path,
+                data_path="4.1",
+                scheme="silx",
+            ),
+            frame_type="projections",
+        ),            
+    )
+
+    res = from_h5_to_nx(configuration=configuration)
+
+.. note::
+
+    you will see another way to create an NXtomo from scratch that could be another alternative.

doc/development/index.rst

@@ -6,3 +6,4 @@ Development
    
    changelog.rst
    design/index.rst
+   create_your_own_sequence.rst

doc/tutorials/h52nx.rst

@@ -249,3 +249,8 @@ If it exist then it will be picked by *nxtomomill h52nx* instead of the ``data``
 .. hint::
 
    You can find `here a script casting a dataset to another type <https://gitlab.esrf.fr/tomotools/scripts/-/blob/master/cast_detector_dataset.py>`_
+
+
+.. hint::
+
+   Consult section on :ref:`handling_h52nx_issues` in case of troubles.

doc/userguide/user_corner.rst → doc/userguide/batch_processing.rst

-User corner
-===========
-
 Batch processing
-****************
+================
 
 It can be convenient to convert several file in a row. Here are two small examples around h52nx that can be reused for other nxtomomill applications.
 

doc/userguide/handling_h52nx_issues.rst

+.. _handling_h52nx_issues:
+
+How to handle `h52nx` conversion issues
+=======================================
+
+This section present ways to go around some potential issues during conversion from bliss-scan to NXtomo like:
+
+* some bliss entry is skipped / unrecognized
+* some mandatory information are missing
+* specify some field values
+* provide a `h52nx` configuration file to tomwer
+
+
+Some bliss entry is skipped / unrecognized
+""""""""""""""""""""""""""""""""""""""""""
+
+Currently the deduction of a bliss scan type (dark, flat, projection...) is done by:
+
+* looking at the 'technique' group (image_key dataset)
+* else look at the title. Title mapping is defined in settings.py file of nxtomomill.
+
+If the titles have a specific naming convention then you can provide updated information to one of the following:
+
+* modify it from the settings.py file (if this is a local installation
+* provide different name to be used
+        
+    * from the CLI
+    * from a configuration file (see later)
+    * from the python API
+
+.. hint::
+
+    You can 'ignore' the bliss 'technique' dataset (aka bliss tomo config) by using a configuration and turning the `ignore_bliss_tomo_config` to True
+
+From the CLI without a configuration file
+'''''''''''''''''''''''''''''''''''''''''
+
+If you look at the help you can see how to redefine title names.
+
+.. code-block::
+
+    nxtomomill h52nx --help
+
+        --init_titles: mark the beginning of a Bliss sequence (eq acquisition). Use for example to retrieve energy.
+        --dark_titles: specify that this Bliss entry is relative to dark field
+        --flat_titles: specify that this Bliss entry is relative to flat field
+        --proj_titles: specify that this Bliss entry is relative to projection
+        --align_titles: specify that this Bliss entry is relative to alignment (some time called 'return')
+        --init_zserie_titles, --init_pcotomo_titles same as init-titles but dedicated to zseries and pcotomo (behavior of NXtomo creation is a bit different)
+
+
+From the CLI with the configuration file
+''''''''''''''''''''''''''''''''''''''''
+
+The same information can be provided to `ENTRIES_AND_TITLES_SECTION` section
+
+
+.. image:: img/handling_h52nx_issues/nxtomomill_config_titles_section.png
+
+
+From the python API
+'''''''''''''''''''
+
+you can also provide this information to the `TomoHDF5Config` class like:
+
+.. code-block:: python
+
+    configuration = TomoHDF5Config()
+    configuration.init_titles = ("mytomo:basic", "mytomo:fullturn")
+
+
+Some mandatory information are missing
+""""""""""""""""""""""""""""""""""""""
+
+From the CLI without a configuration file
+'''''''''''''''''''''''''''''''''''''''''
+
+There is a limited number of information that the user can provide manually like energy or pixel size. Those can be provided from the set-params option like:
+
+In this case you can provide it from the --set-params option from the CLI like:
+
+nxtomomill h52nx ... --set-params energy 0.5
+
+.. warning::
+    
+    the `--set-params` option should always be put at the end of the command. Because it can take a full list of sub-options 
+
+From the CLI with a configuration file
+''''''''''''''''''''''''''''''''''''''
+
+You can also provide this information to the configuration file under the `EXTRA_PARAMS_SECTION` section like:
+
+.. image:: img/handling_h52nx_issues/nxtomomill_configuration_file_extra_params.png
+
+
+From the python API
+'''''''''''''''''''
+
+Or provide this from a python script when defining the configuration
+
+.. code-block:: python
+
+    configuration = TomoHDF5Config()
+    configuration.param_already_defined = {
+        "energy_kev": 19.2,
+    }
+
+
+Specifying field values
+"""""""""""""""""""""""
+
+For specific fields ("detector name", "translation_x", "translation_y", "translation_z", and "rotation"), we attempt to extract this information from the 'technique' dataset. If the data is not available there, we revert to the generic behavior.
+
+Generic behavior
+''''''''''''''''
+The generic behavior involves searching for each field in a set of predefined locations or paths. If the dataset's structure matches the expected format, the field value is retrieved from the corresponding location.
+
+Customizing locations
+'''''''''''''''''''''
+
+You can customize these locations (similar to titles) using the following methods:
+* `settings.py file <https://gitlab.esrf.fr/tomotools/nxtomomill/-/blob/master/nxtomomill/settings.py>`_: modify this file to change the default locations parsed.
+* command line options.
+* `h52nx` configuration file: overwrite the locations from a configuration file.
+
+From the CLI without a configuration file
+'''''''''''''''''''''''''''''''''''''''''
+
+For the CLI we can get them using ̀`nxtomomill h52nx --help` again:
+
+* `--x_trans_keys`: x translation key in bliss HDF5 file.
+* `--y_trans_keys`: y translation key in bliss HDF5 file.
+* `--z_trans_keys`: z translation key in bliss HDF5 file.
+* `--sample-detector-distance`: sample detector distance.
+* `--valid_camera_names`: Valid NXDetector dataset name to be considered. If None will try to deduce the NXdetector from attributes and shape of the dataset
+* `--rot_angle_keys`: Valid dataset name for rotation angle. If None, look name from "technique/scan/motor"
+* `--acq_expo_time_keys`: acquisition exposure time in bliss HDF5 file.
+* `--x_pixel_size_key` x pixel size key in bliss HDF5 file.
+* `--y_pixel_size_key` y pixel size key in bliss HDF5 file.
+
+From the CLI with a configuration file
+''''''''''''''''''''''''''''''''''''''
+
+the same field are available on the `KEYS_SECTION` of the configuration file.
+
+.. image:: img/handling_h52nx_issues/nxtomomill_config_keys_section.png
+
+dataset discovery is done as follow:
+
+* converter will first look at `positioner` group to resolve key then at `root` group aka bliss entry*. Collect is done by a look like code:
+
+.. code-block:: python
+
+    for parse_group in (positioner, root_aka_bliss_entry):
+    # first step: look for existing dataset with expected number of elmt
+    for key_checked in parse_group:
+        if find_dataset_with_expected_nb_elment:
+            return it
+    # second step: look for existing dataset and adapt it if not enought elmt
+    for key_checked in parse_group:
+        if find_dataset:
+        return it
+    return None    

doc/userguide/index.rst

@@ -5,5 +5,6 @@ User Guide
    :maxdepth: 1
 
    installation.rst
-   user_corner.rst
-   settings.rst
+   batch_processing.rst
+   settings.rst
\ No newline at end of file
+   handling_h52nx_issues.rst
\ No newline at end of file