hologradpy.error_metrics
========================

.. py:module:: hologradpy.error_metrics

.. autoapi-nested-parse::

   This module contains functions to characterise light potentials.



Functions
---------

.. autoapisummary::

   hologradpy.error_metrics.normalize
   hologradpy.error_metrics.fidelity
   hologradpy.error_metrics.rms
   hologradpy.error_metrics.rms_phase
   hologradpy.error_metrics.psnr
   hologradpy.error_metrics.eff


Module Contents
---------------

.. py:function:: normalize(img, roi, thres=0.5)

   Normalises an image by dividing it by the pixel sum in a region of interest. Only pixels brighter than
   thres * max(roi * img) are taken into account.

   :param img: Input image.
   :param roi: Binary mask containing region of interest.
   :param thres: Pixel value threshold (see above).
   :return: Normalised image.


.. py:function:: fidelity(signal, a_tar, phi_tar, a_out, phi_out)

   Calculate fidelity between two electric fields in a region of interest (signal region).

   :param signal: Binary mask containing the region of interest.
   :param a_tar: Target amplitude pattern.
   :param phi_tar: Target phase pattern.
   :param a_out: Amplitude of light potential.
   :param phi_out: Phase of light potential.
   :return: Fidelity.


.. py:function:: rms(signal, i_target, i_out, frac=0.5)

   Calculate normalised root-mean-squared error between two images inside a region of interest. Only pixels which are brighter
   than ``frac * max(i_target_norm)`` are taken into account, where ``i_target_norm`` is the normalised target
   intensity pattern.

   :param signal: Binary mask containing region of interest (signal region).
   :param i_target: Target intensity pattern.
   :param i_out: Intensity pattern of light potential.
   :param frac: Threshold as explained above.
   :return: Normalised rms error.


.. py:function:: rms_phase(phi)

   Calculates the root-mean-squared error of an image.

   :param phi: Phase pattern.
   :return: Root-mean-squared error.


.. py:function:: psnr(signal, i_target, i_out)

   Calculates the peak signal-to-noise ratio between two images in a region of interest according to
   https://doi.org/10.1364/OE.24.006249.

   :param signal: Binary mask containing region of interest (signal region).
   :param i_target: Target intensity pattern.
   :param i_out: Intensity pattern of light potential.
   :return: Peak signal-to-noise ratio [dB].


.. py:function:: eff(signal, i_out)

   Calculates the predicted efficiency of a light potential by dividing the pixel sum in the signal region by
   the pixel sum in the entire pattern.

   :param signal: Binary mask containing the signal region.
   :param i_out: Intensity pattern of the light potential.
   :return: Efficiency.