****************************
A quick Slitjaw Image Viewer
****************************

IRIS Slitjaw (SJI) files are often very large and unwieldy to load into memory.
On the other hand, viewing them as movies is a very effective way of getting an oversight over what a specific observing run has seen and will highlight any special events that can and will be of use in data analysis.
`matplotlib` has proven to be fairly slow at rendering animated data so we have built a visualizer using PyQT instead.
It is fairly primitive, and misses a lot of the nice features of `matplotlib`, but it **is** fast, which is what is often needed.
This module can be run both as a standalone code or inside, e.g., an IPython session.

Installation
============

You will first need to install |IRISLMSALgit| as described in the :ref:`Introduction`.
Once that is done the code can be run as a standalone by setting the path to include the location of the |IRISLMSALgit| repository on your machine, e.g., for a ``tcsh`` shell

.. code-block:: bash

    setenv PATH $PATH":$HOME/LMSAL_HUB/iris_hub/iris_lmsalpy/iris_lmsalpy/"

Running standalone
==================

Once set-up is complete, the viewer can be run from the shell command line for viewing an IRIS SJI file with

.. code-block:: bash

    im_view.py iris_l2_20160702_092921_3680258322_SJI_1330_t000.fits

The module takes three parameters:

.. code-block:: bash

    im_view.py  -h -v -g -c <sji_fitsinputfile>

where:

* ``-h`` is for help
* ``-v`` is for verbose
* ``-g`` ``<value>``  sets the gamma used in the display
* ``-c`` ``<value>``, sets the cutoff in the histogram used for setting the max and min values of the colorscale.

The min and max values of the first image are calculated, using the module ``histo_opt`` by making a histogram of the image and removing the pixels that with lower/higher intensities than cutoff/1 - cutoff percentage of the filled histogram bins, with the addition that the lowest possible value is set to be the *second* bin of the histogram (as many points can be set to "zero" in IRIS images).

The options to the ``im_view`` module can also be given in longer version ``--verbose``, ``--gamma``, ``--cutoff``, ``--help``.

Note that for comparison purposes there is also a viewer based on `matplotlib` that can be run in standalone mode:

.. code-block:: bash

    im_view_plt.py <sji_fitsinputfile>

It takes the same options as ``im_view``.

Running in a Python session
===========================

To run the viewer in a Python session is quite simple as well:

.. code-block:: python

    >>> from iris_lmsalpy import im_view as im
    >>> files = im.sji_files()

    [0] iris_l2_20190511_162936_3803109418_SJI_2796_t000.fits
    [1] iris_l2_20160702_092921_3680258322_SJI_2832_t000.fits
    [2] iris_l2_20190511_162936_3803109418_SJI_1400_t000.fits
    [3] iris_l2_20181009_154453_3620028413_SJI_2796_t000.fits
    ...

    >>> im.sji_view(files[0])

Where ``sji_files()`` finds and displays all the files in the current directory with ``*SjI*.fits`` in their name and returns these filenames as a list.
The routine takes the keyword ``dir`` in case the files looked for are in the directory ``dir`` instead.
The viewer itself, ``sji_view``, takes the keywords ``gamma`` and ``cutoff`` and ``verbose``, e.g.,

.. code-block:: python

    >>> im.sji_view(<filename>, gamma=0.3, cutoff=1e-3, verbose=True)

``histo_opt``
=============

The ``histo_opt`` module is used to scale images in the viewer and has other uses as well.
It can be called in the same manner as ``sji_files`` and ``sji_view``:

.. code-block:: python

    >>> # image is a numpy array
    >>> from iris_lmsalpy import im_view as im
    >>> levels = im.histo_opt(image, cutoff=1.5e-3, gamma=1.0, verbose=True)

where the function returns ``levels=(vmin,vmax)`` i.e., the histogram optimized maximum and minimum of the image.