Programming with Real-Time Images

One of the main features of the RTD widget is the ability to display real-time images. These images are typically coming from an aquisition system that controls a CCD camera or other kind of detectors such as the DCS (Detector Control Software). This section describes how programmers providing such real-time images can interface to the RTD and display their images.

As already described in the architecture overview, the real-time image must be provided in shared memory by the aquisition system. This means that the aquisition system is the creator and owner of the shared memory segment (see also shmget(2) , shmctl(2) , shmat(2) ) .

To interface with the RTD widget, the library rtdImgEvt is provided with the following functions:

Routine	Description
rtdInitImageEvt	Register to rtdServer, usually as a camera identified by a unique name.
rtdSendImageInfo	Send image event to rtdServer.
rtdRecvImageInfo	Receive an image event from rtdServer (normally used only by the RTD widget).
rtdAttachImageEvt	Subscribe for event notification from rtdServer (normally used only by the RTD widget).
rtdDetachImageEvt	Unsubscribe for event notification from rtdServer.
rtdClose	Close connection to rtdServer.

The basic idea is that an application providing real time images, such as DCS, uses rtdInitImageEvt () to identify itself to the rtdServer, for example.:

 
#include "rtd/rtdImageEvent.h" 
rtdIMAGE_EVT_HNDL  eventHndl; 
if (rtdInitImageEvt("myCamera",&eventHndl,NULL) == RTD_ERROR){ 
        printf("Could not initialize image event !\n"); 
        usage(); 
}

After this call, a camera source named " myCamera " is registered with the rtdServer. The handle returned of type rtdIMAGE_EVT_HNDL is a handle needed for subsequent calls to rtdImgEvt functions.

When the camera source has a new image ready in shared memory, the structure rtdIMAGE_INFO describing the image must be prepared. rtdIMAGE_INFO contains of following fields (Any unused fields should be set to 0, see memset(3)).:

Member	Description
char version	Protocol version (filled by rtdSendImageInfo)
char frameId	Rapid frame identifier. 0 means normal image. 1 and above identifies the the image is a rapid frame.
char dataType	Defined in the rtdIMAGE_TYPE enumeration: BYTE, SHORT, XIMAGE, SHORT, USHORT, INT, FLOAT, DOUBLE. XIMAGE means that the image provided already has been color scaled.
char bytePerPixel	Number of bytes used per pixel.
int shmId	ID for the shared memory block
short frameX, short frameY	X,Y offsets of the image frame in the canvas (used only for rapid frames and should otherwise be set to 0).
short xPixels	Pixels in horisontal direction (equals the width of the image).
short yPixels	Pixels in vertical direction (equals the height of the image)
short blockLines	If different from 0, block mode is applied. Block mode means that only a small part of the image changed and the rtd widget only has to update a fraction of the image (currently not implemented).
short blockOffset	Y offset on image (currently not implemented).
int highCut	High cut level as set by the aquisition system.
int lowCut	Low cut level as set by the aquisition system.
short binningX	Binning factor applied on image
short binningY	Binning factor applied on image.
struct timeval timeStamp	UTC time when image was aquired.

The following fields were added to support World Coordinates Set all fields to 0 if World Coordinates are not supported

`Member`	`Description`
double ra	Center right ascension in degrees
`double dec`	Center declination in degrees
`double secpix`	Number of arcseconds per pixel
`double xrefpix`	Reference pixel X coordinate
`double yrefpix`	Reference pixel Y coordinate
`double rotate`	Rotation angle (clockwise positive) in degrees
`int equinox`	Equinox of coordinates, 1950 and 2000 supported
`double epoch`	Epoch of coordinates, used for FK4/FK5 conversion, no effect if 0
char proj[8]	Projection: one of: "-SIN", "-TAN", "-ARC", "-NCP", "-GLS", "-MER", "-AIT", "-STG", "PLATE", "LINEAR", "PIXEL", ... (as supported by the wcs library: wcssubs, from Doug Mink)

The following fields were added to support image synchronization

`Member`	`Description`
int semId	ID of semaphore set
`int shmNum`	Number of semaphore in the set
`int reserved[10]`	reserved for future use

These fields were added to support detector " chip " coordinates for real-time images. The chip origin is assumed by be at lower left, as for FITS.

`Member`	`Description`
`short startx short starty`	First window pixel in the X (Y) direction within the detector physical system.

The image event is forwarded with the function rtdSendImageInfo to the rtdServer. The fields marked as bold are mandatory and must have a value in order to display the image.

In order for rtd clients (rtd widget applications) to receive the event, they must first attach to the camera source, which in this case is " myCamera ". As an example of an application the rtd demo application can be used, for example :

rtd -camera myCamera

and from the real time menu select " Attach Camera ". For more information on the functions mentioned above please refer to the man pages. And remember if you program with shared memory images to delete them when they are no longer needed (such as when your aquisition system exits).

The RTD include files and libraries are normally installed in $ prefix /include and $ prefix /lib, which must be added to the path in the Makefile (For the VLT, $ prefix is normally set to /vlt/dflow . The default is /usr/local ). $

 
RTD_LIB=-L$(PREFIX)/lib -lrtd  
RTD_INCLUDE=-I$(PREFIX)/include

Multi-buffering and Semaphore Locking of Shared Memory