summaryrefslogtreecommitdiffstats
path: root/docs/concert.rst
blob: 0c44d899ef3ca2ea839e94ab1ca004ccb8323a36 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
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/