summaryrefslogtreecommitdiffstats
path: root/docs/concert.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/concert.rst')
-rw-r--r--docs/concert.rst188
1 files changed, 188 insertions, 0 deletions
diff --git a/docs/concert.rst b/docs/concert.rst
new file mode 100644
index 0000000..0c44d89
--- /dev/null
+++ b/docs/concert.rst
@@ -0,0 +1,188 @@
+Concert
+=======
+
+`Concert`_ is a light-weight control system interface, which can also control ``libuca`` cameras.
+
+.. _Concert: https://github.com/ufo-kit/concert
+
+
+Installation
+------------
+
+In the `official documentation`_ you can read `how to install`_ ``Concert``.
+
+.. _official documentation: https://concert.readthedocs.io/en/latest/
+.. _how to install: https://concert.readthedocs.io/en/latest/user/install.html
+
+
+Usage
+-----
+
+``Concert`` can be used from a session and within an integrated ``IPython`` shell or as a library.
+
+In order to create a concert session you should first initialize the session and then start the editor::
+
+ $ concert init session
+ $ concert edit session
+
+You can simply add your camera, for example the ``mock`` camera with::
+
+ from concert.devices.cameras.uca import Camera
+
+ camera = Camera("mock")
+
+and start the session with::
+
+ $ concert start session
+
+The function ``ddoc()`` will give you an overview of all defined devices in the session::
+
+ session > ddoc()
+ # ------------------------------------------------------------------------------------------------
+ # Name Description Parameters
+ # ------------------------------------------------------------------------------------------------
+ # camera libuca-based camera. Name Unit Description
+ # buffered None info TRUE if libuca should buffer
+ # All properties that are frames
+ # exported by the locked no
+ # underlying camera are exposure_time second info Exposure time in seconds
+ # also visible. locked no
+ # lower -inf second
+ # upper inf second
+ ...
+
+
+Getting and setting camera parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can get an overview of the camera parameters by calling the ``dstate()`` function::
+
+ session > dstate()
+ # ---------------------------------------------------------
+ # Name Parameters
+ # ---------------------------------------------------------
+ # camera buffered False
+ # exposure_time 0.05 second
+ # fill_data True
+ # frame_rate 20.0 1 / second
+ # has_camram_recording False
+ # has_streaming True
+ ...
+
+set the value of a parameter with::
+
+ session > camera.exposure_time = 0.01 * q.s
+
+and check the set value with::
+
+ session > camera.exposure_time
+ # <Quantity(0.01, 'second')>
+
+or you can use the ``get()`` and ``set()`` methods::
+
+ session > exposure_time = camera["exposure_time"]
+ session > exposure_time.set(0.1 * q.s)
+ session > exposure_time.get().result()
+ # <Quantity(0.1, 'second')>
+
+In order to set the trigger source property you can use ``trigger_sources.AUTO``, ``trigger_sources.SOFTWARE`` or ``trigger_sources.EXTERNAL``::
+
+ session > camera.trigger_source = camera.trigger_sources.AUTO
+
+
+Grabbing frames
+~~~~~~~~~~~~~~~
+
+To grab a frame, first start the camera, use the ``grab()`` function and stop the camera afterwards::
+
+ session > camera.start_recording()
+ session > frame = camera.grab()
+ session > camera.stop_recording()
+
+You get the frame as an array::
+
+ session > frame
+ # array([[ 0, 0, 0, ..., 0, 0, 0],
+ # [ 0, 0, 0, ..., 0, 0, 0],
+ # [ 0, 0, 255, ..., 0, 0, 0],
+ # ...,
+ # [ 0, 0, 0, ..., 0, 0, 0],
+ # [ 0, 0, 0, ..., 0, 0, 0],
+ # [ 0, 0, 0, ..., 0, 0, 0]], dtype=uint8)
+
+
+Saving state and locking parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can store the current state of your camera with::
+
+ session > camera.stash()
+ # <Future at 0x2b8ab10 state=running>
+
+And go back to it again with::
+
+ session > camera.restore()
+ # <Future at 0x299f550 state=running>
+
+In case you want to prevent a parameter or all the parameters from being written you can use the ``lock()`` method::
+
+ session > camera["exposure_time"].lock()
+ session > camera["exposure_time"].set(1 * q.s)
+ # <Future at 0x2bb3d90 state=finished raised LockError>
+
+ # lock all parameters of the camera device
+ session > camera.lock()
+
+and to unlock them again, just use the ``unlock()`` method::
+
+ session > camera.unlock()
+
+
+Concert as a library - more examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also use ``Concert`` as a library.
+
+For example test the bit depth consistency with::
+
+ import numpy as np
+ from concert.quantities import q
+ from concert.devices.cameras.uca import Camera
+
+
+ def acquire_frame(camera):
+ camera.start_recording()
+ frame = camera.grab()
+ camera.stop_recording()
+ return frame
+
+ def test_bit_depth_consistency(camera):
+ camera.exposure_time = 1 * q.s
+ frame = acquire_frame(camera)
+
+ bits = camera.sensor_bitdepth
+ success = np.mean(frame) < 2**bits.magnitude
+ print "success" if success else "higher values than possible"
+
+ camera = Camera("mock")
+ test_bit_depth_consistency(camera)
+
+or the exposure time consistency with::
+
+ def test_exposure_time_consistency(camera):
+ camera.exposure_time = 1 * q.ms
+ first = acquire_frame(camera)
+
+ camera.exposure_time = 100 * q.ms
+ second = acquire_frame(camera)
+
+ success = np.mean(first) < np.mean(second)
+ print "success" if success else "mean image value is lower than expected"
+
+
+Official Documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you have more questions or just want to know more about ``Concert``, please take a look at the very detailed `official documentation`_.
+
+.. _official documentation: https://concert.readthedocs.io/en/latest/