Webcam toolkit

Last modified: June 10, 2015

Contents

Editor:Tim Altmann, Christian Brandt, Christoph Dalitz
Version:1.1.2

This toolkit is a toolkit for getting single video frames from a Webcam.

It is based on results from Tim Altmann's bachelor thesis.

T. Altmann: "Automatische Erkennung gezeichneter Figuren". Bachelor Thesis, Faculty of Electrical Engineering and Computer Science, Niederrhein University of Applied Sciences, Krefeld, 2011

Using the toolkit

The toolkit can be used interactively from the Gamera GUI or automatically from python scripts:

Extending the toolkit

The toolkit includes wrappers for different external webcam drivers for Linux, MacOS X, and Windows. If you want to add an additional driver, please have a look at the documentation on Driver Wrappers.

Installation

We have tested the toolkit on Linux, MacOS X and Windows. See the prerequisites listed below for additionally required third party libraries. If your operating system or video access library is not yet supported, please have a look on the documentation on Driver wrappers to learn how to add additional drivers.

Prerequisites

The Webcam toolkit requires a working installation of the following software:

  • Gamera 3.x, as available from the Gamera website. It is strongly recommended that you use a recent version.
  • The appropriate video access library for your operating system:
    • On Linux, you need Video4Linux. This usually is included in the packages libv4l and lib4vl-dev of your Linux distribution.
    • On Windows, the library DirectShow is already shipped with the OS.
    • On MacOS X, the library QTkit is already shipped with the OS.

If you want to generate the documentation, you will need two additional third-party Python libraries:

  • docutils for handling reStructuredText documents.
  • pygments for colorizing source code.

Note

It is generally not necessary to generate the documentation because it is included in file releases of the toolkit.

Building and Installing

To build and install this toolkit, go to the base directory of the toolkit distribution and run the setup.py script as follows:

# 1) compile
python setup.py build

# 2) install
sudo python setup.py install

Command 1) compiles the toolkit from the sources and command 2) installs it. As the latter requires root privilegue, you need to use sudo on Linux and MacOS X. On Windows, sudo is not necessary.

If you want to regenerate the documentation, go to the doc directory and run the gendoc.py script. The output will be placed in the doc/html/ directory. The contents of this directory can be placed on a webserver for convenient viewing. Note that you must install the ttolkit before building the documentation. Otherwise gendoc.py will not find the class documentation.

Installing without root privileges

The above installation with python setup.py install will install the toolkit system wide and thus requires root privileges. If you do not have root access (Linux) or are no sudoer (MacOS X), you can install the Webcam toolkit into your home directory. Note however that this also requires that Gamera is installed into your home directory. It is currently not possibole to install Gamera globally and only toolkits locally.

Here are the steps to install both Gamera and the webcam toolkit into ~/python:

# install Gamera locally
mkdir ~/python
python setup.py install --prefix=~/python

# build and install the webcam toolkit locally
export CFLAGS=-I~/python/include/python2.x/gamera
python setup.py build
python setup.py install --prefix=~/python

Moreover you should set the following environment variables in your ~/.profile:

# search path for python modules
export PYTHONPATH=~/python/lib/python

Uninstallation

If you have used the binary installer for Windows you can simply uninstall using the Windows Software Manager.

If you have installed the toolkit from the sources, you need to remove the installed files manually, because Python's distutils mechanism does not support uninstallation. These include

  • the installed library files of the toolkit
  • On MacOS X: /usr/local/lib/libQTDynamicGamera.dylib

All python library files of this toolkit are installed into the gamera/toolkits/webcam subdirectory of the Python library folder. Thus it is sufficient to remove this directory for an uninstallation.

Where the python library folder is depends on your system and python version. Here are the folders that you need to remove on MacOS X and Ubuntu Linux ("2.x" stands for the python version; replace it with your actual version):

  • MacOS X: /Library/Python/2.x/site-packages/gamera/toolkits/webcam
  • Ubuntu Linux: /usr/local/lib/python2.x/dist-packages/gamera/toolkits/webcam

About this documentation

The documentation was written by Christian Brandt based on the documentation for some other toolkits by Christoph Dalitz. Permission is granted to copy, distribute and/or modify this documentation under the terms of the Creative Commons Attribution Share-Alike License (CC-BY-SA) v3.0. In addition, permission is granted to use and/or modify the code snippets from the documentation without restrictions.