
Loading a project
=================

Once X-SOCS is started, you can either create a `New project`_ or open an `Existing project`_.

A project contains the information about a single K-map acquisition (scans and calibration) and stores data reduction results (conversion to QSpace and fit).

.. _create_project:

New project
+++++++++++

.. |create_icon| image:: ../../src/xsocs/resources/gui/icons/create_project.png

To start the project creation wizard, click on the |create_icon| button in the toolbar or select the **Create project** item in the **File** menu.

Create project
--------------

The first page will ask you for the folder path into which the new project will be created.

.. warning::
    There can be only one project per folder!
    A confirmation dialog will pop up if a project file is already present in the chosen directory.

The next page gives you the choice between:

#. |bliss_icon| **Load Bliss data (HDF5)** to import data in HDF5 format acquired with Bliss.

   Select the HDF5 `master` file of the dataset (the file that contains links to all the scans).
   Once the project is created, the `Project summary`_ page is displayed.

#. **Load X-Socs data (HDF5)** to import K-map data already in HDF5 format.

   To load data that has already been merged, select the `master` file of the merged data (the file that contains links to all entries).
   Once the project is created, the `Project summary`_ page is displayed.

#. **Import SPEC data** to import K-map data SPEC and EDF files from the ESRF ID01 beamline.

   X-SOCS will merge the SPEC file and the EDF images into HDF5 files.

   See `Merge ID01 SPEC and EDF to HDF5`_ below.


.. |bliss_icon| image:: ../../src/xsocs/resources/gui/icons/bliss.png
   :width: 32px

Merge ID01 SPEC and EDF to HDF5
--------------------------------

When using X-SOCS to merge data the following window is displayed:

.. _figure_merge_window:
.. figure:: img/merge_window.png
   :align: center

   Merge window

Fill the `Input Parameters`_ before starting the parsing by clicking on the **Parse file** button.
The time it takes depends on the size of the spec file.
It can take more than a minute if the file is very large.

.. warning::

    At the moment X-SOCS merges all scans found in the SPEC file that have a matching EDF file.
    So you will have to make sure that ONLY the images corresponding to the scans you want to merge are in the **Img. dir** folder.

Once SPEC parsing is done, the other parameter fields are enabled:

- `SPEC + EDF Parameters`_ for parsing results and scan/EDF file matching.
- `Image ROI Parameters`_ for only saving a region of interest from the input images.
- `Acq. Parameters`_ for calibration information.
  In case this information is available in the SPEC file, those parameters are already set.
- `Output Parameters`_.

After filling those fields, click on the **Merge** button at the bottom of the window to start the file conversion.

.. note::

    When the merge starts you should see the progress of some files changing from 0 to 2%, and then not change for a while.
    This is because the merge process is opening the EDF files to get the number of frames and this can take a while.

Once the conversion to HDF5 is done, the `Project summary`_ page is displayed.

Input Parameters
................

.. list-table::
   :widths: 1 4
   :header-rows: 1

   * - Parameter
     - Description
   * - ``Spec file``
     - Path to the log (usually a \*.spec file) generated by the K-map command.
       It contains the information of all the scans.
   * - ``Img. dir``
     - Path to the folder containing the EDF files that must be merged into the HDF5 file.
   * - ``Version``
     - Allows you to select predefined values for the nextNr padding and offset.
       For data acquired before March 2016 you will probably want to set the version to 0, otherwise version 1 should be OK.
   * - ``nextNr padding``
     - Controls the padding applied to the nextNr value found in the spec file which is used to generated the EDF file name.
        This setting is only used for data acquired before mid 2016.
   * - ``nextNr offset``
     - Controls the offset applied to the nextNr value.

SPEC + EDF Parameters
.....................

.. list-table::
   :widths: 1 4
   :header-rows: 1

   * - Parameter
     - Description
   * - ``Matched scans``
     - Scans found in the spec file which have a matching EDF file.
   * - ``Other scans``
     - Scans found in the spec file which do NOT have a matching EDF file.

Image ROI Parameters
....................

.. list-table::
   :widths: 1 4
   :header-rows: 1

   * - Parameter
     - Description
   * - ``Offset``
     - ``Row`` and ``Column`` in detector pixels coordinate of the ROI corner.
   * - ``Size``
     - ``Width`` and ``Height`` in pixels of the ROI.

Acq. Parameters
...............

.. list-table::
   :widths: 1 4
   :header-rows: 1

   * - Parameter
     - Description
   * - ``Beam energy``
     - Energy of the beam, in eV
   * - ``Direct beam``
     - Position in pixels of the direct beam on the detector
   * - ``Ch. per deg.``
     - Channels per degree

Output Parameters
.................

.. list-table::
   :widths: 1 4
   :header-rows: 1

   * - Parameter
     - Description
   * - ``Prefix``
     - String that will be prepended to all the hdf5 file names.
       Default is the "prefix" value found in the SPEC file
   * - ``Output directory``
     - Folder into which the merged files will be written

Project summary
---------------

Once data has been imported, X-SOCS sums the intensity of all images.
This can take quite some time depending on the size of the acquired data.

.. _figure_open_dialog:
.. figure:: img/open_dialog.png
   :align: center
   :width: 50%

   Open project summary page

Finally, the project summary page (:numref:`figure_open_dialog`) provides the description of the scans from which the project has been created.
Click on **Finish** to display the newly created project in the :ref:`project tree window <project_tree>` and the :ref:`intensity view <intensity_view>`.


.. _load_project:

Existing project
++++++++++++++++

.. |open_icon| image:: img/open_icon.png

To load an existing project click on the |open_icon| button in the toolbar or select the **Open project** item in the **File** menu.
This opens a file dialog which allows you to browse to and select a ``xsocs.prj`` file.

Once the project file is selected, the project summary page (:numref:`figure_open_dialog`) provides the description of the scans contained in the project.

From there you can either cancel, or click on **Finish** to load the selected project in the :ref:`project tree window <project_tree>` and the :ref:`intensity view <intensity_view>`.
