Camwire logo

Camwire
a generic API for IEEE 1394 cameras

Home page: [ Download Camwire 1 ]
kauri.auck.irl.cri.nz/~johanns/camwire/ [ Download Camwire 2 ]

Camwire is a digital camera library for GNU/Linux. It provides a set of C functions to control IEEE 1394 digital cameras from a computer.

Camwire is implemented for the IEEE 1394 bus and OHCI-compatible hosts. (Other names for IEEE 1394 are Firewire™ and iLink™.) It supports cameras that conform to the IIDC 1394-based Digital Camera (DCAM) specifications. To find cameras that conform, or to check if yours conforms, Damien Douxchamps maintains the excellent IEEE1394 Digital Camera List.

Camwire is wrapped around dc1394, the official library for controlling IEEE 1394 digital cameras on GNU/Linux. Version 1 of Camwire (Camwire 1) is based on libdc1394-1 and version 2 (Camwire 2) on libdc1394-2.

Table of contents

Why Camwire?

Get going sooner with less pain

The traditional IEEE 1394 digital camera library on GNU/Linux is dc1394. dc1394 is a low-level wrapper around DCAM register set access, mixed with higher-level DMA transfer and buffering functions. It works if you treat it right but it bristles with thorns and traps. Understanding how to run your camera typically involves a long learning curve of segmentation faults and frozen cameras. There is almost no first-party documentation and I had to read most of the libdc1394 source code to be able to use it effectively.

For example: you might think of using the innocent-looking (libdc1394-1) function dc1394_set_format7_image_size() to change a running camera's region-of-interest. And you would be annoyed as I was when it instantly segfaults.

Or look at a more subtle gotcha in libdc1394-2: the function dc1394_get_color_coding_from_video_mode() succeeds or fails depending on the combination of its video_mode argument and the mode the camera happens to be in at the time. But who has time for grokking video modes when all you want to do is use the camera?

Some dc1394 functions are incompatible with preceding functions and there is no sure way of knowing which can be mixed, without reading a lot of source code. Camwire was written to ease the pain.

It's reliable

Camwire protects the application programmer from most of the gotchas of the dc1394 library. It contains work-arounds for known kernel bugs and avoids using camera registers that are implemented differently by different manufacturers. It is quite difficult to crash a camera with Camwire. Things generally work as expected and you don't need to know how much dirt has been swept under the carpet.

Camwire is being used for industrial-scientific purposes at my company and by many others around the world since 2004. Occasional bugs still turn up but the code is basically stable.

It's intuitive

Camwire focuses on the camera and its generic functions (such as taking pictures), not on the DCAM spec and the IEEE 1394 subsystem. Camwire allows you to think in terms of frame rates, pixel codings and shutter speeds, while dc1394 forces you to think in terms of formats, modes and bytes_per_packet. Camwire adds a few camera-centric extensions to the DCAM spec, such as frame numbers and timestamps of the trigger instants - things a camera user might want to know but which do not concern the bus implementers.

It's maintainable

Camwire is a higher-level API. Working at a higher level is less error-prone. Example: You don't need to know about DCAM Formats if you don't want to, but if you should decide to switch from Format 0 to Format 7, you may have to rewrite and debug a lot of code using dc1394. Different Formats need different dc1394 function calls. With Camwire, you edit one number in a configuration file and the function calls stay the same.

It's efficient

Camwire is thinly wrapped around dc1394 where it is safe to do so. The code only gets thick in places where you would have had to write a lot of glue yourself anyway. Camwire also offers a simple way of shadowing camera settings (caching a local copy) which can dramatically reduce the asynchronous traffic on the bus.

It's comprehensive (well, almost)

Most of the things you might want to do with a DCAM-compatible IEEE 1394 digital camera are covered by Camwire. If it isn't, email me or submit a patch!

Why should I not use Camwire?

Camwire is intended for C/C++ programmers who would like to work at a higher level of abstraction than dc1394. If you want nuts-and-bolts access to the DCAM registers you will need to call dc1394 directly.

Camwire does not exploit every trick in the DCAM spec. The biggest hole is probably its not using absolute value registers. If you don't know what that is, you may not miss it.

If you are not a programmer and need a pre-made GUI interface, something like Coriander might be better.

Some features

The C functions form an interface which is implementation-independent in the sense that it does not know or care whether the camera is on an IEEE 1394 (Firewire, iLink), USB, CameraLink, or whatever bus. They are about camera features, not bus features.

Documentation

The header files camwirebus.h and camwire.h declare the functions that form the Camwire interface. The headers are extensively commented and should contain all the documentation you are likely to need.

If you would like to mix Camwire and dc1394 function calls in your code (at your own risk!), you'll also need camwire_handle.h.

There is also a libdc1394 FAQ if you need to probe deeper.

Example code

The simplest use of Camwire

Here is the canonical Hello world! It does nothing but print some information about any camera it finds connected to the host computer.

There are more extensive examples of how to use Camwire in the examples subdirectory of the release. Their compiled executables can also be installed and run:

Cammonitor screenshot

System requirements

Camwire 1: The minimum system requirements for Camwire 1 is kernel 2.6 and libdc1394 version 1.2. You will also need the supporting libraries and kernel modules libraw1394, raw1394, ieee1394, video1394, and ohci1394 installed.

Camwire 2: The minimum system requirements for Camwire 2 is kernel 2.6 and libdc1394 version 2.1. You will also need the kernel modules firewire-core and firewire-ohci installed.

The Cammonitor example needs SDL and Xv to display images on the screen, and Netpbm to save image to files. These are commonly included in GNU/Linux distributions.

Licence

Camwire is licensed under the GNU Lesser General Public License (LGPL, see file COPYING in the Camwire release). Other files in the source not belonging to but being part of the Camwire build are under their own licences, as stated at the top of the individual files.

Installation

The Camwire releases are now compiled and packaged with CMake. You can either compile Camwire from the source package (using CMake), or download and install the binary package best suited to your platform. See the INSTALL file in the release directory for more help.

Development

Camwire version 0.9.4 is likely to be the last release of Camwire 1. It never quite made it to version 1.0! Further versions may be released only to fix bugs.

Camwire 2 is based on libdc1394 version 2.0. Camwire 2's first release had version number 1.9.0, which is API compatible with Camwire 1's 0.9.4. You should be able to recompile your Camwire 1 code with no change to Camwire 2.

Camwire 2.0 is now stable and has been released.

The following people have contributed code, pathes and bug fixes to Camwire; thanks!

Please let me know if I've left someone out...

If you use Camwire please send me an email describing your application. You'd be surprised a how little feedback developers get when things are working well!

Photo album

A few pictures of places around the world where Camwire is used:


This page was last edited on: $Date: 2015/05/24 23:50:16 $

Please send suggestions, bug reports and fixes to me:

Johann Schoonees (email: my first name dot my surname at callaghaninnovation dot govt dot nz)
Callaghan Innovation, PO Box 2225, Auckland, New Zealand