diff options
Diffstat (limited to 'docs/index.rst')
| -rw-r--r-- | docs/index.rst | 695 |
1 files changed, 12 insertions, 683 deletions
diff --git a/docs/index.rst b/docs/index.rst index 0ac412a..223bb5d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,690 +1,19 @@ Welcome ======= -libuca is a light-weight camera abstraction library, focused on scientific -cameras used at the ANKA synchrotron. +`libuca`_ is a light-weight camera abstraction library written in C and GObject, +focused on scientific cameras used at the ANKA synchrotron. +.. _libuca: https://github.com/ufo-kit/libuca -Quickstart -========== +Contents +-------- -Installation ------------- +.. toctree:: + :maxdepth: 2 -Before installing ``libuca`` itself, you should install any drivers and -SDKs needed to access the cameras you want to access through ``libuca``. -Now you have two options: install pre-built packages or build from -source. - - -Installing packages -~~~~~~~~~~~~~~~~~~~ - -Packages for the core library and all plugins are currently provided for -openSUSE. To install them run ``zypper``: - -:: - - sudo zypper in libuca-x.y.z-x86_64.rpm - sudo zypper in uca-plugin-*.rpm - -To install development files such as headers, you have to install the -``libuca-x.y.z-devel.rpm`` package. - - -Building from source -~~~~~~~~~~~~~~~~~~~~ - -Building the library and installing from source is simple and -straightforward. Make sure you have - -- CMake, -- a C compiler, -- GLib and GObject development libraries and -- necessary camera SDKs - -installed. - -For the base system, install :: - - [Debian] sudo apt-get install libglib2.0 cmake gcc - [openSUSE] sudo zypper in glib2-devel cmake gcc - -In case you want to use the graphical user interface you also need the -Gtk+ development libraries:: - - [Debian] sudo apt-get install libgtk+2.0-dev - [openSUSE] sudo zypper in gtk2-devel - -To generate bindings for third-party languages, you have to install :: - - [Debian] sudo apt-get install gobject-introspection - [openSUSE] sudo zypper in gobject-introspection-devel - - -Fetching the sources -^^^^^^^^^^^^^^^^^^^^ - -Untar the distribution :: - - untar xfz libuca-x.y.z.tar.gz - -or clone the repository :: - - git clone http://ufo.kit.edu/git/libuca - -and create a new, empty build directory inside:: - - cd libuca/ - mkdir build - - -Configuring and building -^^^^^^^^^^^^^^^^^^^^^^^^ - -Now you need to create the Makefile with CMake. Go into the build -directory and point CMake to the ``libuca`` top-level directory:: - - cd build/ - cmake .. - -As long as the last line reads "Build files have been written to", the -configuration stage is successful. In this case you can build ``libuca`` -with :: - - make - -and install with :: - - sudo make install - -If an *essential* dependency could not be found, the configuration stage -will stop and build files will not be written. If a *non-essential* -dependency (such as a certain camera SDK) is not found, the -configuration stage will continue but that particular camera support not -built. - -If you want to customize the build process you can pass several -variables to CMake:: - - cmake .. -DPREFIX=/usr -DLIBDIR=/usr/lib64 - -The former tells CMake to install into ``/usr`` instead of -``/usr/local`` and the latter that we want to install the libraries and -plugins into the ``lib64`` subdir instead of the default ``lib`` subdir -as it is common on SUSE systems. - - -First look at the API ---------------------- - -.. highlight:: c - -The API for accessing cameras is straightforward. First you need to -include the necessary header files:: - - #include <glib-object.h> - #include <uca/uca-plugin-manager.h> - #include <uca/uca-camera.h> - -Then you need to setup the type system:: - - int - main (int argc, char *argv[]) - { - UcaPluginManager *manager; - UcaCamera *camera; - GError *error = NULL; /* this _must_ be set to NULL */ - - g_type_init (); - -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 -camera we have to create a plugin manager first:: - - manager = uca_plugin_manager_new (); - camera = uca_plugin_manager_get_camera (manager, "pco", &error); - -Errors are indicated with a returned value ``NULL`` and ``error`` set to -a value other than ``NULL``:: - - if (camera == NULL) { - g_error ("Initialization: %s", error->message); - return 1; - } - -You should always remove the -`reference <http://developer.gnome.org/gobject/stable/gobject-memory.html#gobject-memory-refcount>`__ -from the camera object when not using it in order to free all associated -resources:: - - g_object_unref (camera); - return 0; - } - -Compile this program with :: - - cc `pkg-config --cflags --libs libuca glib-2.0` foo.c -o foo - -Now, run ``foo`` and verify that no errors occur. - - -Grabbing frames -~~~~~~~~~~~~~~~ - -To synchronously grab frames, first start the camera:: - - uca_camera_start_recording (camera, &error); - g_assert_no_error (error); - -Now, you have to allocate a suitably sized buffer and pass it to -``uca_camera_grab``:: - - gpointer buffer = g_malloc0 (640 * 480 * 2); - - uca_camera_grab (camera, buffer, &error); - -You have to make sure that the buffer is large enough by querying the -size of the region of interest and the number of bits that are -transferred. - - -Getting and setting camera parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Because camera parameters vary tremendously between different vendors -and products, they are realized with so-called GObject *properties*, a -mechanism that maps string keys to typed and access restricted values. -To get a value, you use the ``g_object_get`` function and provide memory -where the result is stored:: - - guint roi_width; - gdouble exposure_time; - - g_object_get (G_OBJECT(camera), - "roi-width", &roi_width, - "exposure-time", &exposure_time, - /* The NULL marks the end! */ - NULL - ); - - g_print ("Width of the region of interest: %d\n", roi_width); - g_print ("Exposure time: %3.5s\n", exposure_time); - -In a similar way, properties are set with ``g_object_set``:: - - guint roi_width = 512; - gdouble exposure_time = 0.001; - - g_object_set (G_OBJECT (camera), - "roi-width", roi_width, - "exposure-time", exposure_time, - NULL); - -Each property can be associated with a physical unit. To query for the -unit call ``uca_camera_get_unit`` and pass a property name. The function -will then return a value from the ``UcaUnit`` enum. - -Several essential camera parameters *must* be implemented by all -cameras. To get a list of them consult the API reference for -```UcaCamera`` <http://ufo.kit.edu/extra/libuca/reference/UcaCamera.html#UcaCamera.properties>`__. -For camera specific parameters you need to consult the corresponding API -reference for ``UfoFooCamera``. The latest nightly built reference can -be found `here <http://ufo.kit.edu/extra/libuca/reference/>`__. - - -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 - the SiliconSoftware frame grabber SDK with the ``menable`` kernel - module installed. -- PhotonFocus -- Pylon -- UFO Camera developed at KIT/IPE. - - -Property documentation ----------------------- - -- `mock <mock.html>`__ -- `pco <pco.html>`__ -- `PhotonFocus <pf.html>`__ -- `Ufo Camera <ufo.html>`__ - - -More API -======== - -In the `last section <#first-look-at-the-api>`__, we had a quick glance -over the basic API used to communicate with the camera. Now we will go -into more detail. - - -Instantiating cameras ---------------------- - -We have already seen how to instantiate a camera object from a name. If -you have more than one camera connected to a machine, you will most -likely want the user decide which to use. To do so, you can enumerate -all camera strings with ``uca_plugin_manager_get_available_cameras``:: - - GList *types; - - types = uca_camera_get_available_cameras (manager); - - for (GList *it = g_list_first; it != NULL; it = g_list_next (it)) - g_print ("%s\n", (gchar *) it->data); - - /* free the strings and the list */ - g_list_foreach (types, (GFunc) g_free, NULL); - g_list_free (types); - - -Errors ------- - -All public API functions take a location of a pointer to a ``GError`` -structure as a last argument. You can pass in a ``NULL`` value, in which -case you cannot be notified about exceptional behavior. On the other -hand, if you pass in a pointer to a ``GError``, it must be initialized -with ``NULL`` so that you do not accidentally overwrite and miss an -error occurred earlier. - -Read more about ``GError``\ s in the official GLib -`documentation <http://developer.gnome.org/glib/stable/glib-Error-Reporting.html>`__. - - -Recording ---------- - -Recording frames is independent of actually grabbing them and is started -with ``uca_camera_start_recording``. You should always stop the -recording with ``ufo_camera_stop_recording`` when you finished. When the -recording has started, you can grab frames synchronously as described -earlier. In this mode, a block to ``uca_camera_grab`` blocks until a -frame is read from the camera. Grabbing might block indefinitely, when -the camera is not functioning correctly or it is not triggered -automatically. - - -Triggering ----------- - -``libuca`` supports three trigger modes through the "trigger-mode" -property: - -1. ``UCA_CAMERA_TRIGGER_AUTO``: Exposure is triggered by the camera - itself. -2. ``UCA_CAMERA_TRIGGER_INTERNAL``: Exposure is triggered via software. -3. ``UCA_CAMERA_TRIGGER_EXTERNAL``: Exposure is triggered by an external - hardware mechanism. - -With ``UCA_CAMERA_TRIGGER_INTERNAL`` you have to trigger with -``uca_camera_trigger``:: - - /* thread A */ - g_object_set (G_OBJECT (camera), - "trigger-mode", UCA_CAMERA_TRIGGER_INTERNAL, - NULL); - - uca_camera_start_recording (camera, NULL); - uca_camera_grab (camera, &buffer, NULL); - uca_camera_stop_recording (camera, NULL); - - /* thread B */ - uca_camera_trigger (camera, NULL); - - -Grabbing frames asynchronously ------------------------------- - -In some applications, it might make sense to setup asynchronous frame -acquisition, for which you will not be blocked by a call to ``libuca``:: - - static void - callback (gpointer buffer, gpointer user_data) - { - /* - * Do something useful with the buffer and the string we have got. - */ - } - - static void - setup_async (UcaCamera *camera) - { - gchar *s = g_strdup ("lorem ipsum"); - - g_object_set (G_OBJECT (camera), - "transfer-asynchronously", TRUE, - NULL); - - uca_camera_set_grab_func (camera, callback, s); - uca_camera_start_recording (camera, NULL); - - /* - * We will return here and `callback` will be called for each newo - * new frame. - */ - } - - -Bindings -======== - -.. highlight:: python - -Since version 1.1, libuca generates GObject introspection meta data if -``g-ir-scanner`` and ``g-ir-compiler`` can be found. When the XML -description ``Uca-x.y.gir`` and the typelib ``Uca-x.y.typelib`` are -installed, GI-aware languages can access libuca and create and modify -cameras, for example in Python:: - - from gi.repository import Uca - - pm = Uca.PluginManager() - - # List all cameras - print(pm.get_available_cameras()) - - # Load a camera - cam = pm.get_camerav('pco', []) - - # You can read and write properties in two ways - cam.set_properties(exposure_time=0.05) - cam.props.roi_width = 1024 - -Note, that the naming of classes and properties depends on the GI -implementation of the target language. For example with Python, the -namespace prefix ``uca_`` becomes the module name ``Uca`` and dashes -separating property names become underscores. - -Integration with Numpy is relatively straightforward. The most important -thing is to get the data pointer from a Numpy array to pass it to -``uca_camera_grab``:: - - import numpy as np - - def create_array_from(camera): - """Create a suitably sized Numpy array and return it together with the - arrays data pointer""" - bits = camera.props.sensor_bitdepth - dtype = np.uint16 if bits > 8 else np.uint8 - a = np.zeros((cam.props.roi_height, cam.props.roi_width), dtype=dtype) - return a, a.__array_interface__['data'][0] - - # Suppose 'camera' is a already available, you would get the camera data like - # this: - a, buf = create_array_from(camera) - camera.start_recording() - camera.grab(buf) - - # Now data is in 'a' and we can use Numpy functions on it - print(np.mean(a)) - - camera.stop_recording() - - -Integrating new cameras -======================= - -A new camera is integrated by -`sub-classing <http://developer.gnome.org/gobject/stable/howto-gobject.html>`__ -``UcaCamera`` and implement all virtual methods. The simplest way is to -take the ``mock`` camera and rename all occurences. Note, that if you -class is going to be called ``FooBar``, the upper case variant is -``FOO_BAR`` and the lower case variant is ``foo_bar``. - -In order to fully implement a camera, you need to override at least the -following virtual methods: - -- ``start_recording``: Take suitable actions so that a subsequent call - to ``grab`` delivers an image or blocks until one is exposed. -- ``stop_recording``: Stop recording so that subsequent calls to - ``grab`` fail. -- ``grab``: Return an image from the camera or block until one is - ready. - - -Asynchronous operation ----------------------- - -When the camera supports asynchronous acquisition and announces it with -a true boolean value for ``"transfer-asynchronously"``, a mechanism must -be setup up during ``start_recording`` so that for each new frame the -grab func callback is called. - - -Cameras with internal memory ----------------------------- - -Cameras such as the pco.dimax record into their own on-board memory -rather than streaming directly to the host PC. In this case, both -``start_recording`` and ``stop_recording`` initiate and end acquisition -to the on-board memory. To initiate a data transfer, the host calls -``start_readout`` which must be suitably implemented. The actual data -transfer happens either with ``grab`` or asynchronously. - - -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``. - - -``uca-grab`` -- grabbing frames -------------------------------- - -Grab with frames with :: - - $ uca-grab --num-frames=10 camera-model - -store them on disk as ``frames.tif`` if ``libtiff`` is installed, -otherwise as ``frame-00000.raw``, ``frame-000001.raw``. The raw format -is a memory dump of the frames, so you might want to use -`ImageJ <http://rsbweb.nih.gov/ij/>`__ to view them. You can also -specify the output filename or filename prefix with the ``-o/--output`` -option:: - - $ uca-grab -n 10 --output=foobar.tif camera-model - -Instead of reading exactly *n* frames, you can also specify a duration -in fractions of seconds:: - - $ uca-grab --duration=0.25 camera-model - - -``uca-camera-control`` -- simple graphical user interface ---------------------------------------------------------- - -Shows the frames and displays them on screen. Moreover, you can change -the camera properties in a side pane. - - -``uca-benchmark`` -- check bandwidth ------------------------------------- - -Measure the memory bandwidth by taking subsequent frames and averaging -the grabbing time: - -:: - - $ ./benchmark mock - # --- 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 - - -The GObject Tango device -======================== - -UcaDevice is a generic Tango Device that wraps ``libuca`` in order to -make libuca controlled cameras available as Tango devices. - - -Architecture ------------- - -UcaDevice is derived from GObjectDevice and adds libuca specific features like -start/stop recording etc. The most important feature is *acquisition control*. -UcaDevice is responsible for controlling acquisition of images from libuca. The -last aquired image can be accessed by reading attribute ``SingleImage``. -UcaDevice is most useful together with ImageDevice. If used together, UcaDevice -sends each aquired image to ImageDevice, which in turn does configured -post-processing like flipping, rotating or writing the image to disk. - - -Attributes -~~~~~~~~~~ - -Besides the dynamic attributes translated from libuca properties -UcaDevice has the following attributes: - -- ``NumberOfImages (Tango::DevLong)``: how many images should be - acquired? A value of -1 means unlimited *(read/write)* -- ``ImageCounter (Tango::DevULong)``: current number of acquired images - *(read-only)* -- ``CameraName (Tango::DevString)``: name of libuca object type - *(read-only)* -- ``SingleImage (Tango::DevUChar)``: holds the last acquired image - - -Acquisition Control -~~~~~~~~~~~~~~~~~~~ - -In UcaDevice acquisition control is mostly implemented by two -``yat4tango::DeviceTasks``: *AcquisitionTask* and *GrabTask*. -*GrabTask*'s only responsibility is to call ``grab`` on ``libuca`` -synchronously and post the data on to AcquisitionTask. - -*AcquisitionTask* is responsible for starting and stopping GrabTask and -for passing image data on to ``ImageDevice`` (if exisiting) and to -``UcaDevice`` for storage in attribute ``SingleImage``. It counts how -many images have been acquired and checks this number against the -configured ``NumberOfImages``. If the desired number is reached, it -stops GrabTask, calls ``stop_recording`` on ``libuca`` and sets the -Tango state to STANDBY. - - -Plugins -~~~~~~~ - -As different cameras have different needs, plugins are used for special -implementations. Plugins also makes UcaDevice and Tango Servers based on -it more flexible and independent of libuca implementation. - -* PCO: The Pco plugin implements additional checks when writing ROI values. -* Pylon: The Pylon plugin sets default values for ``roi-width`` and - ``roi-height`` from libuca properties ``roi-width-default`` and - ``roi-height-default``. - - -Installation ------------- - -Detailed installation depends on the manifestation of UcaDevice. All -manifestations depend on the following libraries: - -- YAT -- YAT4Tango -- Tango -- GObjectDevice -- ImageDevice - - -Build -~~~~~ - -:: - - export PKG_CONFIG_PATH=/usr/lib/pkgconfig - export PYLON_ROOT=/usr/pylon - export LD_LIBRARY_PATH=$PYLON_ROOT/lib64:$PYLON_ROOT/genicam/bin/Linux64_x64 - git clone git@iss-repo:UcaDevice.git - cd UcaDevice - mkdir build - cd build - cmake .. - make - - -Setup in Tango Database / Jive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before ``ds_UcaDevice`` can be started, it has to be registered manually -in the Tango database. With ``Jive`` the following steps are necessary: - -1. Register Server Menu *Tools* → Server Wizard Server name → ds\_UcaDevice - Instance name → my\_server *(name can be chosen freely)* Next Cancel - -2. Register Classes and Instances In tab *Server*: context menu on - ds\_UcaDevice → my\_server → Add Class Class: UcaDevice Devices: - ``iss/name1/name2`` Register server same for class ImageDevice - -3. Start server :: - - export TANGO_HOST=anka-tango:100xx - export UCA_DEVICE_PLUGINS_DIR=/usr/lib(64) - ds_UcaDevice pco my_server - -4. Setup properties for UcaDevice context menu on device → Device wizard - Property StorageDevice: *address of previously registered ImageDevice - instance* - -5. Setup properties for ImageDevice context menu on device → Device wizard - PixelSize: how many bytes per pixel for the images of this camera? - GrabbingDevice: *address of previously registered UcaDevice instance* - -6. Finish restart ds_UcaDevice - -FAQ ---- - -*UcaDevice refuses to start up...?* Most likely there is no instance -registered for class UcaDevice. Register an instance for this class and -it should work. - -*Why does UcaDevice depend on ImageDevice?* UcaDevice pushes each new -Frame to ImageDevice. Polling is not only less efficient but also prone -to errors, e.g. missed/double frames and so on. Perhaps we could use the -Tango-Event-System here! - -Open Questions, Missing Features etc. -------------------------------------- - -* *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 - ImageDevice to push a new frame on reception. A more convenient solution could - be using conventions for the device names, e.g. of the form - ``$prefix/$instance_name/uca`` and ``$prefix/$instance_name/image``. That way - we could get rid of the two Device-Properties and an easier installation - without the process of registering the classes and instances in ``Jive``. - -* *Why does UcaDevice dynamically link to GObjectDevice?* - - There is no good reason for it. Packaging and installing would be easier if we - linked statically to ``GObjectDevice`` because we would hide this dependency. - Having a separate ``GObjectDevice`` is generally a nice feature to make - ``GObjects`` available in Tango. However, there is currently no GObjectDevice - in use other than in the context of UcaDevice. - -* *Why must the plugin name be given as a command line parameter instead of a - Device-Property?* - - There is no good reason for it. UcaDevice would be easier to use, if the - plugin was configured in the Tango database as a Device-Property for the - respective server instance. + quickstart + cameras + api + tools + tango |