|
Camwire |
| Home page: kauri.auck.irl.cri.nz/~johanns/camwire | [Download Camwire] |
This page was last edited on: $Date: 2007/02/22 23:08:28 $
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 DCAM specifications. To find cameras that conform, or to check if yours conforms, Damien Douxchamps maintains the excellent IEEE1394 Digital Camera List.
The official library for controlling IEEE 1394 digital cameras 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 function dc1394_set_format7_image_size() to change the camera's region-of-interest. And you would be right to be annoyed when it instantly segfaults. 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.
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.
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.
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.
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.
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!
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.
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.
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. There is also a libdc1394 FAQ if you need to probe deeper.
There are examples of how to use Camwire in the examples subdirectory of the tarball.
A few tools are included in the tools subdirectory to help with debugging the IEEE 1394 bus interface and to measure some essential DCAM parameters:
You will need dc1394 installed on your platform, as well as the supporting libraries and drivers libraw1394, raw1394, ieee1394, video1394, and ohci1394. The IEEE 1394 for Linux site has good documentation of these.
The Cammonitor example needs SDL and Xv to display images on the screen. These are commonly included in GNU/Linux distributions.
The minimum system requirements for Camwire is kernel 2.4.22 and libdc1394 version 0.9.5 CVS after 11 August 2004. Until libdc1394 version 2.0 is more stable, Camwire will use only versions 1.x of libdc1394.
Camwire is licensed under the GNU Lesser General Public License (LGPL, see file COPYING in the Camwire tarball). 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.
The Camwire tarball does not (yet) include binaries or even the usual autoconfig packaging. You will have to compile it yourself. This may be easier than you think and ensures that Camwire runs correctly on your platform. I provide my Makefile for you to modify and use at your own risk. See the INSTALL file in the tarball for more help. It also has a Troubleshooting section.
While we still occasionally develop it as needed and the odd stray bug gets cleaned up. The only reason why I have not released a version 1.0 is because I am embarrassed by the poor graphics support offered by the main example, Cammonitor.
The plan is to release Camwire version 1.0 in the not-too-distant future. Its development will be frozen soon after, when I start porting it to libdc1394 version 2.0.
Please send suggestions, bug reports and fixes to me. Developers are invited to extend the Camwire interface to other buses like USB and CameraLink. If that happens we may decide to put the project on Sourceforge.
Finally, 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!
A few pictures of places around the world where Camwire is used:
Johann
Schoonees (email: my first initial dot my surname at irl dot cri dot
nz)
Industrial Research Limited, PO Box 2225, Auckland, New
Zealand