Merge pull request #76 from ufo-kit/docs

Update documentation

15 files changed, 389 insertions, 58 deletions

diff --git a/docs/api.rst b/docs/api.rst
index cf0dd4b..3bdde88 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -18,9 +18,9 @@ all camera strings with ``uca_plugin_manager_get_available_cameras``::
 
         GList *types;
 
-        types = uca_camera_get_available_cameras (manager);
+        types = uca_plugin_manager_get_available_cameras (manager);
 
-        for (GList *it = g_list_first; it != NULL; it = g_list_next (it))
+        for (GList *it = g_list_first (types); it != NULL; it = g_list_next (it))
             g_print ("%s\n", (gchar *) it->data);
 
         /* free the strings and the list */
@@ -76,7 +76,7 @@ With ``UCA_CAMERA_TRIGGER_SOURCE_SOFTWARE`` you have to trigger with
                       NULL);
 
         uca_camera_start_recording (camera, NULL);
-        uca_camera_grab (camera, &buffer, NULL);
+        uca_camera_grab (camera, buffer, NULL);
         uca_camera_stop_recording (camera, NULL);
 
         /* thread B */
diff --git a/docs/cameras.rst b/docs/cameras.rst
index 3e7af7c..39c7fbb 100644
--- a/docs/cameras.rst
+++ b/docs/cameras.rst
@@ -4,13 +4,16 @@ Supported cameras
 The following cameras are supported:
 
 -  pco.edge, pco.dimax, pco.4000 (all CameraLink) via
-   `libpco <http://ufo.kit.edu/repos/libpco.git/>`__. You need to have
+   `libpco <http://ufo.kit.edu/extra/libpco/html/>`__. You need to have
    the SiliconSoftware frame grabber SDK with the ``menable`` kernel
    module installed.
 -  PhotonFocus
 -  Pylon
 -  UFO Camera developed at KIT/IPE.
 
+A `remote access`_ is available for ``libuca`` cameras.
+
+.. _remote access: remote.html
 
 Property documentation
 ----------------------
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/
diff --git a/docs/conf.py b/docs/conf.py
index ac1a43e..44fbb14 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -23,8 +23,6 @@ def get_version():
 
     return '.'.join(version)
 
-extensions = []
-templates_path = ['_templates']
 source_suffix = '.rst'
 master_doc = 'index'
 
@@ -39,7 +37,6 @@ pygments_style = 'sphinx'
 
 html_theme = 'default'
 
-html_static_path = ['_static']
 htmlhelp_basename = 'libucadoc'
 
 latex_documents = [
diff --git a/docs/file.rst b/docs/file.rst
index f698d78..4162eeb 100644
--- a/docs/file.rst
+++ b/docs/file.rst
@@ -10,13 +10,13 @@ string **name**
 unsigned int **sensor-width**
     Width of the sensor in pixels
 
-    | *Default:* 1
+    | *Default:* 512
     | *Range:* [1, 4294967295]
 
 unsigned int **sensor-height**
     Height of the sensor in pixels
 
-    | *Default:* 1
+    | *Default:* 512
     | *Range:* [1, 4294967295]
 
 double **sensor-pixel-width**
@@ -34,7 +34,7 @@ double **sensor-pixel-height**
 unsigned int **sensor-bitdepth**
     Number of bits per pixel
 
-    | *Default:* 1
+    | *Default:* 8
     | *Range:* [1, 32]
 
 unsigned int **sensor-horizontal-binning**
@@ -43,22 +43,12 @@ unsigned int **sensor-horizontal-binning**
     | *Default:* 1
     | *Range:* [1, 4294967295]
 
-None **sensor-horizontal-binnings**
-    Array of possible binnings in horizontal direction
-
-    | *Default:* None
-
 unsigned int **sensor-vertical-binning**
     Number of sensor ADCs that are combined to one pixel in vertical direction
 
     | *Default:* 1
     | *Range:* [1, 4294967295]
 
-None **sensor-vertical-binnings**
-    Array of possible binnings in vertical direction
-
-    | *Default:* None
-
 None **trigger-source**
     Trigger source
 
@@ -162,4 +152,4 @@ unsigned int **num-buffers**
 string **path**
     Path to directory containing TIFF files
 
-    | *Default:* .
\ No newline at end of file
+    | *Default:* .
diff --git a/docs/index.rst b/docs/index.rst
index 223bb5d..bde6a32 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,4 +16,5 @@ Contents
     cameras
     api
     tools
-    tango
+    concert
+    remote
diff --git a/docs/mock.rst b/docs/mock.rst
index 0d8acb0..af96c57 100644
--- a/docs/mock.rst
+++ b/docs/mock.rst
@@ -10,13 +10,13 @@ string **name**
 unsigned int **sensor-width**
     Width of the sensor in pixels
 
-    | *Default:* 1
+    | *Default:* 512
     | *Range:* [1, 4294967295]
 
 unsigned int **sensor-height**
     Height of the sensor in pixels
 
-    | *Default:* 1
+    | *Default:* 512
     | *Range:* [1, 4294967295]
 
 double **sensor-pixel-width**
@@ -34,7 +34,7 @@ double **sensor-pixel-height**
 unsigned int **sensor-bitdepth**
     Number of bits per pixel
 
-    | *Default:* 1
+    | *Default:* 8
     | *Range:* [1, 32]
 
 unsigned int **sensor-horizontal-binning**
@@ -43,22 +43,12 @@ unsigned int **sensor-horizontal-binning**
     | *Default:* 1
     | *Range:* [1, 4294967295]
 
-None **sensor-horizontal-binnings**
-    Array of possible binnings in horizontal direction
-
-    | *Default:* None
-
 unsigned int **sensor-vertical-binning**
     Number of sensor ADCs that are combined to one pixel in vertical direction
 
     | *Default:* 1
     | *Range:* [1, 4294967295]
 
-None **sensor-vertical-binnings**
-    Array of possible binnings in vertical direction
-
-    | *Default:* None
-
 None **trigger-source**
     Trigger source
 
@@ -157,4 +147,9 @@ unsigned int **num-buffers**
     Number of frame buffers in the ring buffer 
 
     | *Default:* 4
-    | *Range:* [0, 4294967295]
\ No newline at end of file
+    | *Range:* [0, 4294967295]
+
+bool **fill-data**
+    Fill data with gradient and random image
+
+    | *Default:* True
diff --git a/docs/pco.rst b/docs/pco.rst
index f64425b..66daa60 100644
--- a/docs/pco.rst
+++ b/docs/pco.rst
@@ -275,7 +275,7 @@ None **timestamp-mode**
     | *Default:* <enum UCA_PCO_CAMERA_TIMESTAMP_NONE of type UcaPcoCameraTimestamp>
 
 string **version**
-    Camera version given as `serial number, hardware major.minor, firmware major.minor'
+    Camera version given as 'serial number, hardware major.minor, firmware major.minor'
 
     | *Default:* 0, 0.0, 0.0
 
diff --git a/docs/python-tango.rst b/docs/python-tango.rst
new file mode 100644
index 0000000..c530e42
--- /dev/null
+++ b/docs/python-tango.rst
@@ -0,0 +1,44 @@
+Python Tango server
+===================
+
+``libuca/tango`` is a Python-based Tango server.
+
+Installation
+------------
+
+In order to install ``libuca/tango`` you need
+
+- `PyTango`_ and
+- `tifffile`_
+
+.. _PyTango: http://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/index.html
+.. _tifffile: https://pypi.python.org/pypi/tifffile
+
+Go to the ``libuca`` directory and install the server script with::
+
+    $ cd tango
+    $ sudo python setup.py install
+
+and create a new TANGO server ``Uca/xyz`` with a class named ``Camera``.
+
+
+Usage
+-----
+
+Before starting the server, you have to create a new device property ``camera``
+which specifies which camera to use. If not set, the ``mock`` camera will be used
+by default.
+
+Start the device server with::
+
+    $ Uca device-property
+
+You should be able to manipulate camera attributes like ``exposure_time`` and to store frames using a ``Start``, ``Store``, ``Stop`` cycle::
+
+    import PyTango
+
+    camera = PyTango.DeviceProxy("foo/Camera/mock")
+    camera.exposure_time = 0.1
+    camera.Start()
+    camera.Store('foo.tif')
+    camera.Stop()
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 05f8df1..b154800 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -47,13 +47,18 @@ To generate bindings for third-party languages, you have to install ::
 Fetching the sources
 ^^^^^^^^^^^^^^^^^^^^
 
-Untar the distribution ::
+Clone the repository ::
 
-    untar xfz libuca-x.y.z.tar.gz
+    git clone https://github.com/ufo-kit/libuca
 
-or clone the repository ::
+or download the latest release at https://github.com/ufo-kit/libuca/releases and 
+unzip the ``.zip`` file::
 
-    git clone https://github.com/ufo-kit/libuca
+    unzip libuca-x.y.z.zip
+
+or untar the ``.tar.gz`` file::
+
+    tar -zxvf libuca-x.y.z.tar.gz
 
 and create a new, empty build directory inside::
 
@@ -176,12 +181,14 @@ Then you need to setup the type system::
         UcaCamera *camera;
         GError *error = NULL; /* this _must_ be set to NULL */
 
-        g_type_init ();
+    #if !(GLIB_CHECK_VERSION (2, 36, 0))
+        g_type_init();
+    #endif
 
 Now you can instantiate new camera *objects*. Each camera is identified
 by a human-readable string, in this case we want to access any pco
 camera that is supported by
-`libpco <http://ufo.kit.edu/repos/libpco.git/>`__. To instantiate a
+`libpco <http://ufo.kit.edu/extra/libpco/html/>`__. To instantiate a
 camera we have to create a plugin manager first::
 
         manager = uca_plugin_manager_new ();
@@ -251,7 +258,7 @@ where the result is stored::
                       );
 
         g_print ("Width of the region of interest: %d\n", roi_width);
-        g_print ("Exposure time: %3.5s\n", exposure_time);
+        g_print ("Exposure time: %3.5fs\n", exposure_time);
 
 In a similar way, properties are set with ``g_object_set``::
 
diff --git a/docs/remote.rst b/docs/remote.rst
new file mode 100644
index 0000000..fccd8f7
--- /dev/null
+++ b/docs/remote.rst
@@ -0,0 +1,15 @@
+Remote access
+=============
+
+A Remote access is available for ``libuca`` cameras:
+
+.. toctree::
+   :maxdepth: 3
+
+   uca-net
+   tango
+   python-tango
+
+The `HZG Tango server`_ can also be used with ``libuca`` cameras.
+
+.. _HZG Tango server: https://bitbucket.org/hzgwpn/libuca-jni
diff --git a/docs/tango.rst b/docs/tango.rst
index fa90b56..f2153e7 100644
--- a/docs/tango.rst
+++ b/docs/tango.rst
@@ -1,9 +1,13 @@
-The GObject Tango device
-========================
+GObject Tango device
+====================
 
 UcaDevice is a generic Tango Device that wraps ``libuca`` in order to
 make libuca controlled cameras available as Tango devices.
 
+.. note::
+
+    The documentation of UcaDevice can be outdated.
+
 
 Architecture
 ------------
@@ -135,8 +139,8 @@ Tango-Event-System here!
 Open Questions, Missing Features etc.
 -------------------------------------
 
-* *Why do we need to specify ``Storage`` for UcaDevice and ``GrabbingDevice``
-  for ImageDevice?*
+* *Why do we need to specify* ``Storage`` *for UcaDevice and* ``GrabbingDevice``
+  *for ImageDevice?*
 
   ImageDevice needs the Tango-Address of UcaDevice to mirror all Attributes and
   Commands and to forward them to it. UcaDevice needs the Tango-Address of
diff --git a/docs/tools.rst b/docs/tools.rst
index 4197cc3..aa7e2c1 100644
--- a/docs/tools.rst
+++ b/docs/tools.rst
@@ -2,8 +2,7 @@ Tools
 =====
 
 Several tools are available to ensure ``libuca`` works as expected. All
-of them are located in ``build/test/`` and some of them are installed
-with ``make installed``.
+of them are installed with ``make install``.
 
 
 uca-camera-control -- simple graphical user interface
@@ -14,11 +13,15 @@ side pane:
 
 .. image:: uca-gui.png
 
+You can see all available options of ``uca-camera-control`` with::
+
+    $ uca-camera-control --help-all
+
 
 uca-grab -- grabbing frames
 ---------------------------
 
-Grab with frames with ::
+Grab frames with ::
 
     $ uca-grab --num-frames=10 camera-model
 
@@ -36,6 +39,10 @@ in fractions of seconds::
 
     $ uca-grab --duration=0.25 camera-model
 
+You can see all available options of ``uca-grab`` with::
+
+    $ uca-grab --help-all
+
 
 uca-benchmark -- check bandwidth
 --------------------------------
@@ -43,11 +50,49 @@ uca-benchmark -- check bandwidth
 Measure the memory bandwidth by taking subsequent frames and averaging
 the grabbing time::
 
-    $ ./benchmark mock
+    $ uca-benchmark option camera-model
+
+You can specify the number of frames per run with the ``-n/--num-frames`` option, the number of runs with the ``-r/--num-runs`` option and test asynchronous mode with the ``async`` option::
+
+    $ uca-benchmark -n 100 -r 3 --async mock
+
+    # Type    Trigger Source   FPS        Bandwidth   Frames acquired/total
+      sync    auto             17.57 Hz   4.39 MB/s   300/300 acquired (0.00% dropped)
+      async   auto             19.98 Hz   4.99 MB/s   300/300 acquired (0.00% dropped)
+
     # --- General information ---
-    # Sensor size: 640x480
-    # ROI size: 640x480
-    # Exposure time: 0.000010s
-    # type      n_frames  n_runs    frames/s        MiB/s
-      sync      100       3         29848.98        8744.82
-      async     100       3         15739.43        4611.16
+    # Camera: mock
+    # Sensor size: 4096x4096
+    # ROI size: 512x512
+    # Exposure time: 0.050000s
+
+You can see all available options of ``uca-benchmark`` with::
+
+    $ uca-benchmark --help-all
+
+
+uca-info -- get properties information
+--------------------------------------
+
+Get information about camera properties with::
+
+    $ uca-info camera-model
+
+For example::
+
+    $ uca-info mock
+    # RO | name                      | "mock camera"
+    # RO | sensor-width              | 4096
+    # RO | sensor-height             | 4096
+    # RO | sensor-pixel-width        | 0.000010
+    # RO | sensor-pixel-height       | 0.000010
+    # RO | sensor-bitdepth           | 8
+    ...
+
+
+uca-gen-doc -- generate properties documentation
+------------------------------------------------
+
+Generate HTML source code of property documentation of a camera with::
+
+    $ uca-gen-doc camera-model
diff --git a/docs/uca-gui.png b/docs/uca-gui.png
index eb60953..89429d5 100644
--- a/docs/uca-gui.png
+++ b/docs/uca-gui.png
diff --git a/docs/uca-net.rst b/docs/uca-net.rst
new file mode 100644
index 0000000..7a71608
--- /dev/null
+++ b/docs/uca-net.rst
@@ -0,0 +1,42 @@
+TCP-based network bridge camera
+===============================
+
+`uca-net`_ is a transparent TCP-based network bridge camera for remote access of ``libuca``
+cameras.
+
+.. _uca-net: https://github.com/ufo-kit/uca-net
+
+
+Installation
+------------
+
+The only dependency is libuca itself and any camera you wish to access.
+
+Clone the repository::
+
+    $ git clone https://github.com/ufo-kit/uca-net.git
+
+and create a new build directory inside::
+
+    $ cd uca-net/
+    $ mkdir build
+
+The installation process is the same as by ``libuca``::
+
+    $ cd build/
+    $ cmake ..
+    $ make
+    $ sudo make install
+
+
+Usage
+-----
+
+You can start a server on a remote machine with::
+
+    $ ucad camera-model
+
+and connect to it from any other machine, for example::
+
+    $ uca-grab -p host=foo.bar.com:4567 -n 10 net   // grab ten frames
+    $ uca-camera-control -c net                     // control graphically