libfg -- Frame Grabber library for Linux

New! - the latest version supports USB cameras, and features a sample app for live video display!

Introduction

The libfg library provides a simple high-level C API for controlling Video4Linux devices, including analog video cameras, TV and webcams.

Overview

Linux has support for TV tuners and frame grabbers. This is provided by the Video4Linux API, which has been around since roughly kernel 2.2. V4L is actually an interface implemented by a number of different drivers or kernel modules that support the different types of hardware. Since it is a kernel level interface, it is driven entirely by ioctl() calls, and is not particularly friendly to use. It is also not particularly well documented.

The purpose of libfg is to provide a simple, high level interface for controlling TV tuners and frame grabbers. This insulates the developer from having to fiddle around with the low-level details. An example below shows how easy it is to use. It is hoped that this will enable developers to write more applications that exploit this hardware, and create some interesting programs.

Features

The current version of libfg supports most of the major features provided by the Video4Linux API (Version 1). This includes:

• Double-buffered capturing (depending on driver)
• Setting a capture window (cropping)
• Set brightness, contrast, etc (in percent)
• Control TV tuner (in MHz)
• Supports multiple norms (PAL, NTSC, Secam, etc)
• Supports different frame formats (eg. RGB32, RGB24, YUV)
• Can save frames to disk (pgm)

Hardware Support

Any V4L device supported by the kernel will work with libfg. This includes capture cards, TV tuners and webcams. The most common type of hardware is probably cards based on the BT848/BT878 chipset, although plenty of others will also work. These days, TV tuner/capture cards are surprisingly affordable too. Get yours today! For more details on particular cards, consult the documentation that comes with your kernel.

We have tested libfg on the following hardware:

• Picolo (BT878)
• FlyVideo 98 / Chronos Video Shuttle II (BT878)
• Logitech Webcam Express

Note on Firewire/1394 devices: it should be possible to use a Firewire camera with the loopback driver; I am currently working on this, and will provide a new version soon.

Kernel Support

You may need to build your own kernel (Shock! Horror!) if your distro doesn't already come with the Video4Linux modules. Debian doesn't by default, while Mandrake does. You will need to enable at least Video4Linux, I2C (for the tuner), and the right module for your card.

License

The libfg code has been released under the Lesser GNU Public License (LGPL). This is to ensure that the code can be used in as many applications as possible (even proprietary or closed-source projects if you really must), while ensuring that improvements to the library itself get sent back to the community. Please read the license in its entirety and understand it before using the software - a copy is included in the source in the file LGPL.

Projects

Currently libfg is used in the following projects:

• The University of Melbourne RoboCup Initiative
• Player/Stage
• Mezzanine

Its main application thus far has been in frame-rate (~40ms) image processing for robotics applications.

If you use libfg in your project, please let me know so I can add you to the list.

Download

For now, you can just download the source tarball (using the link below):

• libfg-0.3.1.tar.gz
  (Source tarball, 122kB)

Documentation

API reference documentation is provided in the above tarball, in both HTML and PDF formats (thanks to Doxygen). The included samples show how to use it; it is fairly straightforward. The device is always initialised to sensible defaults, so after fg_open() returns, you can start grabbing right away.

Examples

There are two example progams included - test-capture, which exercises a number of different calls in the library, and camview. The camview program uses libsdl to perform live streaming of video images into a window.

Building

Just running make will give you a static library (.a) to link with. For now, that will have to do until I sort out dynamic linking of shared libraries and versioning and all that it entails. The README has info on how to build the Python bindings, which is pretty simple.

Sample User Code

Here is an example of how easy it is to use libfg to control your frame grabber in C:

#define TV_ABC 64.250f

void test()
{
  FRAMEGRABBER* fg = NULL;
  FRAME* fr = NULL;

  // Open the default device
  fg = fg_open( NULL );

  // Capture from our VCR

  fg_set_source( fg, FG_SOURCE_COMPOSITE );

  // Take a snap
  fr = fg_grab( fg );
  frame_save( fr, "vcr.pgm" );

  // Now get ABC TV
  fg_set_source( fg, FG_SOURCE_TV );
  fg_set_tuner( fg, TV_ABC );

  // Take a snap
  fg_grab_frame( fg, frame );
  frame_save( fr, "ABC.pgm" );

  frame_release( fr );
  fg_close( fg );
}

And here is an example of the preliminary Python support. This script
was used to create the image at the top of this page. (Gimp was used
to convert the file from PGM to JPG and scale it down a little.)

#!/usr/bin/env python

import fg

g = fg.Grabber()

g.set_channel(182.250)

g.save_frame('sample.pgm')

del g

Enscript was used to do the colour syntax highlighting of the source code.

Useful Links

Here are some links that may be useful:

• BTTV Mini-HOWTO (LinuxDoc.org)
• Video 4 Linux HQ
• Video 4 Linux Version 2