How to acquire data with specMACS
=================================

The specMACS data acquisition system is built on ideas of the actor model and tries to be highly configureable and modular.
This modularity is immediately visible to the user, as many separate processes have to be started to offer a running acquisition system as a combination of them.

Background setup
----------------

To allow all of the components to talk to each other, two main parts are needed:

* A running :doc:`../roc/rocbroker`, which is a server to wich all components register and which is responsible for relaying messages between them.
* A :doc:`capture_config`, which states the address of the :doc:`../roc/rocbroker` and some auxiliary configuration options.

As a starting point, the following simple configuration file can be stored under ``~/.macs/capture.json``:

.. literalinclude:: ../../configs/capture_simple.json
   :language: json

After adding the IP address or hostname of the computer running the :doc:`../roc/rocbroker`, this will configure a capturing system with two cameras, and store data under ``K:/``.

The next step is to start the :doc:`../roc/rocbroker` by the following command::

    python -m runmacs.roc.rocbroker

Getting data from the cameras
-----------------------------
Image data is received from the cameras by the :doc:`camserver`, which is a C++ program.
It can be found under ``cpp/camserver[.exe]`` after a simple ``make`` in the ``cpp`` directory.
Start it simply by issuing::

    camserver

From inside the ``cpp`` directory (or ``./camserver`` for simulation under Linux/OSX).

The :doc:`camserver` will read the configuration and start a data acquisition thread for each listed camera.
It will further connect to the :doc:`../roc/rocbroker` waiting for additional commands.

User interface
--------------
Up to now, no visble feedback is available to the user and no data is actually stored on disk.
Therefore, at least one user interface should be started.
Try one (or both) of::

    python spec_gui.py
    python spec_gui_simple.py

In the root directory of the source tree.

:note: For the simple gui, a short PDF-Manual is available `here <../_static/pdf/specMacsGuiManual.pdf>`_.

Changing camera settings
------------------------
The :doc:`camserver` is only responsible for getting and storing image data.
Changing camera settings is subject to another program, one for each camera.
As most other actors, these can be found at ``runmacs/roc/servers``.
So start the following two actors::

    python -m runmacs.roc.servers.vnir
    python -m runmacs.roc.servers.swir

As soon as they are running, it should be possible to read an set the cameras framerate and integration time using ``spec_gui.py``.
``spec_gui_simple.py`` additionally requires the autoexposure actors to regulate the integration time.
They can be started using::

    python -m runmacs.roc.servers.vnir_autoexp
    python -m runmacs.roc.servers.swir_autoexp

Logging
-------
Log messages are automatically distributed using the :doc:`../roc/rocbroker`, you can already see them in one of the user interfaces.
If you want to store them to a file, use :doc:`logdump`.

Supervisor
----------
To keep all of the needed programs running, it is advisable to use a supervisor like `Ramona <https://ateska.github.io/ramona/>`_ or `supervisord <http://supervisord.org/>`_.