Camera API Technical Report:
The Camera Library

The Camera Library

The underlying design of the camera library is that a camera is a complex object which can only be accessed via functions to return or set attributes or to return image values. I would suggest that the easiest way of handling this is have a complete set of camera independent functions that act as links to specific functions. So as to mimic the OOP style I suggest that the camera dependent functions are all part of the individual camera ``class'' structure and so the camera library is simply dereferencing functions. This avoids case statements and the need to modify old code when installing a new camera.

I think we should cover all modes of access, individual attribute by attribute setting and single ``block'' node setting. A suitable model for the block mode is provided by X11 XSetWindowAttributes, the single attribute mode is simple a list of functions. Typically the set functions will return an error status and the get functions will return a value. Errors in the get functions will be flagged by returning an impossible value. If and error has occurred then a global error_number and error_string will be set to enable condition handling and some form of output to the user, maybe these should be returned by a function so that they are not global, alternatively there could be an error-handling function which is user settable. Included in the attribute setting there will be geometry and exposure constraint functions.

In addition to attribute functions we will need read_image, capture_image (for video and multi-resolution options), initialise_camera (open), write_camera (to file), read_camera (from file) and close_camera. To enable run-time selection of the available cameras there will need to be a function to return the available camera list - names, initialisation functions and initialisation strings. Application code will include function definitions via camera.h, camera library code will also need a private include file to give all the structure definitions that should be opaque to the user. Maybe the structures should be Xt fashion and in blocks corresponding to the widget hierarchy. The rest of this document is a possible outline for the header files and the library function stubs.

I have implemented an example library which knows about the iim camera device. What follows is a description of the code, and examples of its use. The user has two means of getting access to a particular camera. The first is to include the file camera.h and use the CameraGetList() procedure to return the list of cameras supported by the library (the user must then test each camera to see if it is present on the current host). The second is to include the specific camera include file cam_iim.h and use the camera class pointer and camera record declared there. Note the camera class is an opaque pointer and can only be used as an argument to some of the camera library procedures. The same is true of the camera pointer returned by CameraInit()

The basic design of the library is that the user only sees an opaque pointer to a camera object. To access attributes of the camera or read in data it is necessary to use one of the access functions. The most general access functions are CameraSetVal(), CameraGetVal() and CameraCheckVal() which set, get and check any particular attribute. The check function will return the nearest legal value for a particular attribute. Many of the attributes have convenience routines to return values often used CameraWinX().

Data is read from the camera in an analogous fashion to the unix read. The user must provide a data buffer of sufficient size then call CameraRead(). The camera library is completely independent of woolz and therefore there are no routines that return a woolz object. These should be provided by a separate library.

Errors are reported via an error handler for which the default is simply to write a message to stderr. The error handler can by set or removed by the user and typically on an X11 display will be replaced by a procedure to popup a message window.

To make the maintenance of a ``control panel'' display easier in a windows environment there is also provision for a callback function whenever an attribute is set. This means that separate parts of a large program can change camera parameters without having to worry about updating the camera controls interface, this updating is handled by the callback function. The default callback does nothing.