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.config.h52nxtomo_models 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_scans = (
        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.