= Unified Camera Access =

[[TOC]]

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

== 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/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`       || C string || r || Name of camera ||
|| `UCA_PROP_WIDTH`      || `width`      || pixels   || r/w || Width of image to be taken ||
|| `UCA_PROP_WIDTH_MIN`  || `width.min`  || pixels   || r   || Minimum width of image to be taken ||
|| `UCA_PROP_WIDTH_MAX`  || `width.max`  || pixels   || r   || Maximum possible width ||
|| `UCA_PROP_HEIGHT`     || `height`     || pixels   || r/w || Height of image to be taken ||
|| `UCA_PROP_HEIGHT_MIN` || `height.min` || pixels   || r   || Minimum height of image to be taken ||
|| `UCA_PROP_HEIGHT_MAX` || `height.max` || pixels   || r   || Maximum possible height ||
|| `UCA_PROP_X_OFFSET`   || `offset.x`   || pixels   || r/w || Horizontal coordinate of start of ROI ||
|| `UCA_PROP_Y_OFFSET`   || `offset.y`   || pixels   || r/w || Vertical coordinate of start of ROI ||
|| `UCA_PROP_BITDEPTH`   || `bit-depth`  || bits     || r   || Bits per pixel ||
|| `UCA_PROP_EXPOSURE`     || `exposure`     || 10^-6^s    || r/w || Duration of image capture ||
|| `UCA_PROP_EXPOSURE_MIN` || `exposure.min` || 10^-6^s    || r   || Minimum duration of image capture ||
|| `UCA_PROP_EXPOSURE_MAX` || `exposure.max` || 10^-6^s    || r   || Maximum duration of image capture ||
|| `UCA_PROP_DELAY`        || `delay`        || 10^-6^s    || r/w || Delay before image capture ||
|| `UCA_PROP_DELAY_MIN`    || `delay.min`    || 10^-6^s    || r   || Minimum delay before image capture ||
|| `UCA_PROP_DELAY_MAX`    || `delay.min`    || 10^-6^s    || r   || Maximum delay before image capture ||
|| `UCA_PROP_TRIGGER_MODE` || `trigger-mode` || [#trigger see below] || r/w || Trigger mode for shutter opening ||
|| `UCA_PROP_FRAMERATE`    || `frame-rate`   || frames/s   || 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 =||= Access =||= Meaning =||
|| `UCA_PROP_TIMESTAMP_MODE`         || `timestamp-mode`            || [#timestamp bitmask (see below)] || r/w || Print a timestamp ||
|| `UCA_PROP_SCAN_MODE`              || `scan-mode`                 || [#scanmode see below] || r/w || Enable certain scan modes ||
|| `UCA_PROP_INTERLACE_SAMPLE_RATE`  || `interlace.sample-rate`     || 1–2^16^ || 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  || r/w || Row is classified as triggered, when more than `interlace-row-threshold` pixels trigger ||
|| `UCA_PROP_INTERLACE_ROW_THRESH`   || `interlace.threshold.row`   || rows    || r/w || Ignore row trigger when less than `interlace-row-threshold` rows trigger ||
|| `UCA_PROP_CORRECTION_MODE`        || `correction-mode`           || [#correction bitmask (see below)] || 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/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;
}
}}}