wiki:UnifiedCameraAccess

Version 8 (modified by Matthias Vogelgesang, 14 years ago) (diff)

--

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