The dragonfly2 framegrabber device driver can acquire RGB color images in 320x240 or 640x480 resolutions.

Collaboration diagram for dragonfly2:

The dragonfly2 framegrabber device driver can acquire RGB color images in 320x240 or 640x480 resolutions.

The dragonfly2raw framegrabber device driver can acquire raw format images in 640x480 resolution.

Description

The dragonfly framegrabber device driver is based on libdc1394-2.

It can acquire RGB color images in 320x240 or 640x480 resolutions. In 640x480 there are two options: Bayer decoding performed on board by the camera or Bayer pattern decoding performed by the driver. In the second mode the bandwidth required to the Firewire bus is lower, and thus the framerate can be up to 60 fps. In the first mode the framerate is limited to 15 fps with two cameras on the same channel. Moreover, once the resolution is chosen, the image can be cropped on board by the camera before the transfer on the Firewire bus.

These functionalities are made available thought two YARP devices: dragonfly2 (for RGB images) and dragondly2raw (for raw images with Bayer encoding).

Runtime parameters can be changed using the graphical interface: icub_framegrabbergui2.

Libraries

libdc1394-2 (Linux) PGRFlyCapture (Windows)

Parameters

–name // image output port

–video_type // 1: RGB 320x240, 2: RGB 640x480, 3: RGB 640x480 (default) software Bayer decoding (higher fps)

–width|size_x // width image cropping (limited to image size)

–height|size_y // height image cropping (limited to image size)

–port_number // Firewire channel (need to specify only if you have more than one firewire card)

–guid // camera global unique 64 bit identifier WARNING: replaces –d

–d // camera unit number DEPRECATED

–white_balance // red and blue balance, values are normalized betwen 0.0 and 1.0

–feature // camera feature setting, normalized between 0.0 and 1.0 (features listed below)

The video_type parameter

The video_type parameter determines how images are acquired by the dragonfly chip.

-video_type 1: the image is acquired by the Dragonfly2 camera in 320x240 resolution as RGB color image, and transferred to the framegrabber driver memory buffer in this format. The Firewire bandwidth allows maximum framerate (60 fps) with two cameras. If specified, the –width and –height parameters will '''crop''' the image to the specified dimension.

-video_type 2: the image is acquired by the Dragonfly2 camera in 640x480 resolution as RGB color image, and transferred to the framegrabber driver memory buffer in this format. The Firewire bandwidth allows 15 fps with two cameras. If specified, the –width and –height parameters will '''crop''' the image to the specified dimension.

-video_type 3: the image is acquired as a raw Bayer pattern 640x480 image, and transferred in this format to the framegrabber driver memory buffer. In this way, the bandwidth required to the Firewire bus is lower than in the previous format, allowing 60 fps. The Bayer decoding to the usual RGB format provided by the DragonflyDeviceDriver2 framegrabber is performed at software level by the driver itself. If specified, the –width and –height parameters will '''crop''' the original 640 x 480 image to the specified dimension.

Port, Unit number and 64 bit Global Unique Identifier

Many cameras can coexist on the same Firewire bus (port), sharing the available bandwidth. Each camera connected to the same Firewire bus is associated to a unit number. Port numbers, as well as unit numbers, are assigned increasingly starting from 0. The iCub robot has one only Firewire card, and thus its port number is always 0 (can be omitted). The two left and right cameras will be unit 0 and 1, but unfortunately this association is not deterministic, and thus the Global Unique Identifier (guid) must be used in order to univokely identify a camera. The yarpdev device driver supports configuration files, thus the most convenient way to deal with GUIDs is putting them in .ini files that will be passed to yarpdev together with all the other parameters as follows:

yarpdev –from camera/dragonfly2_config_left.ini yarpdev –from camera/dragonfly2_config_right.ini

In the latest iCub software releases the .ini files are already supplied in app/robots/iCubXXXnn/camera folders. The –d option must be replaced in them by assigning the guid of the corresponding camera to the guid parameter. The following configuration file dragonfly2_config_left.ini

device grabber
subdevice dragonfly2
width 320
height 240
video_type 1
white_balance 0.506 0.494
gain 0.312
shutter 0.913
name /icub/cam/left
brightness 0
DR2
stamp
sharpness 0.5
hue 0.48
gamma 0.4
saturation 0.271
framerate 30
d 0
#guid <64bit global identifier, without the leading 0x> then remove the d option
will become after configuration, if (for example) A0BB98F34560AAB5 is the guid of the left camera:

device grabber
subdevice dragonfly2
width 320
height 240
video_type 1
white_balance 0.506 0.494
gain 0.312
shutter 0.913
name /icub/cam/left
brightness 0
DR2
stamp
sharpness 0.5
hue 0.48
gamma 0.4
saturation 0.271
framerate 30
guid A0BB98F34560AAB5
The configuration files already present in the /app/robots/iCubXXXnn/camera folder are:

dragonfly_config_left.ini
dragonfly_config_right.ini
dragonfly_config_left_bayer_320_240.ini
dragonfly_config_right_bayer_320_240.ini
dragonfly_config_left_bayer_640_480.ini
dragonfly_config_right_bayer_640_480.ini

How to obtain GUID from a camera

Execute from terminal:

yarpdev –device grabber –subdevice dragonfly 2 –name /foocam0 –d 0

The driver will answer something like:

---— Camera information ---—
Vendor : Point Grey Research
Model : Dragonfly2 DR2-03S2C-EX
Unit : 0
Specifications ID : 0xa02d
Software revision : 0x102
IIDC version code : 548
Unit directory offset : 0x428
Unit dependent directory offset : 0x440
Commands registers base : 0xf00000
Unique ID : 0x00b09d01006fb1fb <== THIS IS THE INFORMATION THAT YOU NEED!!!
Vendor ID : 0xb09d
Model ID : 0x1
Advanced features found at offset : 0xf01000
1394b mode capable (>=800Mbit/s) : Yes
Platform backend : juju
---— Camera platform-specific information ---—
Device filename : /dev/fw2
Now, from another terminal, execute

yarpview –name /fooview0
yarp connect /foocam0 /fooview0
and check in the viewer if the camera is the left or right iCub eye. Supposing that it is the left one, write the guid parameter in the dragonfly2_config_left*.ini files as shown in the former section. Do the same for the other camera, using unit number 1:

yarpdev –device grabber –subdevice dragonfly 2 –name /foocam1 –d 1
yarpview –name /fooview1
yarp connect /foocam1 /fooview1
and set the corresponding guid in the other camera's .ini files, without leading 0x.

Features

brightness
exposure
sharpness
hue
saturation
gamma
shutter
gain
iris

Please notice that ''exposure'' is an auto mode, if set it controls ''gain'' and ''shutter'' parameters in order to match the desired ''exposure''.

Ports Accessed

None.

Ports Created

The dragonfly device driver is usually executed combined with a network wrapper grabber (called grabber, see examples below) which reads images from the driver and streams them on the network. The grabber opens the followig ports:

Output ports:

<as specified by --name> streams out a yarp::sig::ImageOf<yarp::sig::PixelRgb> which contains the image grabbed by the Dragonfly camera.

Input ports:

<as specified by --name> input port to control the camera features and acquisition modes, accept a yarp::os::Bottle. The FrameGrabberGui module connects to this port.

Input Data Files

None.

Output Data Files

None.

Configuration Files

None.

Tested OS

Linux and Windows.

Example Instantiation of the Module

Usage syntax:

yarpdev –device grabber –subdevice dragonfly2 –name <yarp port name> [–video_type <type>] [–width|size_x <W> –height|size_y <H>] [–port_number <pn>] [–guid <64_bit_camera_unique_identifier>] [–white_balance <red_value> <blue_value>] [–feature <parameter>] [...]

yarpdev –device grabber –subdevice dragonfly2raw –name <yarp port name> [–width|size_x <W> –height|size_y <H>] [–port_number <pn>] [–guid <64_bit_global_unique_identifier>] [–white_balance <red_value> <blue_value>] [–feature <parameter>] [...]

WARNING: the old –d <unit_number> parameter is still working but deprecated, please use –guid <64_bit_global_unique_identifier> instead, because –d <unit_number> camera has become non deterministic in left/right assignment in latest linux releases.

Example:

yarpdev –device grabber –subdevice dragonfly2 –name /icub/cam/left –guid AB10980D6656E455 [...]

yarpdev –device grabber –subdevice dragonfly2 –name /icub/cam/right –guid 98FF0666E478A001 [...]

yarpdev –device grabber –subdevice dragonfly2raw –name /icub/cam/left –guid AB10980D6656E455 [...]

yarpdev –device grabber –subdevice dragonfly2raw –name /icub/cam/right –guid 98FF0666E478A001 [...]

DEPRECATED:

yarpdev –device grabber –subdevice dragonfly2 –name /icub/cam/right –d 1|0 [...]

yarpdev –device grabber –subdevice dragonfly2 –name /icub/cam/left –d 0|1 [...]

yarpdev –device grabber –subdevice dragonfly2raw –name /icub/cam/left –d 0|1 [...]

yarpdev –device grabber –subdevice dragonfly2raw –name /icub/cam/right –d 1|0 [...]

Author: Paul Fitzpatrick, Lorenzo Natale, Giorgio Metta, Alessandro Scalzo

CopyPolicy: Released under the terms of the GNU GPL v2.0.

This file can be edited at /src/libraries/icubmod/dragonfly2/common/DragonflyDeviceDriver2.h