libfg - Video4Linux Frame Grabber interface

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
• Live GUI video viewer
• USB cameras with v4l 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.

Kernel Support

These days, nearly all kernels come with the v4l module pre-build. In rare circumstances, you may need to build your own kernel (Shock! Horror!) if your distro doesn’t already come with the Video4Linux modules. 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

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.

Status

The source has not been updated in quite some time. However, there are a number of active users of the library beyond the projects listed above, and several have kindly provided patches. There is an unofficial git repository which has some patches (and extensions) applied.

I do not currently have any Video4Linux capable hardware, and are not currently working on projects that use libfg. Thus I am not in a position to make contributions and enhancements. I will be updating this page periodically with more information, and will gather the patches supplied by various users into a new source distribution.

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

Useful Links

Here are some links that may be useful:

• BTTV Mini-HOWTO
• Video 4 Linux
• Video 4 Linux Version 2