summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMariaMatveeva <matveeva.maria@gmail.com>2016-08-26 14:29:03 +0200
committerMariaMatveeva <matveeva.maria@gmail.com>2016-08-26 14:29:03 +0200
commit48b868c5208816b007ec1d9c7940e75b4c64e5ce (patch)
treeca1f4a3bc0838b94b9fe9774d23ca1848948c303
parentd0aabc426cb01d488e9d41a66623773da73ff5e3 (diff)
downloaduca-48b868c5208816b007ec1d9c7940e75b4c64e5ce.tar.gz
uca-48b868c5208816b007ec1d9c7940e75b4c64e5ce.tar.bz2
uca-48b868c5208816b007ec1d9c7940e75b4c64e5ce.tar.xz
uca-48b868c5208816b007ec1d9c7940e75b4c64e5ce.zip
Update documentation
-rw-r--r--docs/api.rst6
-rw-r--r--docs/cameras.rst5
-rw-r--r--docs/concert.rst188
-rw-r--r--docs/conf.py3
-rw-r--r--docs/file.rst18
-rw-r--r--docs/index.rst3
-rw-r--r--docs/mock.rst23
-rw-r--r--docs/pco.rst2
-rw-r--r--docs/python-tango.rst44
-rw-r--r--docs/quickstart.rst21
-rw-r--r--docs/remote.rst15
-rw-r--r--docs/tango.rst12
-rw-r--r--docs/tools.rst65
-rw-r--r--docs/uca-gui.pngbin112062 -> 254960 bytes
-rw-r--r--docs/uca-net.rst42
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
Binary files differ
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