Unified Camera Access

TOC?

libuca is a thin wrapper to make the different cameras (via CameraLink, PCIe, Thunderbolt …) accessible in an easy way. It builds support for cameras, when it can find the necessary dependencies, so there is no need to have camera SDKs installed when you don't own a camera.

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. The different implementations in camera/uca_$MODEL.* must make sure, that units and types are correctly converted and cast.

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

int main(int argc, char *argv[])
{
    struct uca_t *uca = uca_init();
    if (uca == NULL)
        return 1;

    /* take first camera */
    struct uca_camera_t *cam = uca->cameras;

    uint32_t val = 5000;
    cam->set_property(cam, UCA_PROP_EXPOSURE, &val);
    val = 0;
    cam->set_property(cam, UCA_PROP_DELAY, &val);

    uint32_t width, height;
    cam->get_property(cam, UCA_PROP_WIDTH, &width);
    cam->get_property(cam, UCA_PROP_HEIGHT, &height);

    uca_cam_alloc(cam, 20);
    uint16_t *buffer = (uint16_t *) malloc(width * height * 2);

    cam->start_recording(cam);
    cam->grab(cam, (char *) buffer);
    cam->stop_recording(cam);
    uca_destroy(uca);

    FILE *fp = fopen("out.raw", "wb");
    fwrite(buffer, width*height, 2, fp);
    fclose(fp);

    free(buffer);
    return 0;
}

Milestones

Version	Anticipated Date	Features
0.1.0	03/02/11	Stable camera and camera access API
0.2.0	03/03/11	Frame acquisition
0.3.0	03/04/11	Full integration of pco.edge
0.4.0	03/10/11	Full integration of Photon Focus
1.0.0	03/30/11	First stable release
1.x.0	mid April	Full integration of IPE camera

From version 1.0.0 on, the old Linux way of version numbering is used. That means odd-numbered minor versions are development releases and even-numbered minor versions are stable releases.