WebCam Sample

Article
03/01/2012

Glossary Item Box

Robotics Common: WebCam

Technology Samples: IP-based Camera Sample

Microsoft Robotics Developer Studio

WebCam Sample

The Webcam service provides a Decentralized Software Services (DSS) service that captures frames from a webcam attached to a PC running a DSS Node.

This sample is provided in the C# language. You can find the project files for this sample at the following location under the Microsoft Robotics Developer Studio installation folder:

Samples\Sensors\WebCam

Prerequisites

Hardware and Software

A Webcam and its Windows drivers. The camera must have either a DirectShow capture driver, or support the VideoForWindows capture model. Webcams are usually connected to the computer using either USB or IEEE 1394.

You will also need Microsoft Internet Explorer or another conventional web browser.

Running the Sample

Start the DSS Command Prompt from the Start > All Programs menu.

Start a DssHost node and create an instance of the service by typing the following command:

dsshost /p:50000 /m:"samples\config\WebCam.manifest.xml"

This starts the service and you see the "Manifest load complete" message when the manifest is loaded.

Inspecting the Service

Start Internet Explorer (IE) and type the following URI in the address bar:

https://localhost:50000/webcam

The state of the Webcam service displays in your browser. The Webcam service supports direct access from a web browser to see the latest captured image from the currently selected camera. To see a single frame, use one of the following URIs:

https://localhost:50000/webcam/jpg
https://localhost:50000/webcam/gif
https://localhost:50000/webcam/png
https://localhost:50000/webcam/bmp

To change the currently selected camera, if more than one is available, or to change the capture format and to see streamed images from the camera, go to the following URI:

https://localhost:50000/webcam/live

Understand the Different Webcam Service State Elements

The Webcam service state has 6 elements:

Cameras - a list of cameras currently attached to the computer and available for use by the webcam service.
Selected - the currently selected camera, if any.
ImageSize - the size of the most recently captured frame in pixels.
LastFrameUpdate - the timestamp of the most recently captured frame.
CaptureFile - the path used to save each captured frame to file.
Quality - quality coefficient used by the JPEG codec when saving captured frames to file, 0.0 - 1.0, where 1.0 is highest quality.

Using the Webcam Service

A service can subscribe to the Webcam service. The webcam service sends the following notifications:

Replace - when the entire state is replaced.
UpdateFrame - when the webcam service has captured a new frame.
UpdateDevice - when the webcam service starts using a new device (Camera).

The Webcam service does not send captured frames to subscribers. It only sends the information that there is a new frame available.

To get the most recently captured frame from the webcam service send a QueryFrame message. The QueryFrameRequest type has two parameters:

Format - a GUID identifying the ImageFormat to use in transmitting the frame.
Useable values are defined in static properties in the class System.Drawing.Imaging.ImageFormat. For example: ImageFormat.Jpeg.Guid.
Size - a requested image size to reply with.

If the Format field is set to Guid.Empty, then the QueryFrameResponse.Frame field contains raw image data, in the PixelFormat.Format24bppRgb format. When requesting a raw frame the Size field in the request is ignored.

Otherwise the Frame field contains a binary serialization of the image using the appropriate image format.

The following code fragment demonstrates one way to use the QueryFrame message to get the most recently captured image.

Fault fault = null;
webcam.QueryFrameRequest request = new webcam.QueryFrameRequest();
webcam.QueryFrameResponse response = null;

request.Format = ImageFormat.Jpeg.Guid;

yield return Arbiter.Choice(
    _webcamPort.QueryFrame(request),
    delegate(webcam.QueryFrameResponse success)
    {
        response = success;
    },
    delegate(Fault f)
    {
        fault = f;
    }
);

if (fault != null)
{
    yield break;
}

Bitmap frame = null;

using(MemoryStream stream = new MemoryStream(response.Frame, false))
{
    frame = new Bitmap(stream);
}

Setting the Initial State

The Webcam service supports the Initial State partner. Initial state is used to configure:

Which camera to use, if more than one is supported.
Default is the first camera found.
What frame rate for capture.
Default is the highest supported by the camera.
What size frame to capture.
Default is the largest frame size supported at the highest frame rate.
The file in which to save captured frames.
The default is not to save captured frames.
The quality to save at.
Default is 0.

The manifest file included with the webcam service sample code shows how to use an initial state config file.

To set which camera to use, the Selected element in the state needs to be populated. Cameras are identified by the DevicePath element. This is specific to the particular camera in question.

To set which frame rate to capture at, you need to specify the Format field within the Selected element. In the Format field, you need to specify the MaxFramesPerSecond value.

To set which frame capture size, specify the Width and Height fields. It is only possible to specify a size that the camera supports. The supported sizes can be deduced from the SupportedFormats list which is part of the CameraInstance element within the list of Cameras on the state.

To set the file to save captured images to, provide a valid fully qualified filename in the CaptureFile element.

To set the quality to save captured images at, provide a number between 0 and 1 in the Quality element.

A config file that demonstrates setting all of these properties would be as follows:

<?xml version="1.0" encoding="utf-8"?>
<WebCamState xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns="https://schemas.microsoft.com/robotics/2006/05/multidevicewebcamservice.html">
  <Cameras/>
  <Selected>
    <FriendlyName>1394 Desktop Video Camera</FriendlyName>
    <DevicePath>\\?\1394#unibrain&amp;fire-i_1.2#4386000061431408#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\global</DevicePath>
    <SupportedFormats/>
    <Format>
      <Width>320</Width>
      <Height>240</Height>
      <MinFramesPerSecond>0</MinFramesPerSecond>
      <MaxFramesPerSecond>4</MaxFramesPerSecond>
      <Compression>UYVY</Compression>
    </Format>
  </Selected>
  <CaptureFile>c:\capture.stream</CaptureFile>
  <Quality>0.75</Quality>
</WebCamState>

A config file that selected a particular camera, but used default capture size and rate, and didn't store captured frames to a file would be as follows:

<?xml version="1.0" encoding="utf-8"?>
<WebCamState xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns="https://schemas.microsoft.com/robotics/2006/05/multidevicewebcamservice.html">
  <Cameras/>
  <Selected>
    <FriendlyName>1394 Desktop Video Camera</FriendlyName>
    <DevicePath>\\?\1394#unibrain&amp;fire-i_1.2#4386000061431408#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\global</DevicePath>
    <SupportedFormats/>
  </Selected>
</WebCamState>

Using the Webcam Replay Service

The capture file that can be stored by the webcam service is a simple sequence of frames. Each frame is composed of 3 elements:

Timestamp - A 64-bit little-endian representation of the frame's timestamp.
This can be reconstructed into a DateTime structure by calling DateTime.FromBinary();
Length - A 32-bit little-endian value containing the length of the following frame data.
Data - An array of bytes containing the frame.
This is encoded by the webcam service as a JPEG. The webcam replay service can use any format that GDI+ can detect and load safely.

The Webcam Replay service can play one of these files and supports the generic webcam contract. This allows a session to be recorded once with the webcam service and used repeatedly with the replay service.

To start the Webcam Replay service, start a node by using following command line:

dsshost /p:50000 /m:"samples\config\WebCamReplay.manifest.xml"

This uses a config file named webcamreplay.config.xml which contains the following:

<?xml version="1.0" encoding="utf-8"?>
<WebCamState xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns="https://schemas.microsoft.com/robotics/2006/05/multidevicewebcamservice.html">
  <Cameras/>
  <CaptureFile>c:\capture.stream</CaptureFile>
</WebCamState>

The Webcam Replay service requires an initial state document and will not start without one.

Summary

This sample covered the following:

Running the Sample
Inspecting the Service
Understand the Different Webcam Service State Elements
Using the Webcam Service
Setting the Initial State
Using the Webcam Replay Service

See Also

Robotics Common: WebCam

Technology Samples: IP-based Camera Sample

WebCam Sample

WebCam Sample

Contents:

Prerequisites

Hardware and Software

Running the Sample

Inspecting the Service

Understand the Different Webcam Service State Elements

Using the Webcam Service

Setting the Initial State

Using the Webcam Replay Service

Summary

Additional resources