Update documentation

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/