.. _limaCameras:

***********************
The limaCameras package
***********************

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

The `limaCameras` package provides a mean for controlling cameras
supported by LImA [1]_, for example Basler cameras.

.. _limaCameras-parameters:

LimaDevice expected parameters
------------------------------

Some LImA parameters are already available in the LimaDevice base class:

* Camera Type, read-only
* Camera Model, read-only
* Sensor Width [pixel], read-only
* Sensor Height [pixel], read-only
* Image Depth [bytes], read-only
* Trigger Mode
* Exposure Time [ms]
* Latency Time [ms]: the latency time between two successive exposures
* Number of Frames: the number of frames to be acquired (0 means unlimited)
* Image Rotation [degrees]
* Image Flip (X and Y)
* Image Binning (X and Y)
* ROI (X, Y, Width and Height)

More parameters are available in the derived devices.


.. _limaCameras-deployment:

Deployment Guidelines
=====================

`limaCameras` will automatically install its dependency LImA.

In order to have the receiving thread executed with real time priority,
the line

.. code-block:: bash

    username rtprio 99

shall be added to the file ``/etc/security/limits.conf`` on the control
server (may differ depending on the Linux distribution).

The MTU on the network interface used for the camera shall be set - when
possible - to 9000, also known as "jumbo frames".

For debugging purposes it can be useful to have ``tshark`` installed on the
control server, and ``xctrl`` user added to the ``wireshark`` group.

The control server should have a 10 GbE network interface for sending images
to the DAQ, and possibly one for the GUI server.

Please also check the camera specific configuration section, e.g. Basler's
:ref:`limaBaslerCameras-setup`.


.. _limaCameras-contact:

Expert Contact
==============

* Andrea Parenti <andrea.parenti@xfel.eu>


How to create a new camera device in limaCameras
================================================

After checking-out `limaCameras` and its dependencies, as specified in the
DEPENDS file, you can add your a new camera device in `src/limaCameras`,
named for example `MyLimaCamera`.

Do not forget to add it to `setup.py`, in the `entry_points`
section. This is needed to have it loaded by the Karabo python server.

Once you have done it, you can edit the source file (see
:ref:`limaCameras-py-file` Section).


.. _limaCameras-py-file:

MyLimaCamera.py file
--------------------

This method is abstract in `LimaDevice` and must therefore be defined
in `MyLimaCamera`:

* **initializeCamera** is the function where the `Camera` and
  `HwInterface` objects have to be initialized.

There are also two user's hooks in the `LimaDevice` class, which do
nothing by default but can be overwritten in the derived class:

* **pollCameraSpecific** is called regularly, and can be used to read
  parameters from the camera and set them in the `MyLimaCamera`
  device.

* **reconfigureCameraSpecific** is called upon reconfiguration of the
  device, and can be used to set camera specific parameters.

This method is defined in the base class but can be redefined in
`MyLimaCamera` to do more specific checks:

* **isConnected** shall return `True` if camera is connected.

This is for example the code for a camera using the Simulator plugin
(`Lima.Simulator` subpackage):

.. code-block:: python

    #!/usr/bin/env python

    #############################################################################
    # Author: <andrea.parenti@xfel.eu>
    # Created on Jul 21, 2017
    # Copyright (C) European XFEL GmbH Hamburg. All rights reserved.
    #############################################################################

    from karabo.bound import (
        KARABO_CLASSINFO, PythonDevice
    )

    from .lima_device import LimaDevice

    import Lima.Simulator

    @KARABO_CLASSINFO("MyLimaCamera", "2.1")
    class MyLimaCamera(LimaDevice, PythonDevice):
	def __init__(self, configuration):
	    # always call PythonDevice constructor first!
	    super(MyLimaCamera,self).__init__(configuration)

	@staticmethod
	def expectedParameters(expected):
	    # Simulated camera does not have any additional parameters
	    pass

	def initializeCamera(self):
	    self.log.INFO("Initialize Simulated camera")

	    # Creates the camera object (Simulator)
	    self.camera = Lima.Simulator.Camera()
	    # Creates the HwInterface
	    self.interface = Lima.Simulator.Interface(self.camera)

.. rubric:: Footnotes

.. [1] `Lima <http://lima.blissgarden.org/>`_ ( **L**\ibrary for
   **Im**\age **A**\cquisition) is a project for the unified control
   of 2D detectors.