Getting Started with C+FOX

This page will show how to use the C+FOX library to perform quick, high quality acquisition from a FireWire camera device. Base classes, compilation process and a simple example will be presented.

Installing and compiling with C+FOX

C+FOX is composed of a light weight static library (libcfox.a) and a set of headers files. After downloading the sources tarball, you will find a XCode project ready to be built. Once compiled, the library file and headers can be safely copied to some usual location (like /usr/local/lib and /usr/local/include).

Once installed the library is easy to use. Create a new XCode project, adds the path tothe C+FOX headers files, link against libcfox,IOKit Framework and Carbon Framework and you're set. Now that your project is ready to use C+FOX, we can start writing code. First is to include the main C+FOX header and using the cfox namespace.

#include <cfox/cfox.h>
using namespace cfox;

int main(int,char**)
{
  return 0;
}

In the following example we'll write a simple application that acquires fifty frames from a camera. We'll see how to use the cfox::Camera class and its various settings.

Acquisition Code

The cfox::Camera class is designed to work like a stream. Once constructed, we can use the >> operator to get a pointer to the latest acquired frame from the camera device.

#include <cfox/cfox.h>
using namespace cfox;

int main(int,char**)
{
  Camera myCam(Mode_640x480_Mono8,FPS_30,0,BasicCamera);
  Camera::Frame img;
  myCam.start();
  
  for(int i=0;i<50;i++)
  {
    CFRunLoopRunInMode(kCFRunLoopDefaultMode,1,true);
    myCam >> img;
  }
  return 0;
}

The frame acquisition is initialized by the Camera::start method and the actual video frame are grabbed via Camera::operator>>.The last remains of the IOKit framework is the call to CFRunLoopRunInMode. This call ensure that the data transfer between the FireWire DMA and the main memory is performed correctly during the loop.

The Camera::Frame type is an encapsulation of an unsigned char*. All frames acquired trough cfox::Camera are stored as an array of unsigned char independently of their internal format. For example a 640x480 image encoded in YUV4:2:2 is stored into a 640x480x2 unsigned char array. From there, it's up tot the end user to use this array correctly.


Note on start/stop method
The cfox::Camera class exposes a start and stop method. This may looks like bad C++ practice by violating the RAII idiom. In fact, separating the actual Camera class instanciation from the acquisition start is needed for broadcasting support purpose. More over, the stop method just halt the acquisition and doesn't release any FireWire ressources internally. The release of FireWire ressources are still done in the Camera destructor.

Building a Camera instance

The cfox::Camera class constructor needs four parameters that defines the device behavior.

Camera myCam( Mode videoMode,FPS fps,size_t chan, Spec camType);

Video Mode
All common modes and formats for video camera are supported. Here is a complete list sorted by resolution, color and color encoding.

YUV Color Encoding              RGB Color Encoding
Mode_160x120_YUV444           Mode_640x480_RGB
Mode_320x240_YUV422           Mode_800x600_RGB
Mode_640x480_YUV411           Mode_1024x768_RGB
Mode_640x480_YUV422           Mode_1280X960_RGB
Mode_800x600_YUV422           Mode_1600X1200_RGB
Mode_1024x768_YUV422
Mode_1024x768_YUV422
Mode_1280X960_YUV422
Mode_1600X1200_YUV422

8 bits Grayscale Encoding             16 bits Grayscale Encoding
Mode_640x480_Mono8                        Mode_640x480_Mono16
Mode_800x600_Mono8                        Mode_800x600_Mono16
Mode_1024x768_Mono8                      Mode_1024x768_Mono16
Mode_1280X960_Mono8                      Mode_1280X960_Mono16
Mode_1600X1200_Mono8                    Mode_1600X1200_Mono16

Video FPS
All FPS from 1.875 to 30 are supported and selectable by the following tags :
FPS_1_875, FPS_3_75, FPS_7_5, FPS_15 and FPS_30.

FireWire Channel
C+FOX supports up to 64 FireWire device. Each device is tied to a channel between 0 and 63 that is used to locate the device ontot he FireWire network.

Camera Type
Four camera types are supported :

  • BasicCamera : Used for standard compliant camera.
  • NonConformantCamera : Used for non standard compliant camera.
  • ListeningCamera : Used for standard compliant camera used in Listening mode.
  • NonConformantListeningCamera : Used for non standard compliant camera used in Listening mode.
The compliant/non compliant camera issue can appears with some brand of camera. If your specific camera seems to not deliver correct frame or to not start at all, try to switch between BasicCamera and NonConformantCamera. If it doesn't fix the problem, send me a mail with camera model, brand and sample code.

Advanced Features

Memory Management
It's possible to take control over the memory used to acquire the image from cfox::Camera by using an user defined memory area and the Camera::copyFrame method as shown in the following example.

  Camera myCam(Mode_640x480_Mono8,FPS_30,0,BasicCamera);
  Camera::Frame img = new unsigned char[myCam.frameSize()];
  
  CFRunLoopRunInMode(kCFRunLoopDefaultMode,1,true);
  myCam.copyFrame(img);

FireWire Broadcasting
C+FOX provides a way to perform FireWire broadcasting over a FireWire network. COnsider five MAC OS X computer connected trough a FireWire network. Computer 0 is connected to a camera. It's possible to run an acquistino on the five nodes by creating a cfox::Camera in BasicCamera mode on Computer 0, then by creating a cfox::Camera in ListeningCamera mode on Computer 1 to 4. You have to use a way to synchronize this creation (using MPI or another network based synchronisation tool). The Computer 0 camera having to be created and started before the other. At the end of the process, Computer 1 to 4 should stop the camera before Computer 0.

Using C+FOX with X11,OpenGL or AltiVec

Using C+FOX image arrays with X11,OpenGL or AltiVec functions doesn' t require any further processing. Frame arrays are memory aligned for AltiVec purpose and use X11/OpenGL format for RGB and grayscale images.