= Unified Camera Access =

`libuca` is a thin wrapper to make the different cameras (via !CameraLink or PCIe) accessible in an easy way.

== Specification ==

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/uca/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.

||= Property Name =||= Property String =||= Unit =||= Access =||= Meaning =||
|| UCA_PROP_NAME       || `name`       || null-terminated C string || r || Name of camera ||
|| UCA_PROP_WIDTH      || `width`      || pixels         || r/w || Width of image to be taken ||
|| UCA_PROP_HEIGHT     || `height`     || pixels         || r/w || Height of image to be taken ||
|| UCA_PROP_X_OFFSET   || `x-offset`   || pixels         || r/w || Horizontal coordinate of start of ROI ||
|| UCA_PROP_Y_OFFSET   || `y-offset`   || pixels         || r/w || Vertical coordinate of start of ROI ||
|| UCA_PROP_MAX_WIDTH  || `max-width`  || pixels         || r   || Maximum possible width ||
|| UCA_PROP_MAX_HEIGHT || `max-height` || pixels         || r   || Maximum possible height ||
|| UCA_PROP_BITDEPTH   || `bit-depth`  || number of bits || r   || Bits per pixel ||
|| UCA_PROP_EXPOSURE   || `exposure`   || microseconds   || r/w || Duration of image capture ||
|| UCA_PROP_DELAY      || `delay`      || microseconds   || r/w || Delay before image capture ||
|| UCA_PROP_FRAMERATE  || `frame-rate` || frames per second || r || Current number of frames per second ||
|| UCA_PROP_TRIGGERMODE || `trigger-mode` || see below || r/w || Trigger mode for shutter opening ||

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 =||= Access =||= Meaning =||
|| UCA_PROP_INTERLACE_SAMPLE_RATE  || `interlace-sample-rate`     || integer quantity || r/w || Take only every `interlace-sample-rate` rows into account for the Fast-Reject algorithm ||
|| UCA_PROP_INTERLACE_PIXEL_THRESH || `interlace-pixel-threshold` || number of pixels || r/w || Row is classified as triggered, when more than `interlace-row-threshold` pixels trigger ||
|| UCA_PROP_INTERLACE_ROW_THRESH   || `interlace-row-threshold`   || number of rows   || r/w || Ignore row trigger when less than `interlace-row-threshold` rows trigger ||
|| UCA_PROP_CORRECTION_MODE        || `correction-mode`           || 32-bit bitmask (see below) || r/w || Enable/disable certain correction modes ||

A camera may use different trigger signals to start exposure via `UCA_PROP_TRIGGERMODE`. Possible values are:

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

The following correction modes and combinations of them can be applied

||= 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/pco-diag libpco
bzr clone bzr+ssh://user@ufo.kit.edu/vogelgesang/uca 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 "uca.h"

int main(int argc, char *argv[])
{
    struct uca_t *uca = uca_init();
    if (uca == NULL) {
        printf("Couldn't find a camera\n");
        return 1;
    }

    uint32_t width = 800, height = 600;
    uca->cam_set_property(uca, UCA_PROP_WIDTH, &width);
    uca->cam_set_property(uca, UCA_PROP_HEIGHT, &height);

    char camera_name[256] = "foobar";
    uca->cam_get_property(uca, UCA_PROP_NAME, camera_name);

    printf("Camera name: %s\n", camera_name);

    uca_destroy(uca);
    return 0;
}
}}}