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 ​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-6s	r/w	Duration of image capture
UCA_PROP_EXPOSURE_MIN	exposure.min	10-6s	r	Minimum duration of image capture
UCA_PROP_EXPOSURE_MAX	exposure.max	10-6s	r	Maximum duration of image capture
UCA_PROP_DELAY	delay	10-6s	r/w	Delay before image capture
UCA_PROP_DELAY_MIN	delay.min	10-6s	r	Minimum delay before image capture
UCA_PROP_DELAY_MAX	delay.min	10-6s	r	Maximum delay before image capture
UCA_PROP_TRIGGER_MODE	trigger-mode	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	bitmask (see below)	r/w	Print a timestamp
UCA_PROP_SCAN_MODE	scan-mode	see below	r/w	Enable certain scan modes
UCA_PROP_INTERLACE_SAMPLE_RATE	interlace.sample-rate	1–216	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	bitmask (see below)	r/w	Enable/disable certain correction modes

Values

UCA_PROP_TIMESTAMP_MODE (boolean combinations possible)

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

UCA_PROP_SCANMODE_MODE

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

UCA_PROP_TRIGGER_MODE

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