libwebcam

How to use

Install library using installation guide.

In source code:

  • Include webcam.h header file
  • Enumerate for available webcams
  • Setup webcam::video_settings using enumerated video parameters
  • Create instance of webcam::device passing number of device and video_settings
  • Open device
  • Read images
  • Close device
  • Wrap code in try-catch block

    • Link against webcam library 

    ...
#include <libwebcam/webcam.h> //include header
...
int main(){
  try{
    //enumerate for available webcams
    const webcam::device_info_enumeration enumeration =
      webcam::enumerator::enumerate();
    const size_t count = enumeration.count();
    if (count == 0){//if there is no webcam available... exit
      std::cout << "There is no webcam available on this computer";
      return 0;
    }

    //get first enumerated settings
    const webcam::device_info device_info = enumeration.get(0);
    const webcam::video_info_enumeration & video_info_enum =
      device_info.get_video_info_enumeration();
    const webcam::video_info & video_info = video_info_enum.get(0);

    //setup video_settings
    webcam::video_settings video_settings;
    video_settings.set_format(video_info.get_format());
    video_settings.set_resolution(video_info.get_resolution());
    video_settings.set_fps(1);

    const unsigned char device_number = 1;//setup device number
    webcam::device device(device_number, video_settings);
    device.open();//open device
    while(...){
      webcam::image * image = device.read();//read images
      ...
      delete image;//delete unused image
    }
    device.close();//close device
  }
  catch (const webcam::webcam_exception & exc_){
    std::cout << "error occured: " << exc_.what() << std::endl;
  }
}

    Important notes

  • Supported formats and resolutions

    • Before you open device make sure that webcam supports desired video format and resolution. Result of webcam::enumerator::enumerate() contains such information for each webcam. If you set up unsupported parameters there will be exception thrown.

    Under Windows you can also set up format_BMP24 for all webcams despite it is not listed in enumeration.
  • Device numbering

    • Device numbering starts from 1 not from 0. 

    webcam::device device(1, video_settings)//use first device;
webcam::device device(2, video_settings)//use second device;
  • read result is never NULL

    • read() method blocks only for specified amount of time. If there is problem with image acquisition returned webcam::image * is never NULL, but it may be empty. 

    webcam::video_settings video_settings;
video_settings.set_fps(5);//set 5 frame per second, read blocks for about 200 ms
webcam::image * image = device.read();//image is never NULL
if(image->is_empty()){//but it may be empty
  return;
}
  • Extended enumeration results
    • Enumeration implementation uses records stored in usb.ids file which is part of the library. It is regular text file containing such information as vendor and model of usb device identified by hexadecimal index. 
    ...
046c  Toshiba Corp., Digital Media Equipment
046d  Logitech, Inc.
  0801  QuickCam Home
  0802  Webcam C200
...
    Note: usb.ids must be present in working process folder in order to obtain extended enumeration results.
    Note: Extended enumeration is supported only on Windows but it will be on Linux soon.

    Installation

    Prepare sources

    Download libwebcam-master.zip. Extract content to desired libwebcam development directory.
    The installation guide differs for Windows and Linux, so it is described separately.
    Note: This guide was tested on Windows 8 and 10 but should work for other Windows version as well.

    The installation process produces static library webcam.lib (debug and release). As a result of installation, there will be Visual Studio project file which should be added to your solution.

    Complete required software

    The installation guide assumes you have already installed:

    Setup environment

  • Add cmake to your system path
    • Open command window and type: 
    cmake --version
    If cmake is not recognized, open Run window (press WIN + R) and type: 
    sysdm.cpl
    In advanced tab click Environment Variables button. Find Path variable in System Variables list. Click edit button and add your CMake\bin directory path (ie. C:\Program Files (x86)\CMake\bin).
    Note: Each path entry is separated by ;
    Reopen your command window and type again: 
    cmake --version
    If command is recognized, make sure cmake meets minimal version requirement. If command is not recognized, fix your cmake availibity in command window.
  • Update baseclass project
    • Launch Visual Studio IDE in administrator mode. Open baseclass.vcproj placed in Windows 7 SDK installation (ie. C:\Program Files\Microsoft SDKs\Windows\v7.1\Samples\multimedia\directshow\baseclasses\) and proceed coversion. Baseclass.vcproj will be converted to digestible baseclass.vxcproj version.
    Note: Visual Studio must be launched in administrator mode because conversion writes to write protected directory.
  • Build library
    • Build process creates (inside build directory):
    1. static webcam.lib library (debug and release),
    2. Visual Studio project files,
    3. Visual Studio solution.
    Open command window in administrator mode. Navigate to extracted libwebcam directory and type: 
    ms_cmake.bat build
    The command will start libwebcam build process.
    Note: This guide is compatibile with Debian based Linux distributions. If you have other distribution, use your platform specific commands.

    The installation process produces static library libwebcam.a. Source code and library are copied to default system library and source folders.

    Open terminal and ...
  • Install required software
    • Install c++ compiler, cmake and unzip. 
    sudo apt-get install g++
sudo apt-get install cmake
sudo apt-get install unzip
  • Build and install
    • cd to directory where your placed libwebcam-master.zip and extract files. 
    unzip libwebcam-master.zip
    cd to installation folder 
    cd libwebcam-master/installation/
    Run build script 
    sudo sh cmake.sh build
sudo sh cmake.sh install
    If everything went ok, you are able to use the library in your project.

    Examples

    Examples directory contains several short examples which demonstrates how to use libwebcam library.

  • bitmap_writer

    • Writes 100 bitmaps (dib) to disk.

    Note: This example works only on Windows.
  • enumerator

    • Enumerates and prints informations about webcams available on the computer.

  • grabber

    • Reads images for 5 seconds from first webcam with 10/s frame rate.

    Example building process requires libwebcam to be installed. Each example is build separetly. To build example open terminal/command window. Change directory to specified example directory. Type:

    For Linux: 
    ./cmake.sh build
    For Windows: 
    ms_cmake.bat build