Skip to content

Latest commit

 

History

History
347 lines (250 loc) · 9.51 KB

README.rst

File metadata and controls

347 lines (250 loc) · 9.51 KB

libcamiface - camera interface C API

Overview

libcamiface ("camera interface") is a C API that provides a camera and OS independent image acquisition framework.

There is also a Python wrapper (:mod:`cam_iface`) of the libcamiface libraries.

What cameras are supported?

Camera support is determined by a libcamiface "backend". Each backend is a piece of code that creates the libcamiface interface for each particular camera driver.

As seen below, the supported camera drivers are currently libdc1394, the Prosilia Gigabit Ethernet SDK, and Point Grey Research FlyCapture2. For a list of cameras supporting the libdc1394 software, see http://damien.douxchamps.net/ieee1394/cameras/. For the Prosilica Gigabit cameras, see http://www.prosilica.com/. For the Point Grey cameras, see http://www.ptgrey.com.

What frame rates, image sizes, bit depths are possible?

This depends primarily on the camera and camera interface. A primary goal of the Motmot suite is not to limit the capabilities possible. The fastest frame rates that we routinely use are 500 fps with a Basler A602f camera using a small region of interest and 200 fps on a Prosilica GE 680 at full frame resolution. The largest image size we routinely use is 1600x1200 on a Pt. Grey Scorpion camera. The largest bit depths we routinely use are 12 bits/pixel on a Basler A622f camera.

Backend status

A number of backends are supported.

Backend GNU/Linux i386 GNU/Linux x86_64 (amd64) win32 (XP) Mac OS X
libdc1394 works works caution newest library version supports Windows, but untested with libcamiface mostly works triggering options disabled
Prosilica GigE Vision works works works works
Point Grey Research FlyCapture2 caution untested caution untested works NA
ImperX NA NA caution rudiments present in git 'cruft' branch NA
Basler BCAM 1.8 NA NA caution rudiments present in git 'cruft' branch, frequent BSOD NA

Key to the above symbols:

  • works Works well, no known bugs or missing features
  • mostly works Mostly works, some missing features
  • caution Not working, although with some effort, could presumably be
    made to work
  • NA The upstream driver does not support this configuration

Download

Download official releases from the download page.

Install from binary releases

Mac OS X

The Mac installer is called libcamiface-x.y.z-Darwin.dmg.

This will install the files:

/usr/include/cam_iface.h
/usr/bin/liveview-glut-*
/usr/bin/ ( other demos )
/usr/lib/libcam_iface_*

To run a demo program, open /usr/bin/liveview-glut-mega.

Windows

The Windows installer is called libcamiface-x.y.z-win32.exe.

This will install the files:

C:\Program Files\libcamiface x.y.z\bin\simple-prosilica_gige.exe
C:\Program Files\libcamiface x.y.z\bin\liveview-glut-prosilica_gige.exe
C:\Program Files\libcamiface x.y.z\include\cam_iface.h
C:\Program Files\libcamiface x.y.z\lib\cam_iface_prosilica_gige.lib
C:\Program Files\libcamiface x.y.z\bin\cam_iface_prosilica_gige.dll

To run a demo program, open C:\Program Files\libcamiface x.y.z\bin\liveview-glut-prosilica_gige.exe.

Compile from source

On all platforms, you need to install cmake. cmake is available from http://www.cmake.org/

You will also need the libraries for any camera software. Cmake should automatically find these if they are installed in the default locations.

linux

mkdir build
cd build
cmake ..
make
make install

To build with debug symbols, include the argument -DCMAKE_BUILD_TYPE=Debug in your call to cmake. To install in /usr, include -DCMAKE_INSTALL_PREFIX=/usr. To make verbose makefiles, include -DCMAKE_VERBOSE_MAKEFILE=1.

To cut a source release:

VERSION="0.9.0"
git archive --prefix=libcamiface-$VERSION/ release/$VERSION | gzip -9 > ../libcamiface-$VERSION.tar.gz
git archive --prefix=libcamiface-$VERSION/ --format=zip release/$VERSION > ../libcamiface-$VERSION.zip

To make a Debian source package:

VERSION="0.9.0"
ln ../libcamiface-$VERSION.tar.gz ../libcamiface_$VERSION.orig.tar.gz
rm -rf ../libcamiface_*.orig.tar.gz.tmp-nest
git-buildpackage --git-debian-branch=debian --git-upstream-branch=master --git-no-create-orig --git-tarball-dir=.. --git-ignore-new --git-verbose -rfakeroot -S

Mac OS X

Download and install Apple's XCode. This requires signing up (free) as an Apple ADC member.

mkdir build
cd build
cmake ..
make
cpack

To build with debug symbols, include the argument -DCMAKE_BUILD_TYPE=Debug in your call to cmake.

In fact, I use the following commands to set various environment variables prior to my call to cmake.:

# You will doubtless need to change these to match your system
export PROSILICA_CMAKE_DEBUG=1
export PROSILICA_TEST_LIB_PATHS=/Prosilica\ GigE\ SDK/lib-pc/x86/4.0
export GLEW_ROOT="/Users/astraw/other-peoples-src/glew/glew-1.5.1"

This will build a Mac installer, called libcamiface-x.y.z-Darwin.dmg.

To build an Xcode project, run cmake with the argument -DCMAKE_GENERATOR=Xcode.

Windows

Windows XP 32bit with CMake 2.6

Install Microsoft's Visual Studio 2008. (Tested with Express Edition.) Install CMake.

Open a Visual Studio Command Prompt from Start Menu->All Programs->Microsoft Visual C++ 2008 Express Edition->Visual Studio Tools->Visual Studio 2008 Command Prompt. Change directories into the libcamiface source directory.

Compile in Release mode. (On linux, this would be done with adding -DCMAKE_BUILD_TYPE=Release in your call to cmake. As I write this, I'm not sure of the best way to do it in Windows.)

cmakesetup
rem  In the cmakesetup GUI, set your source and build directories.
rem  Click "configure".
rem  In the "Select Generator" menu that pops up, press "NMake Makefiles".
rem  After it's done configuring, click "configure" again.
rem  Finally, click "OK".

rem Now change into your build directory.
cd build
nmake

rem Now, to build an NSIS .exe Windows installer.
cpack

This will build a Windows installer, called libcamiface-x.y.z-win32.exe.

Windows 7 64bit with CMake 2.8 to make 32 bit libcamiface

Install Microsoft's Visual Studio 2008. Install CMake.

Open a Visual Studio Command Prompt from Start Menu->All Programs->Microsoft Visual Studio 2008->Visual Studio Tools->Visual Studio 2008 Command Prompt. Change directories into the libcamiface source directory.

cd build
"C:\Program Files (x86)\CMake 2.8\bin\cmake.exe" .. -G "NMake Makefiles"
nmake

rem Now, to build an NSIS .exe Windows installer.
cpack

This will build a Windows installer, called libcamiface-x.y.z-win32.exe.

Backend notes

prosilica_gige

Here is an example of setting attributes on the camera using Prosilica's command line tools:

export CAM_IP=192.168.1.63
CamAttr -i $CAM_IP -s StreamBytesPerSecond 123963084
CamAttr -i $CAM_IP -s PacketSize 1500

Environment variables:

  • PROSILICA_BACKEND_DEBUG print various debuging information.

libdc1394

Environment variables:

  • DC1394_BACKEND_DEBUG print libdc1394 error messages. (You may also be interested in libdc1394's own DC1394_DEBUG environment variable, which prints debug messages.)
  • DC1394_BACKEND_1394B attempt to force use of firewire
    1. (Otherwise defaults to 400.)
  • DC1394_BACKEND_AUTO_DEBAYER use dc1394 to de-Bayer the images,
    resulting in RGB8 images (rather than MONO8 Bayer images).

Basler Pylon

Environment variables for CMake:

  • BASLER_PYLON_LIB_PATH location of Basler libraries
    (e.g. export BASLER_PYLON_LIB_PATH="/opt/pylon/lib64/")
  • BASLER_PYLON_INCLUDE_PATH location of Basler include files
    (e.g. export BASLER_PYLON_INCLUDE_PATH="/opt/pylon/include/")

Environment variables for Basler Pylon libraries:

  • PYLON_ROOT location of Pylon SDK root (e.g. export PYLON_ROOT=/opt/pylon)
  • GENICAM_ROOT location of GenICam root (e.g. export GENICAM_ROOT_V1_1=/opt/pylon)

Git source code repository

The development version of libcamiface may be downloaded via git:

git clone git://github.com/motmot/libcamiface.git

License

libcamiface is licensed under the BSD license. See the LICENSE.txt file for the full description.