diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api.rst | 6 | ||||
| -rw-r--r-- | docs/cameras.rst | 5 | ||||
| -rw-r--r-- | docs/concert.rst | 188 | ||||
| -rw-r--r-- | docs/conf.py | 3 | ||||
| -rw-r--r-- | docs/file.rst | 18 | ||||
| -rw-r--r-- | docs/index.rst | 3 | ||||
| -rw-r--r-- | docs/mock.rst | 23 | ||||
| -rw-r--r-- | docs/pco.rst | 2 | ||||
| -rw-r--r-- | docs/python-tango.rst | 44 | ||||
| -rw-r--r-- | docs/quickstart.rst | 21 | ||||
| -rw-r--r-- | docs/remote.rst | 15 | ||||
| -rw-r--r-- | docs/tango.rst | 12 | ||||
| -rw-r--r-- | docs/tools.rst | 65 | ||||
| -rw-r--r-- | docs/uca-gui.png | bin | 112062 -> 254960 bytes | |||
| -rw-r--r-- | docs/uca-net.rst | 42 |
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 Binary files differindex 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 |
