These functions are used to get the value of various features of the camera, the information about the ISO channel, trigger mode, frame rate, format and mode. The functions contain get or query in their names.

For example,

int dc1394_get_gamma (raw1394handle_t handle, node_t node, unsigned
int *gamma)

gets the value of the gamma attribute for the camera.

Most of the get functions take a minimum of three parameters:

If we try to trace the flow of the function call, we can understand what actually happens:

Figure 1. Flow of get function call

In case the get function you called is meant to retrieve the value of a camera feature (the value for the parameters listed in feature enumeration), that get function will call another get function (GetFeatureValue), which takes the enumeration value of the feature as input. For example, in the case of gamma value, the function passes 422 as the value (this value can be calculated from the enumeration given in the dc1394_control.h file).

Ultimately, the GetCameraControlRegister function, whose task is to get the value from the appropriate control registers, is called. This functions takes the offset value (octlet_t offset), which is the offset from the base register as the input to its call. The function prototype is declared in dc1394_internal.h.

GetCameraControlRegister (raw1394handle_t handle, nodeid_t node,
                         octlet_t offset, quadlet_t *value)

The above will store the final result in the value.

The GetCameraControlRegister function will in turn call dc1394_get_camera_info() to get the address of the base register:

camera->ccr_base = CONFIG_ROM_BASE + info->ccr_offset;

Once the base register and the offset is known, raw1394_read() is called by GetCameraControlRegister to read the actual values.

Now the get function (dc1394_get_gamma) uses the value returned by the GetCameraControlRegister to modify the parameter gamma.

int dc1394_get_gamma (raw1394handle_t handle, node_t node , unsigned int *gamma )

In this way, the user obtains the value of the camera parameter he queried for.

These functions are used to set the values of various camera features. There is a corresponding set function for almost each get function. You can recognize these functions by searching for set string.

For example,

dc1394_set_gamma (raw1394handle_t handle, nodeid_t node, int
gamma)

Like the get function, this function needs raw1394handle_t and nodeid_t for camera identification.

The other parameter, gamma, is the user-specified value for the gamma parameter.

The flow of the function call is quite helpful in understanding what is actually happening. The flow is exactly same as that of the get function. The only difference is this time all the intermediate functions are also set functions, and instead of raw1394_read(), it uses raw1394_write() to write the value of the camera parameter on to the registers.

Figure 2. Flow of set function call

There are three print functions available:

As the name suggests, these functions are used to prepare the camera to start grabbing the images. In order to setup the camera, some parameters must be passed to the function. The number and the type of parameters are specific to the setup function, but essentially three parameters must be passed in all the setup functions: raw1394handle_t, nodeid_t and the pointer to the dc1394_cameracapture structure (this is to provide the buffer for grabbed images and keep attributes, like height and width of frame).

As mentioned previously, raw1394handle_t and nodeid_t uniquely define the camera, while the pointer to dc1394_cameracapture provides the buffer for the image frame to be grabbed. It also stores information about the width and height of the frame which is useful at the time of image processing.

Other parameters that are passed are data speed, frame rate, image format, image mode and ISO channel number.

In case the camera uses DMA, the number of DMA buffers and drop frames is to be provided. In most applications you will want to set the number of DMA buffers relatively low(i.e. 1) this ensures that you are viewing frames in near real time. Drop frames is also important for real time as it causes the capture function to throw away the frames buffered in the DMA ring buffer except fot the last. We will discuss about DMA functions in the later part of this HowTo

The various setup functions are:

These setup functions have been defined in dc1394_capture.c.

You have a choice while passing the values for the parameters, like data-speed, format, mode, and channel. Instead of providing the value yourself, you may instruct the function to take the value from the camera. This can be done by passing QUERY_FROM_CAMERA in place of the actual value for that function parameter.

The basic flow of control is easy to understand:

Figure 3. Flow of the setup function call

As shown in Figure 3, the Setup function in turn calls various set functions to set the parameter values to the camera registers. In the case of DMA setup, after the set functions have been called the ioctl system call is called to allocate memory for the DMA buffers and returns a pointer capture_buffer in user space.

The ioctl system calls will fail if the DMA is not setup correctly

The setup functions also allocate memory for the camera _capture buffer:

camera->capture_buffer=(int*)malloc(camera->quadlets_per_frame*4);

These functions are used only if the camera is set for Format7. This format is preferred since this allows the user to define the size of the image to be captured according to his need. By default the size is 1024x768; you can set it to different dimensions, say 960x720.

All Format7 functions have format7 in their function names, and the functions have been defined in a separate file, dc1394_format7.c.

The setup function for Format7 has a minor difference from the normal setup since it also asks for the size of the frame, while you don't have to pass the format parameter as the setup function, as it is meant only for a particular format, for example Format7. The function call flow remains the same as discussed in the previous section.

The Format7 get functions are called query functions. The mechanism is different from the normal get/query functions: they don't call GetCameraControlRegister; instead, they call GetCameraFormat7Register().

The following flowchart will make the differences evident:

Figure 4. Flow of the Format7 query function call

The Format7 query function will call GetCameraFormat7Register, which is supposed to read the values from the control and status registers of the camera. This function in turn will call the QueryFormat and CSROffset to know the offset for the particular information that has been queried. After getting the offset, raw1394_read is used to actually read the values.

The Format7 set functions also follow the same logic with the obvious difference that the reading functions are replaced by writing functions, for example, SetCameraFormat7Register and raw1394_write().

These are the final set of functions identified by us. The basic job of these functions is to release the memory allocated to the capture buffer by the setup routine. This is essential to save the system from memory leaks.

These functions are defined in dc1394_capture.c:

dc1394_release_camera()

This function in turn calls free (camera -> capture_buffer), which frees the memory.

Similarly, the release function is available for DMA setup.

In this interpolation method, each interpolated output pixel is assigned the value of the nearest pixel in the input image. The nearest neighbor can be any one of the upper, lower, left or right pixels.

An example will make the logic clear. We try to find the G values for the R, B tiles for a 3x3 block (shown as shaded region. The blank squares either bear R value or B value. We have not shown them just to make the figure easy to understand). Here we assume the left neighboring pixel value is used to fill the missing ones.

Figure 10. Nearest Neighbour

The table on the left shows the G values for the Bayer Pattern image. In order to find out the missing G values for the other squares that originally contains only R or B we use the following approach:

Find the nearest G value square and copy the G value of that square onto the R (B) square. This has been illustrated in the above figure. The square next to G7 had a value of either R or B. So to get G8 (a G value for square 8) we copied the G value of square 7, since it was the nearest so G8 = G7. Similarly we filled the other non G value squares.

The same logic is applied when finding R and B values for the green squares.

Now that we have presented the basic concept of the RAW, RGB and the conversion algorithm, we feel that you can understand an example program that gives us a colored image.

We have chosen the format as Format7 because the camera we used responds to this format only. We will make use of another example code which provides the implementation of the algorithms. The program is conversions.cpp, in the grabdma folder, available for download at http://www.ptgrey.com/support/kb/data/grabdma.tgz.

To run the code, make sure that you have the following files:

#include <stdio.h>
#include <libraw1394/raw1394.h>
#include <libdc1394/dc1394_control.h>
#include <stdlib.h>
#include <onversions.h>

#define IMAGE "Image.rgb"

int main(int argc, char *argv[]) 
{
  FILE* imagefile;
  dc1394_cameracapture camera;
  int numNodes;
  int numCameras;
  raw1394handle_t handle;
  nodeid_t * camera_nodes;
  int channel,speed,mode,bytes_per_packet;

   /* Open ohci and asign handle to it */

    handle = dc1394_create_handle(0);
  if (handle==NULL)
  {
    fprintf( stderr, "Unable to aquire a raw1394 handle\n\n"
       "Please check \n"
         " - if the kernel modules `ieee1394',`raw1394' and `ohci1394' are loaded \n"
         " - if you have read/write access to /dev/raw1394\n\n");
exit(1);
  }

  /* get the camera nodes and describe them as we find them */

  numNodes = raw1394_get_nodecount(handle);
  camera_nodes = dc1394_get_camera_nodes(handle,&numCameras,1);
  fflush(stdout);
  if (numCameras<1)
  {
    fprintf( stderr, "no cameras found :(\n");
    dc1394_destroy_handle(handle);
    exit(1);
  }
  printf("working with the first camera on the bus\n");

  if( camera_nodes[0] == numNodes-1)
  {
    fprintf( stderr, "\n"
           "Sorry, your camera is the highest numbered node\n");
    dc1394_destroy_handle(handle);
    dc1394_free_camera_nodes(camera_nodes);
    exit( 1);
  }

  /*obtain the values of the parameter from the camera */

dc1394_get_video_mode(handle,camera_nodes[0],(unsigned int *)&mode); 

dc1394_get_iso_channel_and_speed(handle,camera_nodes[0],
(unsigned int *)&channel, (unsigned int *)&speed);

dc1394_query_format7_byte_per_packet(handle,camera_nodes[0],(unsigned)
mode,&bytes_per_packet);

  /*setup capture */

if (dc1394_setup_format7_capture(handle,
           camera_nodes[0],
         channel , /* channel */ 
         mode,
         speed,
         bytes_per_packet,
         0,
         0,
         960,
         720, 
         &camera)!=DC1394_SUCCESS) 
  {
    fprintf( stderr,"unable to setup camera-\n"
         "check line %d of %s to make sure\n"
         "that the video mode,framerate and format are\n"
         "supported by your camera\n",
         __LINE__,__FILE__);
    dc1394_release_camera(handle,&camera);
    dc1394_destroy_handle(handle);
    dc1394_free_camera_nodes(camera_nodes);
    exit(1);
  }
  dc1394_free_camera_nodes(camera_nodes);

  /* have the camera start sending us data*/

  if (dc1394_start_iso_transmission(handle,camera.node)
      !=DC1394_SUCCESS) 
  {
    fprintf( stderr, "unable to start camera iso transmission\n");
    dc1394_release_camera(handle,&camera);
    dc1394_destroy_handle(handle);
    exit(1);
  }

  /* capture one frame */

  if (dc1394_single_capture(handle,&camera)!=DC1394_SUCCESS) 
  {
    fprintf( stderr, "unable to capture a frame\n");
    dc1394_release_camera(handle,&camera);
    dc1394_destroy_handle(handle);
    exit(1);
  }

  /*query the camera to determine the Bayer pattern*/

quadlet_t qValue;
   GetCameraControlRegister( handle, 
              Camera_nodes[0],
              0x1040,/* Bayer Tile Mapping register */
              &qValue );

   bayer_pattern_t pattern = BAYER_PATTERN_BGGR;
   switch( qValue )
   {
      case 0x42474752:/* BGGR */
       pattern = BAYER_PATTERN_BGGR;
       break;
      case 0x47524247:/* GRBG */
       pattern = BAYER_PATTERN_GRBG;
       break;
      case 0x52474742: /* RGGB */
       pattern = BAYER_PATTERN_RGGB;
       break;
      case 0x47425247:/* GBRG */
       pattern = BAYER_PATTERN_GBRG;
       break;
      case 0x59595959:/* YYYY = BW */
       fprintf( stderr, "Camera is black and white\n" );
       cleanup();
       return 1;
      default:
      fprintf(stderr,
          "Camera BAYER_TILE_MAPPING register has an unexpected value:\n"
          "\t0x%x\n", qValue );

      return 1;
   }

   int bufferSize = camera.frame_width*camera.frame_height;

   /* assign a buffer of size three time the original image */

   unsigned char* rgbBuffer = new unsigned char[3 * bufferSize];

   unsigned char* src = (unsigned char*)camera.capture_buffer;

   unsigned char* captureBuffer=
            (unsigned char*)camera.capture_buffer;
   for ( int i = 0; i < bufferSize; i++ )
   {
       src[i] = captureBuffer[ i * bytesPerPixel ];
   }

   /* convert to color image */

   BayerNearestNeighbor (src, 
             rgbBuffer, 
             camera.frame_width,
             camera.frame_height,
             pattern );


   /* Stop data transmission */

  if (dc1394_stop_iso_transmission(handle,camera.node)!=DC1394_SUCCESS) 
  {
  printf("couldn't stop the camera?\n");
  }

  /* save image as 'Image.rgb' without adding any pgm header */

  printf( "Saving the image...\n" );
  imagefile = fopen( IMAGE, "w" );

  fwrite( rgbBuffer, 3,
         bufferSize, imagefile );

  fclose( imagefile );

  /* Close camera */

  dc1394_release_camera(handle,&camera);
  dc1394_destroy_handle(handle);
  return 0;
}

As we have already discussed the use of GetCameraControlRegister, you can understand that it has been used to find out the value contained at 0x1040. Libdc1394 does not provide any function to query this address, so we explicitly used this call to get the value.

It is important to understand the utility of the above function call. Refer to our discussion about the Bayer Pattern filters in the previous section. We know that the pattern can be BGGR, RGGB, GRBG, and GRBG. The algorithm that we use for converting the Bayer Pattern to RGB requires to know about the type of pattern the camera filter has got so that it can carry out some initialization (refer to conversions.cpp for details). The fourth parameter in the function call:

   BayerNearestNeighbor (src, 
             rgbBuffer, 
             camera.frame_width,
             camera.frame_height,
             pattern )

refers to this value.

BayerNearestNeighbor is the function call for the interpolation algorithm we discussed in the last section. This is implemented in conversions.cpp.

Having understood this, we move on to the switch-cases. The value that is obtained for the Bayer Pattern (qvalue) is in the hex form which needs to be decoded for setting the value of the variable pattern.

The case statements indicate the various hex values relating to the Bayer Pattern that can be returned by the various cameras. The intimidating values are actually quite easy to decode. Here's the trick:

The hex code for various colors is as follows:

Now if the qvalue contains 0x42474752, it means: B (42h) G (47h) G (47h) R (52h) or BGGR. We can therefore decode all the case statements similarly.

Finally, we need to declare another image buffer that will contain the RGB image. Remember that the size of the RGB is 3 times the size of the Bayer Pattern image. rgbbuffer is therefore assigned 3 times the buffer size (camera.capture_buffer). This buffer (rgbbuffer) will be passed as the destination buffer (the second parameter in BayerNearestNeighbor).

After the buffer has been filled with the RGB values we write it in the file image.rgb.

In order to view this image using gimp, we need to append a bitmap header. The method we employed was as follows:

In order to run the program, use the following steps:

g++ -c conversions.cpp
g++ -o grabcolor conversions.o grabcolor.cpp -lraw1394
-ldc1394_control

The Coriander application is useful in finding out how the RGB image will look after undergoing different conversion algorithms. For example, it provides the choice between Nearest Neighbor, Edge Sense and Down Sample conversion algorithms. The difference can be observed on a mouse click.