.. _sec-intro:

Introduction
============

In this documentation, you will find step-by-step instructions on setting up
the package, detailed descriptions of its components, and all necessary
information to fully leverage its functionalities.

Given the abundance of image processing software available, it is essential to
clearly define the motivations behind :mod:`piva`, as well as its capabilities
and limitations. This will provide users with a comprehensive overview of the
package, highlighting the aspects that may be beneficial for their research
or work.


What is :mod:`piva`
-------------------
:mod:`piva` is a GUI application based on the :mod:`PyQt5` and
:mod:`pyqtgraph` toolkits, designed for the interactive and intuitive
exploration of large image-like datasets. While it can generally display any
multidimensional data, most of its functionalities are tailored for users
performing Angle-Resolved Photoemission Spectroscopy (ARPES) experiments.


Graphical Interface and Interactive Viewers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The showcase video presented below offers a demonstration of the GUI's layout
and overall user experience, while also highlighting its core functionalities
and key features in action.

.. raw:: html

   <div style="text-align: center;">
       <video width="600" controls>
           <source src="_static/showcase.mp4" type="video/mp4">
           Your browser does not support the video tag.
       </video>
   </div>
   <br><br><br>


The package allows for live investigation of various datasets individually, as
well as linking separate datasets for simultaneous browsing. Interactive
sliders enable the display of multidimensional data across all available
directions (see :ref:`DataViewers <sec-viewers>`). In addition to numerous
image processing methods, PIVA can represent ARPES images in momentum space
and apply corrections specific to the experimental conditions under which the
data were acquired.

Several utilities are particularly useful during the experimental phase, such
as automated methods for finding the highest symmetry points, azimuthal
rotation, and autogenerated experimental notebooks implemented for
:ref:`various beamlines <sec-dl-list>` at synchrotron sources worldwide.

The :ref:`Fitters <sec-fitters>` and :ref:`PlotTool <sec-plottool>`
applications offer additional functionalities for detailed analysis and
personalized representation of acquired results.


Data Format Standardization
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Moreover, :mod:`piva` translates raw data into a standardized
:ref:`Dataset <sec-dataset>` object, addressing the issue of diverse data
formats within the ARPES community. The :ref:`Dataset <sec-dataset>` can be
easily used outside of :mod:`piva` by simply importing the
:ref:`data_loaders.py <sec-data-loaders-file>` module.


Analysis Tools
~~~~~~~~~~~~~~

Unlike other experimental techniques, discrepancies in ARPES results between
different physical systems necessitate the implementation of unique analysis
methods for nearly every investigated system. To address this, :mod:`piva`
includes a generic toolkit for handling photoemission results that can be
further tailored to meet specific user needs. Additionally, it offers
straightforward tools for exporting loaded datasets and opening them with a
``jupyter-lab`` notebook for more sophisticated analysis requiring hands-on
scripting.


Custom Add-ons
~~~~~~~~~~~~~~

The architecture of the :mod:`piva` package is designed with modularity in
mind, providing users with a convenient platform for implementing custom data
loaders and other plugins. Detailed descriptions and examples of
configuring new modules can be found in this documentation.

----

In summary, :mod:`piva` provides an efficient, intuitive GUI application for
examining multiple datasets and includes a platform for importing data into a
convenient format. It is based on ``python`` and ``jupyter-lab`` environments,
allowing users to easily conduct detailed analyses of their acquired data.