From bf641d06c522b86213b28640e85dc6e483a70cbd Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Fri, 31 Aug 2012 16:47:21 +0200 Subject: Extend section on new camera integration --- docs/manual.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 69abae8..0373010 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -381,6 +381,31 @@ 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. + [sub-classing]: http://developer.gnome.org/gobject/stable/howto-gobject.html -- cgit v1.2.3 From 7e4637741be0cdb0fd3e53bb779df649cee59374 Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Wed, 19 Sep 2012 18:25:22 +0200 Subject: Update documentation --- docs/manual.md | 43 ++++++++++++++----------------------------- 1 file changed, 14 insertions(+), 29 deletions(-) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 69abae8..584da8f 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -107,6 +107,7 @@ necessary header files: ~~~ {.c} #include +#include #include ~~~ @@ -116,6 +117,7 @@ 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 */ @@ -124,10 +126,12 @@ main (int argc, char *argv[]) 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][]: +supported by [libpco][]. To instantiate a camera we have to create a plugin +manager first: ~~~ {.c} - camera = uca_camera_new ("pco", &error); + manager = uca_plugin_manager_new (); + camera = uca_plugin_manager_new_camera (manager, "pco", &error); ~~~ Errors are indicated with a returned value `NULL` and `error` set to a value @@ -252,38 +256,19 @@ communicate with the camera. Now we will go into more detail. 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_camera_get_types`: +`uca_plugin_manager_get_available_cameras`: ~~~ {.c} - gchar **types; + GList *types; - types = uca_camera_get_types (); + types = uca_camera_get_available_cameras (manager); - for (guint i = 0; types[i] != NULL; i++) - g_print ("%s\n", types[i]); + for (GList *it = g_list_first; it != NULL; it = g_list_next (it)) + g_print ("%s\n", (gchar *) it->data); - /* free the string array */ - g_strfreev (types); -~~~ - -If you _know_ which camera you want to use you can instantiate the sub-classed -camera object directly. In this case we create a pco-based camera: - -~~~ {.c} -#include -#include - -int -main (int argc, char *argv[]) -{ - UcaPcoCamera *camera; - GError *error = NULL; - - g_type_init (); - camera = uca_pco_camera_new (&error); - g_object_unref (camera); - return 0; -} + /* free the strings and the list */ + g_list_foreach (types, (GFunc) g_free, NULL); + g_list_free (types); ~~~ [last section]: #first-look-at-the-api -- cgit v1.2.3 From e5ff011119ac42e48f3f3521b789a18bdfdfb51e Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Fri, 21 Sep 2012 19:24:36 +0200 Subject: Add documentation generator and mock docs --- docs/manual.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 5600d3f..cff6f18 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -245,6 +245,12 @@ The following cameras are supported: * Pylon * UFO Camera developed at KIT/IPE. +## Property documentation + +* [mock][mock-doc] + +[mock-doc]: mock.html + # More API -- cgit v1.2.3 From b60398963a2072115675f732e7d38d99205e8c9a Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Wed, 26 Sep 2012 14:26:29 +0200 Subject: Add change log to manual --- docs/manual.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index cff6f18..19eacca 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -442,3 +442,6 @@ grabbing time: # The GObject Tango device [TODO: Get more information from Volker Kaiser and/or Mihael Koep] + + +# Changes -- cgit v1.2.3 From 0bc642a31600bbfaac15779b8d932a409283ae3f Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Wed, 26 Sep 2012 14:51:14 +0200 Subject: Generalized log generation --- docs/manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 19eacca..91935cc 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -444,4 +444,4 @@ grabbing time: [TODO: Get more information from Volker Kaiser and/or Mihael Koep] -# Changes +# ChangeLog -- cgit v1.2.3 From 4e78a33ab00c8437d341a4cb83919e2a67e54493 Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Mon, 8 Oct 2012 10:04:18 +0200 Subject: Generate documentation for the base camera object --- docs/manual.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 91935cc..0fe4cca 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -247,8 +247,10 @@ The following cameras are supported: ## Property documentation +* [Basic camera properties][base-doc] * [mock][mock-doc] +[base-doc]: base.html [mock-doc]: mock.html -- cgit v1.2.3 From 1716926f5c36a89cb00c900160629110657638b1 Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Mon, 8 Oct 2012 16:05:19 +0200 Subject: Add packages and bindings sections --- docs/manual.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 47 insertions(+), 4 deletions(-) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 0fe4cca..5162ddf 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -12,7 +12,18 @@ 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. -## Building 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 @@ -38,7 +49,8 @@ repository][repo], you also need Git: [repo]: http://ufo.kit.edu/repos/libuca.git/ -### Fetching the sources + +#### Fetching the sources Untar the distribution @@ -54,7 +66,7 @@ and create a new, empty build directory inside: mkdir build -### Configuring and building +#### 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: @@ -86,7 +98,7 @@ 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 +#### Building this manual Make sure you have [Pandoc][] installed. With Debian/Ubuntu this can be achieved with @@ -367,6 +379,37 @@ setup_async (UcaCamera *camera) } ~~~ + +# Bindings + +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: + +~~~ {.python} +from gi.repository import Uca + +pm = Uca.PluginManager() + +# List all cameras +print(pm.get_available_cameras()) + +# Load a camera +cam = pm.get_camera('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. + + # Integrating new cameras A new camera is integrated by [sub-classing][] `UcaCamera` and implement all -- cgit v1.2.3 From 6b82a9a175c92c39f25e9b5965b2e9f5c35f65c2 Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Thu, 11 Oct 2012 17:48:48 +0200 Subject: Update API call --- docs/manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 5162ddf..8bf38aa 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -143,7 +143,7 @@ manager first: ~~~ {.c} manager = uca_plugin_manager_new (); - camera = uca_plugin_manager_new_camera (manager, "pco", &error); + camera = uca_plugin_manager_get_camera (manager, "pco", &error); ~~~ Errors are indicated with a returned value `NULL` and `error` set to a value -- cgit v1.2.3 From e16087fbe25df8901e9221602570c074ae887450 Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Thu, 18 Oct 2012 11:59:24 +0200 Subject: Add pco property documentation --- docs/manual.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 8bf38aa..a68400e 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -260,9 +260,11 @@ The following cameras are supported: ## Property documentation * [Basic camera properties][base-doc] +* [pco][pco-doc] * [mock][mock-doc] [base-doc]: base.html +[pco-doc]: pco.html [mock-doc]: mock.html -- cgit v1.2.3