Driver wrappers

Last modified: June 10, 2015

Contents

This Toolkit supports pure Python and C++ driver wrappers. The wrappers are located in a subfolder of the drivers directory whose name has to start with webcam.

Selecting a wrapper

At compile time of the toolkit, all wrappers available for the current platform are compiled. You can select a driver as shown if following small example.

import gamera.toolkits.webcam as wtk

# get list of drivers
driverlist = wtk.Drivers()

# create Webcam instance with first available driver
cam = Webcam(driverlist[0])

Implementing own wrappers

driverinfo.py

The file driverinfo contains some basic information for the setup script. Additional to the supported platforms and the driver's class name there are some options specific for Python or C++ as described in the following.

# This file contains information about your driver Package.

import os

#add your supported platforms as returned from platform.system() here
platforms = ["Linux"]

#add your driver's class name here
classname = "WebcamDriver"

# this is a helper for referring to the directory containing the driver before
# built. You can only use absolute path names because this script is executed
# in the main directory of the Webcam Toolkit
DRIVER_MODULE = classname.lower()
DRIVER_PATH = os.path.join(SETUP_PATH, "drivers", DRIVER_MODULE)

C++ Wrappers

A Webcam driver wrapper is a C++ class which is inherited from Webcam and implements following interface.

class Webcam {
   protected:
      int widthImage, heightImage;

   public:
      /// initializes components needed for further actions
      Webcam() {};

      /// closes current session and frees reserved memory
      virtual ~Webcam() {};

      /**
       * initalizes a session with given device. If there is already an
       * existing session, this session will be closed and a new session to the
       * given device is opened. The parameters width and height set the size of
       * the recorded picture.
       * returns 1 on success, 0 on error
       * */
      virtual int initSession(int width, int height, char* device) = 0;

      /**
       * takes a pictureframe from the webcam and returns its data as RGB.
       * There is no termination symbol but this data is
       * widthImage * heightImage * 3
       * bytes long. The Python wrapper assumes that this memory is allocated
       * using the new[] operator and delete[]s it automatically after creating
       * the Gamera Image.
       * */
      virtual unsigned char* snapshotFromWebcam() = 0;

      /// closes the current session and frees memory
      virtual void closeSession() = 0;

      /**
       * returns a list of available devices as a string (separated by [/])
       * */
      virtual std::string getDevices() = 0;

      /// returns set image width
      int getImageWidth() {
         return widthImage;
      }

      /// returns set image height
      int getImageHeight() {
         return heightImage;
      }
};

New drivers can be added by implementing this inherited class.

C++ wrappers must provide following information in driverinfo.py

################################################################################
# only for C++-Drivers
################################################################################

#leave this True unless you know what you do
compile = True

#add your source files here
sources = ["webcamv4l.cpp"]



#shell-commands that should be run before/after the distutils build-mechanism.
syscommands_before = []
syscommands_after = []

#linking additional libraries. Passed through to distutils
library_dirs = []
libraries = []

#additional arguments passed to the compiler/linker
extra_compile_args = []
extra_link_args = []

#files that should be copied during installation
copy_on_install = [("#sourcefile#", "#destinationfile#")]

Python wrappers

Python wrappers have at least a __init__.py file which provides a class derived from Webcam. This class has to be mapped to the name Webcam in the module.

Python wrappers must provide following infomration in driverinfo.py

################################################################################
#only for Python Drivers
################################################################################

#leave this False unless you know what you do
compile = False

#add all files needed for running the module here
pythonfiles = ["__init__.py"]

Wrappers included in this toolkit

Mac OS X

For Mac OS X there is a wrapper which uses the Objective C API QtKit. Compiling and linking this to a Gamera toolkit is a little bit tricky because Gamera supports only plugins written in C++. Our C++ class WebcamQtkit wraps the Objective C methods. This module is compiled using the Objective-C++ compiler for creating a library libQTDynamicGamera.dylib. This library is linked to the toolkit and copied into /usr/local/lib.

Linux

For Linux there is a wrapper WebcamV4l around libv4l2. On a Debian based system you have to install the packages.

sudo apt-get install libv4l-0 libv4l-dev

This wrapper is compiled using Gamera's standard plugin build mechanism.

Windows

For Windows there is a wrapper which uses DirectShow, which is part of Windows.