= Unified Camera Access =

[[TOC]]

`libuca` is a thin wrapper to make the different cameras (via !CameraLink, PCIe, Thunderbolt …) accessible in an easy way. It builds support for cameras, when it can find the necessary dependencies, so there is no need to have camera SDKs installed when you don't own a camera. Right now `libuca` supports

* pco.imaging [http://www.pco.de/de/scmos-kameras/pcoedge/ pco.edge],
* photon focus [http://www.photonfocus.com/html/eng/products/products.php?prodId=39 MV2-D128-640-CL-8],
* Silicon Software [http://www.silicon-software.de/me4_vseries.html#_mE4_VD4-CL microEnable IV VD4-CL] and
* partially the IPE camera.

=== API documentation ===

Documentation for unstable versions can be generated with `make doc` if [http://www.doxygen.org Doxygen] is installed. It is also re-built nightly and located online at

* [http://ufo.kit.edu/extra/libuca/html API Manual and Reference]


== Specification of Properties ==

Properties of cameras are accessed in a vendor-neutral way by specifying the property names as defined in [http://ufo.kit.edu/ufo/browser/vogelgesang/libuca/src/uca.h uca.h]. The following list is the definite specification of basic properties that all devices must implement. If a property cannot be set or get via `uca_(get|set)_property()` the function shall return UCA_ERR_PROP_INVALID. The different implementations in `camera/uca_$MODEL.*` must make sure, that units and types are correctly converted and cast.

||= Property Name =||= Property String =||= Unit =||= Type =||= Access =||= Meaning =||
|| `UCA_PROP_NAME`       || `name`       || string   || C-String || r || Name of camera ||
|| `UCA_PROP_WIDTH`      || `width`      || pixels   || uint32_t || r/w || Width of image to be taken ||
|| `UCA_PROP_WIDTH_MIN`  || `width.min`  || pixels   || uint32_t || r   || Minimum width of image to be taken ||
|| `UCA_PROP_WIDTH_MAX`  || `width.max`  || pixels   || uint32_t || r   || Maximum possible width ||
|| `UCA_PROP_HEIGHT`     || `height`     || pixels   || uint32_t || r/w || Height of image to be taken ||
|| `UCA_PROP_HEIGHT_MIN` || `height.min` || pixels   || uint32_t || r   || Minimum height of image to be taken ||
|| `UCA_PROP_HEIGHT_MAX` || `height.max` || pixels   || uint32_t || r   || Maximum possible height ||
|| `UCA_PROP_X_OFFSET`   || `offset.x`   || pixels   || uint32_t || r/w || Horizontal coordinate of start of ROI ||
|| `UCA_PROP_Y_OFFSET`   || `offset.y`   || pixels   || uint32_t || r/w || Vertical coordinate of start of ROI ||
|| `UCA_PROP_BITDEPTH`   || `bit-depth`  || bits     || uint8_t  || r   || Bits per pixel ||
|| `UCA_PROP_EXPOSURE`     || `exposure`     || 10^-6^s    || uint32_t || r/w || Duration of image capture ||
|| `UCA_PROP_EXPOSURE_MIN` || `exposure.min` || 10^-9^s    || uint32_t || r   || Minimum duration of image capture ||
|| `UCA_PROP_EXPOSURE_MAX` || `exposure.max` || 10^-3^s    || uint32_t || r   || Maximum duration of image capture ||
|| `UCA_PROP_DELAY`        || `delay`        || 10^-6^s    || uint32_t || r/w || Delay before image capture ||
|| `UCA_PROP_DELAY_MIN`    || `delay.min`    || 10^-9^s    || uint32_t || r   || Minimum delay before image capture ||
|| `UCA_PROP_DELAY_MAX`    || `delay.min`    || 10^-3^s    || uint32_t || r   || Maximum delay before image capture ||
|| `UCA_PROP_TRIGGER_MODE` || `trigger-mode` || [#trigger see below] || uint8_t || r/w || Trigger mode for shutter opening ||
|| `UCA_PROP_FRAMERATE`    || `frame-rate`   || frames/s   || uint32_t || r   || Current number of frames per second ||

The following table lists special properties that are ignored (and also flagged with an `UCA_ERR_PROP_INVALID` return value) by cameras that don't support them:

||= Property Name =||= Property String =||= Unit =||= Type =||= Access =||= Meaning =||
|| `UCA_PROP_TIMESTAMP_MODE`         || `timestamp-mode`            || [#timestamp bitmask (see below)] || uint8_t || r/w || Print a timestamp ||
|| `UCA_PROP_SCAN_MODE`              || `scan-mode`                 || [#scanmode see below] || uint8_t || r/w || Enable certain scan modes ||
|| `UCA_PROP_INTERLACE_SAMPLE_RATE`  || `interlace.sample-rate`     || 1–2^16^ || uint32_t || r/w || Take only every `interlace-sample-rate` rows into account for the Fast-Reject algorithm ||
|| `UCA_PROP_INTERLACE_PIXEL_THRESH` || `interlace.threshold.pixel` || pixels  || uint32_t || r/w || Row is classified as triggered, when more than `interlace-row-threshold` pixels trigger ||
|| `UCA_PROP_INTERLACE_ROW_THRESH`   || `interlace.threshold.row`   || rows    || uint32_t || r/w || Ignore row trigger when less than `interlace-row-threshold` rows trigger ||
|| `UCA_PROP_CORRECTION_MODE`        || `correction-mode`           || [#correction bitmask (see below)] || uint8_t || r/w || Enable/disable certain correction modes ||

=== Values ===

==== `UCA_PROP_TIMESTAMP_MODE` (boolean combinations possible) ==== #timestamp

||= Timestamp bit =||= Meaning =||
|| UCA_TIMESTAMP_BINARY || Binary encoded timestamp ||
|| UCA_TIMESTAMP_ASCII  || Human-readable ASCII timestamp ||


==== `UCA_PROP_SCANMODE_MODE` ==== #scanmode

||= Scan mode =||= Meaning =||
|| UCA_SCANMODE_FAST || Higher pixel clock, less bits ||
|| UCA_SCANMODE_SLOW || Standard ||

==== `UCA_PROP_TRIGGER_MODE` ==== #trigger

||= Trigger Name =||= Meaning =||
|| `UCA_TRIGGER_AUTO` || Free run mode ||
|| `UCA_TRIGGER_INTERNAL` || Trigger via !CameraLink interface ||
|| `UCA_TRIGGER_EXTERNAL` || Trigger via external hardware ||

==== `UCA_PROP_CORRECTION_MODE` (boolean combinations possible) ==== #correction

||= Correction bit =||= Meaning =||
|| `UCA_CORRECT_OFFSET`   || Remove static fixed-pattern noise using a black-reference image ||
|| `UCA_CORRECT_HOTPIXEL` || Interpolate marked hot pixels as average of surrounding pixels  ||
|| `UCA_CORRECT_GAIN`     || Apply correction to each pixel for linear behaviour ||


== Code ==

Followingly, we will build libpco (the hardware-dependent pco.edge "driver") and libuca. First of all, get the sources
{{{
#!sh
cd some-empty-dir
bzr clone bzr+ssh://user@ufo.kit.edu/vogelgesang/libpco
bzr clone bzr+ssh://user@ufo.kit.edu/vogelgesang/libuca
}}}

Make sure, that you have installed the Silicon Software [http://www.silicon-software.de/download.html Runtime Environment]. Then build and install libpco using
{{{
#!sh
mkdir build && cd build
cmake ../libpco
make && sudo make install
}}}
If everything went okay, you can try the `diagnose` program in the build directory. It tries to open the camera and frame grabber, prints out some information and stores one frame as `out.raw`.

Finally, you can build libuca
{{{
#!sh
rm -rf *
cmake ../libuca
make
}}}

== Using libuca ==

The following test program is supplied with `libuca` and demonstrates the general functionality of the library:

{{{
#!c
#include <stdio.h>
#include <stdlib.h>
#include "uca.h"
#include "uca-cam.h"

int main(int argc, char *argv[])
{
    struct uca_t *uca = uca_init();
    if (uca == NULL)
        return 1;

    /* take first camera */
    struct uca_camera_t *cam = uca->cameras;

    uint32_t val = 5000;
    cam->set_property(cam, UCA_PROP_EXPOSURE, &val);
    val = 0;
    cam->set_property(cam, UCA_PROP_DELAY, &val);

    uint32_t width, height;
    cam->get_property(cam, UCA_PROP_WIDTH, &width);
    cam->get_property(cam, UCA_PROP_HEIGHT, &height);

    uca_cam_alloc(cam, 20);
    uint16_t *buffer = (uint16_t *) malloc(width * height * 2);

    cam->start_recording(cam);
    cam->grab(cam, (char *) buffer);
    cam->stop_recording(cam);
    uca_destroy(uca);

    FILE *fp = fopen("out.raw", "wb");
    fwrite(buffer, width*height, 2, fp);
    fclose(fp);

    free(buffer);
    return 0;
}
}}}


== Milestones ==

||= Version =||= Anticipated Date =||= Release Date =||= Features =||
|| 0.1.0 rev 34 || ~~03/02/11~~ || 03/02/11 ||Stable camera and camera access API ||
|| 0.2.0 rev 38 || ~~03/03/11~~ || 03/04/11 || Frame acquisition ||
|| 0.3.0 rev 96 || ~~03/04/11~~ ||03/22/11 || Full integration of pco.edge and Photon Focus ||
|| 0.3.1 rev 117 || ~~04/26/11~~ || 04/26/11 || Bug fixes ||
|| 0.4.0 rev 151 || ~~12/15/11~~ || 12/15/11 || Bug fixes, API break, pco.dimax and pco.4000 support ||

From version 1.0.0 on, the old Linux way of version numbering is used. That means odd-numbered minor versions are development releases and even-numbered minor versions are stable releases.