.. _headless:

.. _PyJAMAS: https://bitbucket.org/rfg_lab/pyjamas/src/master/
.. _Qt: https://www.qt.io/

================================
Using PyJAMAS_ in headless mode
================================

Some times it can be convenient to create a PyJAMAS_ instance within a notebook, or in an environment in which no display is available, to use a PyJAMAS_ object and the associated functionality. While these should work with no problem, creating the PyJAMAS_ object could printout warnings related to the lack of a display. To get around these issues, it is possible to create the PyJAMAS object in *headless* mode. In headless mode, PyJAMAS_ uses Qt_ offscreen rendering capabilities to avoid the need for a display. This is done by setting the environment variable `QT_QPA_PLATFORM` to `offscreen` before creating the PyJAMAS_ object. Please, note that once a headless PyJAMAS_ object is created, it is not possible to create a non-headless PyJAMAS_ object in the same Python session (e.g. notebook), and *vice versa*.

This code block illustrates how to create a PyJAMAS_ object in headless mode, how to use the headless PyJAMAS_ object to load annotations onto a virtual image (notice the second parameter passed on to *cbLoadAnnotations*), and how to plot the trajectories of the fiducials loaded (this time using a static PyJAMAS_ method, *plotly_trajectories*):.

.. code-block:: python

    from pyjamas.pjscore import PyJAMAS
    from pyjamas.rutils import RUtils

    apjs = PyJAMAS(headless=True)  # headless!!

    thepath = 'path/to/your/annotations.pjs'

    apjs.io.cbLoadAnnotations([thepath], '')  # no display

    fig_trajectories = RUtils.plotly_trajectories(apjs.fiducials, xy_res, t_res)
    fig_trajectories.show()