4.1. Important Data Structures

The library provides some structures which are useful in storing camera and image related information. They have been declared in the dc1394_control.h file.

We will be largely concerned with the dc1394_cameracapture structure.

4.2. Types of functions

We have categorized the functions provided by the library into 6 types. (The categorization is purely done on our own for the ease of discussion). Each of these functions has been declared in dc1394_control.h. We suggest you to keep a copy of the file on hand while going through the subsequent section.

1. Get/Query Functions

2. Set Functions

3. Print Functions

4. Setup Functions

5. Format7 Functions

6. Release Functions

---

4.2.1. Get/Query Functions

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:

1. Both the raw1394handle_t and node_t nodes: these two together identify the camera

2. A pointer to obtain the value, for example, int * gamma

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.

	Note on data types:
	The library makes use of typedefed data types octlet_t and quadlet_t very frequently . These are defined in dc1394_internal.h and stand for 8-byte and 4-byte data types.

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.

4.3. Coriander: A GUI for the libdc1394 library

Coriander helps in easy handling of the IEEE1394 cameras. It uses the above discussed functions and libraries and provides a GUI for them. The main advantage of Coriander is that it saves time that is normally wasted in camera setup. Also, Coriander shows only those features and attributes that are present on the camera and hence you can judge how useful the camera will be for your application development. The most important feature of Coriander is its ability to display the captured image at run-time.

Coriander also allows the user to convert a BGGR image to RGB. We will discuss the meaning of these types of images in detail in later sections. Some files that can be useful in understanding the functionality of Coriander are:

1. thread_iso.c

2. Camera.c

3. main.c

The Coriander homepage contains an excellent user manual which can be useful in case of any difficulty: http://damien.douxchamps.net/ieee1394/coriander/manual.php.

Our use of Coriander was limited only to checking that the camera was working properly and confirming the focus was correct. We will give some more usage information for Coriander in later sections.

4.4. Example: How to grab image from the IEEE1394 camera

In this section we will demonstrate how to write a small program to grab an image from the camera. We have taken the program (grab_gray_image.c) given in the examples in the library tar file. We have removed some lines to increase the readability of the code. We have provided the explanation for this code below. In order to provide you with a clear picture of which section of the code does what, we grouped the code lines together by task below.

  #include <stdio.h>
  #include <libraw1394/raw1394.h>
  #include <libdc1394/dc1394_control.h>
  #include <stdlib.h>                                     
  #define IMAGE_FILE_NAME "Image.pgm"

  int main(int argc, char *argv[]) 
  {

    FILE* imagefile;
    dc1394_cameracapture camera;
    int numNodes;
    int numCameras;
    raw1394handle_t handle;
    nodeid_t * camera_nodes;                              

         /* 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"
                    );
         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);
    }

    /*setup capture */

    if (dc1394_setup_capture(handle,camera_nodes[0],      
                             0, /* channel */ 

                             FORMAT_VGA_NONCOMPRESSED,
                             MODE_640x480_MONO,
                             SPEED_400,
                             FRAMERATE_7_5,
                             &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);

    /* set trigger mode */

    if( dc1394_set_trigger_mode(handle, camera.node, TRIGGER_MODE_0)
        != DC1394_SUCCESS)
    {                                                     
      fprintf( stderr, "unable to set camera trigger mode\n");
#if 0
      dc1394_release_camera(handle,&camera);
      dc1394_destroy_handle(handle);
      exit(1);
#endif
    }

    /* 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);
    }

    /* Stop data transmission */

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

    /* save image as 'Image.pgm' */

    imagefile=fopen(IMAGE_FILE_NAME, "w");

    if( imagefile == NULL)
    {
      perror( "Can't create '" IMAGE_FILE_NAME "'");
      dc1394_release_camera(handle,&camera);
      dc1394_destroy_handle(handle);
      exit( 1);
    }

    /* Adding the pgm file header */

    fprintf(imagefile,"P5\n%u %u 255\n", camera.frame_width,
         camera.frame_height );
                                                          (11)
    /* Writing to the file */

    fwrite((const char *)camera.capture_buffer, 1,
         camera.frame_height*camera.frame_width, imagefile);
    fclose(imagefile);                                    (12)
    printf("wrote: " IMAGE_FILE_NAME "\n");

    /* Close camera */

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

We hope that after going through this algorithmic way explanation you can comfortably understand the example code.

If we used the Format7 image format, we would have to change only the setup_capture function. Let us look at the setup function:

dc1394_setup_format7_capture( /* handle and camera_nodes[0] uniquely identifies the camera */ handle, camera_nodes[0], channel, /* channel */ mode , /*mode */ bytes_per_packet , left ,/*area of interest start column */ right, /*area of interest start row */ width,/* area of interest width */ height /* area of interest height */ &camera /* dc1394_cameracapture type pointer *./ )!=DC1394_SUCCESS)

where the values of the parameters for channel, speed, bytes_per_packet, speed, mode are found using the following functions:

1. dc1394_get_iso_channel_and_speed(handle,camera_nodes[0], &channel,&speed) /* to get the channel and the data speed */

2. dc1394_get_video_mode(handle,camera_nodes[0] &mode); /* to get the mode */

3. dc1394_query_format7_byte_per_packet(handle, camera_nodes[0], mode ,&bytes_per_packet); /* to get the bytes per packet which depends on the mode*/

4. The value of left, top can be set to QUERY_FROM_CAMERA, or can be specified directly by the user.

5. The value of the width and height depends on the size of frame the user wants, for example, if one wants 960x720 then pass 960 as width and 720 as height.

4.5. Example: How to grab image from the IEEE1394 camera using DMA

This section has been contributed by Ian Peikon <[email protected]>and Tim Hanson <[email protected]> We will now present an example of how to grab a frame by the camera using DMA calls. The example is simple to understand as the logic remains the same as the previous example. We will later compare the function calls used in the previous example (without dma) and this example (with dma) for better understanding.

#include <stdio.h>
#include <libraw1394/raw1394.h>
#include <libdc1394/dc1394_control.h>
#include <stdlib.h>  
#include <iostream>
#define IMAGE_FILE_NAME "Image.pgm"
using namespace std;

int main(int arc, char *argv[]){
        FILE * imagefile;
        dc1394_cameracapture camera;
        int numNodes;
        int numCameras;
        raw1394handle_t handle;
        nodeid_t * camera_nodes;
        unsigned int channel, speed, format, framerate, mode;
        
        /*Step 1: Open ohci and assign a handle to it.*/
	/*=======================================================*/
	handle = dc1394_create_handle(0);
        if(handle==NULL){
                fprintf(stderr, "Unable to acquire a handle. \n\n");
        }
        else{
		 cout <<"dma1394: Handle aquired successfully-" <<handle<<"\n";
        }
        
/*Step 2: 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);
                return -1;
        }
        else{
                cout<<"dma1394:"<< numCameras<<" cameras found. \n";
        }
        printf("dma1394: Working with the first camera on the bus.\n");
        if(camera_nodes[0] == numNodes-1){
                fprintf(stderr, "\n" "dma1394: Sorry, your camera is the highest numbered node.\n");
                dc1394_destroy_handle(handle);
                dc1394_free_camera_nodes(camera_nodes);
                return -1;
        }
        
/*Step 3: Setup Capture*/
	/*=====================================================================*/
	/*Using camera functions to get the params by querying them*/
	cout<<"INFO FOR DEBUG: \n"
                        "num_dma_buffers: "<< camera.num_dma_buffers<<"\n";
        dc1394_get_iso_channel_and_speed(handle, camera_nodes[0], &channel, &speed); /*get channel and speed*/
	dc1394_get_video_format(handle, camera_nodes[0], &format); /*get format*/
	dc1394_get_video_framerate(handle, camera_nodes[0], &framerate); /*get framerate*/
	dc1394_get_video_mode(handle, camera_nodes[0], &mode); /*get mode*/
	cout<<"dc1394: Got parameters from the camera.\n"
                "=======================================\n"
                "Channel: "<< channel<< " \n"
                "Speed: " <<speed <<" \n"
                "Format: "<< format <<" \n"
                "Framerate: " <<framerate<< "\n"
                "Mode: "<< mode <<"\n";
        camera.num_dma_buffers = 8; /* set the dma buffers */
        camera.drop_frames = 1; /* set the number of drop frames */
        camera.dma_device_file = NULL;
        if(dc1394_dma_setup_capture(handle, camera_nodes[0], channel, format, mode, speed, framerate, camera.num_dma_buffers, camera.drop_frames, camera.dma_device_file, &camera) !=DC1394_SUCCESS){
                fprintf(stderr, "dma1394: Unable to setup camera.\n" 
                                        "Check line %d of %s to ensure that the options set are supported by your camera.\n", __LINE__, __FILE__);
                dc1394_destroy_handle(handle);
                dc1394_free_camera_nodes(camera_nodes);
                return -1;
        }
        else{
                printf("dma1394: Capture has been setup.\n");
        }
        dc1394_free_camera_nodes(camera_nodes);

        //Set Trigger Mode -- Generally not required thus I will comment it out.
	/*if(dc1394_set_trigger_mode(handle, camera.node, TRIGGER_MODE_0) != DC1394_SUCCESS){
                fprintf(stderr, "dma1394: Unable to set the camera trigger mode. Refer to line %d in %s.\n", __LINE__, __FILE__);
                dc1394_release_camera(handle, &camera);
                dc1394_destroy_handle(handle);
        }
        else{
                printf("dma1394: Successfully set trigger mode.\n");
        }*/
        
        /*Step 4: Start sending data */
	/*=======================================================*/
	if(dc1394_start_iso_transmission(handle, camera.node) != DC1394_SUCCESS){
                fprintf(stderr, "dma1394: Unable to start the data transmission.\n");
                dc1394_dma_done_with_buffer(&camera);
				dc1394_dma_release_camera(handle, &camera);
                dc1394_destroy_handle(handle);
                return -1;
        }
        else{
                printf("dma1394: Success.  Data Transmission started.\n");
        }
        
        /*Step 5: Capture Something...Anything...PLEASE*/
	/*===============================================================*/
	if(dc1394_dma_single_capture(&camera) != DC1394_SUCCESS){
                fprintf(stderr, "dma1394; DAIM, can't capture a single frame.\n");
				dc1394_dma_done_with_buffer(&camera); /*important step */
                dc1394_dma_release_camera(handle, &camera);
                dc1394_destroy_handle(handle);
                return -1;
        }
        else{
                printf("dma1394: GREAT SUCCESS! Captured a single frame.\n");
        }
        
        /*Step 6: Stop sending data*/
	/*==================================================*/
	if(dc1394_dma_unlisten(handle, &camera) != DC1394_SUCCESS){
        		fprintf(stderr, "Can't unlisten iso channel! \n");
        }
        else{
                printf("dma1394: DMA unlistened. \n");
        }
        
	if(dc1394_stop_iso_transmission(handle, camera.node) != DC1394_SUCCESS){
                fprintf(stderr, " Can't stop the camera!! \n");
        }
        else{
                printf("dma1394: Data transmission terminated. \n");
        }
        
        /*Step 7: Save our image*/
	/*===============================================================*/
	imagefile=fopen(IMAGE_FILE_NAME, "w");
        if(imagefile==NULL){
                perror("dma1394: Can't create' "IMAGE_FILE_NAME" ' ");
                dc1394_dma_done_with_buffer(&camera);
				dc1394_dma_release_camera(handle, &camera);
                dc1394_destroy_handle(handle);
                return -1;
        }
        else{
                cout<<"dma1394: Saved image in "<<IMAGE_FILE_NAME<<".\n";
        }
         /*Add pgm file header*/
	fprintf(imagefile, "P5\n%u %u 255\n", camera.frame_width, camera.frame_height);
       
		/*write to file*/
	fwrite((const char *)camera.capture_buffer, 1, camera.frame_height*camera.frame_width, imagefile);
        fclose(imagefile);
        printf("dma1394: wrote: " IMAGE_FILE_NAME "\n");
        
        /*Step 8: Close camera*/
	/*=============================================================*/
	dc1394_dma_done_with_buffer(&camera);
	dc1394_dma_release_camera(handle, &camera);
        dc1394_destroy_handle(handle);
        printf("dma1394: Camera released.  Exiting. \n");
        
        //Step END
	return 0;

}

  

Just like the previous example (Section 4.4) the program includes the necessary header files(libraw1394/raw1394.h and libdc1394/dc1394_control.h) and then declare the three variables of the following data type

• dc1394_cameracapture

• raw1394handle_t

• nodeid_t *

1. Open ohci and assign handle to it using the function dc1394_create_handle(0)
2. Get the camera nodes using the function dc1394_get_camera_nodes
3. Find out various parameters need to be passed during the camera setup. This is done by querying the camera using the following functions
   • dc1394_get_iso_channel_and_speed(): To get the channel and speed information
   • dc1394_get_video_format(): To get the camera format
   • dc1394_get_video_framerate(): To get the framerate information
   • dc1394_get_video_mode(): To get the camera mode
   Also we are required to set the dma buffersto 8 and number of drop framesto 1.

   Once the values of the parameter have been obtained (framerate,format,mode,channel,speed etc), they are passed in dc1394_dma_setup_capture which then sets up the camera and enables it for capturing video. For DMA you must pass the number of dma buffers and drop frames parameter.

4. After the camera is set, dc1394_start_iso_transmission()is called. This function starts data transactions from the camera to the bus.
5. Now capture one frame using dc1394_dma_single_capture(). This function will capture a frame into the dma buffer

   After the frame has been grabbed release the dma buffer using dc1394_dma_done_with_buffer(). This is required so that the memory can be reused. It is imperative that dc1394_dma_done_with_buffer() always follows a dma_capture function call

   So in order to capture more than one frame the code will be

   for( i=0;i<100 ;i++)/* to capture 100 images*/ { dc1394_dma_single_capture(&camera); dc1394_dma_done_with_buffer(&camera); }

6. Stop listening to the iso channel by calling dc1394_dma_unlisten()

   Terminate the data transmission by calling dc1394_stop_iso_transmission()

7. Save the image in a file and add a PGM header for viewing using gimp.
8. Finally call dc1394_release_camerato release the camera

If DMA is not setup correctly you will get the following error message:

VIDEO1394_IOC_LISTEN_CHANNEL ioctl failed

There are various reasons for this error which will be further explained in the Problems section (Section 4.7)

Thus we can see that the image capture using DMA is not much different from non DMA method. We have compared the functions used in two approaches in the following table.

4.6. How to get color images: Bayer Pattern Concepts

The image grabbed by the sample code in the previous section is not colored (we have intentionally used the words "not colored," since the image is not gray-scale either). It is actually a Bayer Pattern. We will give an overview of Bayer Patterns and how they are used to get a colored image in this section.

Digital cameras use a solid-state device called an image sensor. These fingernail-sized silicon chips contain millions of photosensitive diodes called photosites. When you take a picture with a digital camera, the intensity of light hitting each photo site on the sensor is recorded as a signal. Depending on the camera, either 12 or 14 bits of data are recorded. At 12 bits, the camera can record 4,096 levels of brightness. At 14 bits, the camera can record 16,384 levels of brightness. This is referred to as bit depth. The higher the bit depth, the finer is the detail, the smoother the transition between tones, and the higher the dynamic range (the ability of the camera to hold detail in both highlighted and shadowed areas). But at capture, digital images are grayscale, not color. To record color information, each pixel on the sensor is covered with a red, green, or blue filter, with the colors alternating. A common arrangement of color filters is the Bayer Pattern array that alternates colors, but that also uses twice as many green filters as red and blue. Twice as many green filters are used because our eyes are more sensitive to green. This pattern, or sequence, of filters can vary, but the widely adopted Bayer Pattern, which was invented at Kodak, is a repeating 2x2 arrangement. Each pixel has been made sensitive only to one color (one spectral band).

A Typical Bayer Pattern will look like this:

The tile or square (pixel) labeled B means this particular tile is sensitive only to Blue light, and so on.

The Bayer Patterns may be classified into 4 types, depending on how we have arranged the colors. The naming of the Bayer Pattern is done by taking a 2x2 matrix from the top most corner of the pattern and the colors being read in (0,0),(0,1),(1,0),(1,1) order. So for the above Bayer Pattern, if we take the 2x2 matrix as:

The pattern is therefore known as BGGR

The other possible patterns are:

The image we obtained in the previous example was a Bayer Pattern image also known as a RAW image. This was stored in camera.capture_buffer. In order to view what we have captured we convert this RAW image to .PGM by adding a header (look at the explanation in Section 4.4).

In order to get a colored image, the Bayer Pattern image is converted to a RGB image. A RGB image is an enhanced version of the Bayer Pattern image; we try to find the value of the two missing colors at each pixel (remember that each pixel of the sensor is covered by Bayer Pattern filter so we get a single color at any pixel by default). This is done by using different algorithms like Nearest Neighbor, Edge Sense, and so on:

To get a clear picture of what's happening, we have provided the following diagram:

Let's understand how the RAW to RGB conversion algorithms work. We will look into the Nearest Neighbor algorithm in detail. Other Algorithms are thoroughly explained at the following web link: http://www-ise.stanford.edu/~tingchen/main.htm.

Most of these algorithms make use of some kind of interpolations.

---

4.6.2. Example program to understand how the colored image is grabbed using IEEE1394 Camera

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:

• conversions.h

• conversions.cpp

• grabcolor.cpp - also from the grabdma folder. We have modified the code according to our requirements and removed some of the lines. Since most of the code is same as the previously discussed code, we have explained only the portions that are different. These portions have been emphasized.

#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:

• 42h -> B

• 47h -> G

• 52h -> R

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:

1. Save the RGB image buffer in a file, say, image.rgb.

2. Make a bitmap header and save it in a separate file, bmpheader. Refer to http://www.fortunecity.com/skyscraper/windows/364/bmpffrmt.html for header details.

3. cat bmpheader image.rgb > bmpfile

4. Open bmpfile using gimp.

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

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

	Note on available algorithms:
	There are many algorithms that are available in conversions.cpp, so depending upon the requirements, you can call the necessary functions.

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.

4.7. Common Problems Faced While Working With IEEE1394 Cameras

We now look at some of the common problems faced while working with the camera, however we have only listed those problems which we faced. These problems are likely to be faced by anyone who uses the library and the camera. Some of the problems were solved with a proper reasoning but some were just hit-and-miss attempts. The problems and their solutions are listed below.

• Problem #1. After the installation of the library and the modules the camera did not respond

  Solution: We disconnected the camera and connected it again. May be this has to be repeated multiple times. We could not figure out an appropriate reason for this but it works.

• Problem #2. Program is not compiling

  Solution: If one forgets to link the executable with raw1394 and dc1394_control the program won't compile. The correct way is:

  gcc -o xx xx.c -lraw1394 -ldc1394_control /*for C files*/ g++ -o xx xx.cpp -lraw1394 -ldc1394_control /* for Cpp files */

• Problem #3. Compilation failed, giving the error: libdc1394_control.so.13: cannot open the shared object file.

  Solution: Check for the environment variable LD_LIBRARY_PATH. This should contain the path of the shares library. On our system the path was /usr/local/lib. The path must be set accordingly.

• Problem #4. Program hangs when executed.

  Solution: This primarily happens if the values of parameters that are passed to the setup function are not supported by the camera. For e.g. setting the mode mode_640x480_MONO16 when it is not supported. Our suggestion is that one should always query for the values and then pass them to the function (as explained in the example code, located in Section 4.4).

• Problem #5. IDEO1394_IOC_LISTEN_CHANNEL ioctl failed error message being displayed.

  Solution: (contributed by Ian and Tim). There are various reasons for this error message. Type dmesg in the command prompt to gain a better understanding of the problem. Here is a list of problem we ran into [1]

• Problem #6. Used CTRL+C to terminate the image grabbing program, but the next time the program is run, it just hangs.

  Solution: The error usually occurs because the camera functions like a pipe and experiences a broken pipe situation if terminated without flushing the memory channels. The trick is to disconnect the camera and connect it again. One can also try debugging the problem by reinstalling the ohci1394, video1394, raw1394, video1394 modules, which works occasionally.

• Problem #7. Every parameter is okay and the installation is also fine, but even then, when the program is executed the camera is still not detected.

  Solution: This is a strange problem which we also face frequently. The solution is based on trial and error, but it always works:

  1. Disconnect the camera first and then reconnect it.

  2. Now run Coriander (that's why we suggest that you install Coriander before you start working with the camera).

  3. Make all the necessary adjustments; for example, select the mode of the camera, the frame size, and so forth.

  4. Close Coriander.

  5. Execute your program.

  Bingo!!! It works.

  	Note on first step above:
  	The first step is critical since we experienced an error message from Coriander about not finding the camera if we did not disconnect and reconnect the camera before running Coriander.