.. _dg_visualiser_tutorial:

.. include:: define_roles.rst


===========================
Interactive Image Filtering
===========================

The :py:mod:`temul.signal_processing` module allows one to filter images with a
double Gaussian (band-pass) filter. Apart from the base functions, it can be
done interactively with the
:py:func:`temul.signal_processing.visualise_dg_filter` function. In this
tutorial, we will see how to use the function on experimental data.


Load the Experimental Image
---------------------------

Here we load an example experimental atomic resolution image stored in the
TEMUL package.

.. code-block:: python

    >>> import temul.api as tml
    >>> from temul.example_data import load_Se_implanted_MoS2_data
    >>> image = load_Se_implanted_MoS2_data()



Interactively Filter the Experimental Image
-------------------------------------------

Run the :py:func:`temul.signal_processing.visualise_dg_filter` function.
There are lots of other parameters too for customisation.

.. code-block:: python

    >>> tml.visualise_dg_filter(image)

.. image:: tutorial_images/dg_filter_tutorial/dg_visualiser.gif
    :scale: 50 %

As we can see, an interactive window appears, showing the FFT ("FFT Widget")
of the image with the positions of the inner and outer Gaussian full width
at half maximums (FWHMs). The inital FWHMs can be changed with the
:python:`d_inner` and :python:`d_outer`
parameters (limits can also be changed).

To change the two FWHMs interactively
just use the sliders at the bottom of the window. Reset can be used to reset the
FWHMs to their initial value, and Filter will display the "Convolution" of the FFT
and double Gaussian filter as well as the inverse FFT ("Filtered Image") of this
convolution.


Return the Filtered Image
-------------------------

When we have suitable FWHMs for the inner and outer Gaussians, we can use
the :py:func:`temul.signal_processing.double_gaussian_fft_filter` function
the return a filtered image.

.. code-block:: python

    >>> filtered_image = tml.double_gaussian_fft_filter(image, 50, 150)
    >>> image.plot()
    >>> filtered_image.plot()

.. image:: tutorial_images/dg_filter_tutorial/image_plot.png
    :scale: 50 %

.. image:: tutorial_images/dg_filter_tutorial/filtered_image_plot.png
    :scale: 50 %


Details on the
:py:func:`temul.signal_processing.double_gaussian_fft_filter_optimised`
function can be found in the :ref:`api_doc`.