diff options
| -rw-r--r-- | docs/Makefile | 22 | ||||
| -rw-r--r-- | docs/manual.md | 261 | ||||
| -rw-r--r-- | src/uca-docs.xml.in | 24 |
3 files changed, 283 insertions, 24 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..f92bfc9 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,22 @@ +PANDOC=$(shell which pandoc) +MD2PDF=$(shell which markdown2pdf) +OPTS=-s --smart + +all: pdf html + +pdf: manual.pdf + +html: manual.html + +clean: + rm -f manual.pdf manual.html + +manual.pdf: manual.md + $(MD2PDF) -o manual.pdf manual.md + +manual.html: manual.md + $(PANDOC) $(OPTS) manual.md -o manual.html + +ifeq ($(PANDOC),) + $(warning Pandoc not found!) +endif diff --git a/docs/manual.md b/docs/manual.md new file mode 100644 index 0000000..00e19fc --- /dev/null +++ b/docs/manual.md @@ -0,0 +1,261 @@ +% libuca -- A Unified Camera Access Interface +% Matthias Vogelgesang [matthias.vogelgesang@kit.edu] + +libuca is a light-weight camera abstraction library, focused on scientific +cameras used at the ANKA synchrotron. + +# Quickstart + +## Installation + +Before installing `libuca` itself, you should install any drivers and SDKs +needed to access the cameras you want to access through `libuca`. + +## 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. With Debian/Ubuntu this should be enough: + + sudo apt-get install libglib2.0 cmake gcc + +In case you want to use the graphical user interface you also need the Gtk+ +development libraries: + + sudo apt-get install libgtk+2.0-dev + +If you want to build the most recent version fresh from the [Git +repository][repo], you also need Git: + + sudo apt-get install git + +[repo]: http://ufo.kit.edu/repos/libuca.git/ + +### 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 .. -DCMAKE_INSTALL_PREFIX=/usr -DLIB_SUFFIX=64 + +The former tells CMake to install into `/usr` instead of `/usr/local` and the +latter that 64 should be appended to any library paths. This is necessary on +Linux distributions that expect 64-bit libraries in `/usr[/local]/lib64`. + + +### Building this manual + +Make sure you have [Pandoc][] installed. With Debian/Ubuntu this can be achieved +with + + sudo apt-get install pandoc + +Once done, go into `docs/` and type + + make [all|pdf|html] + +[Pandoc]: http://johnmacfarlane.net/pandoc/ + + +## First look at the API + +The API for accessing cameras is straightforward. First you need to include the +necessary header files: + +~~~ {.c} +#include <glib-object.h> +#include <uca-camera.h> +~~~ + +Then you need to setup the type system: + +~~~ {.c} +int +main (int argc, char *argv[]) +{ + 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][]: + +~~~ {.c} + camera = uca_camera_new ("pco", &error); +~~~ + +Errors are indicated with a returned value `NULL` and `error` set to a value +other than `NULL`: + +~~~ {.c} + if (camera == NULL) { + g_error ("Initialization: %s", error->message); + return 1; + } +~~~ + +You should always remove the [reference][gobject-references] from the camera +object when not using it in order to free all associated resources: + +~~~ {.c} + g_object_unref (camera); + return 0; +} +~~~ + +Compile this program with + + cc `pkg-config --cflags --libs libuca glib-2.0` foo.c -o foo + +[libpco]: http://ufo.kit.edu/repos/libpco.git/ +[gobject-references]: http://developer.gnome.org/gobject/stable/gobject-memory.html#gobject-memory-refcount + +### Grabbing frames + +To synchronously grab frames, first start the camera: + +~~~ {.c} + uca_camera_start_recording (camera, &error); + g_assert_no_error (error); +~~~ + +Now you have two options with regard to memory buffers. If you already have a +suitable sized buffer, just pass it to `uca_camera_grab`. Otherwise pass a +pointer pointing to `NULL` (this is different from a `NULL` pointer!). In this +case memory will be allocated for you: + +~~~ {.c} + gpointer buffer_1 = NULL; /* A pointer pointing to NULL */ + gpointer buffer_2 = g_malloc0 (640 * 480 * 2); + + /* Memory will be allocated. Remember to free it! */ + uca_camera_grab (camera, &buffer_1, &error); + + /* Memory buffer will be used */ + uca_camera_grab (camera, &buffer_2, &error); +~~~ + + +### 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: + +~~~ {.c} + 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`: + +~~~ {.c} + guint roi_width = 512; + gdouble exposure_time = 0.001; + + g_object_set (G_OBJECT(camera), + "roi-width", roi_width, + "exposure-time", exposure_time, + NULL); +~~~ + +Several essential camera parameters _must_ be implemented by all cameras. To get +a list of them consult the API reference for `UcaCamera`. For camera specific +parameters you need to consult the corresponding API reference for +`UfoFooCamera`. + + +# 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`. + +## `grab` -- grabbing frames + +Grab with frames with + + $ ./grab camera-model + +store them on disk as `frame-00000.raw`, `frame-000001.raw` ... and measure the +time to take them. The raw format is not format but a memory dump of the +buffers, so you might want to use [ImageJ][] to view them. + +[ImageJ]: http://rsbweb.nih.gov/ij/ + +## `control` -- simple graphical user interface + +Shows the frames and displays them on screen. Moreover, you can change the +camera properties in a side pane. + +## `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 + +# Integrating a new camera diff --git a/src/uca-docs.xml.in b/src/uca-docs.xml.in index 60bcf57..43a830d 100644 --- a/src/uca-docs.xml.in +++ b/src/uca-docs.xml.in @@ -18,30 +18,6 @@ <title>Unified Camera Access</title> <xi:include href="xml/uca-camera.xml"/> ${_xml_doc_input} - - </chapter> - - <chapter id="howto-add-camera"> - <title>How to add a new camera</title> - - <para> - Adding a new camera involves three steps: - <itemizedlist> - <listitem><para>Subclass from <link linkend="UcaCamera">UcaCamera</link> and implement all necessary methods - to start and stop recording, to grab frames and override and - add properties that are special to your - camera.</para></listitem> - <listitem><para>Adapt <filename>src/CMakeLists.txt</filename>, so - that your dependencies are detected and your source files - are added to the <literal>uca_SRCS</literal> CMake - variable. Furthermore you must add an entry to - <filename>src/config.h.in</filename> that reflects the - CMake option variable</para></listitem> - <listitem><para>Change <filename>src/uca-camera.c</filename> - and add a new (guarded) entry to the factory as well - as necessary include files.</para></listitem> - </itemizedlist> - </para> </chapter> <index id="api-index-full"> |