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 ​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

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 ​Runtime Environment. Then build and install libpco using

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

rm -rf *
cmake ../libuca
make

Using libuca

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

#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;
}