Frame Grabber & Camera Drivers

Introduction

Along with the development libraries, SAL3D provides also drivers from some frame grabbers and for some cameras, allowing an easy acquisition through the FrameGrabber interface.

Specified in each driver is the version of the manufacturer SDK used to build it. It should be possible to recompile the driver (as we provide the sources) for newer versions of the SDK, provided that the API has not changed.

Frame Grabber drivers list:

Camera drivers list:

Time-Of-Flight cameradrivers list:

Mesa Imaging TOF cameras (mesa.fgd) (only for 32-bit SAL3D)

Others:

File Frame Grabber (file.fgd)

In addition to the drivers included in the SAL3D package, some camera manufacturer provide examples to combine their cameras with SAL3D. This is the case of Automation Technology and Ximea. Automation Technology added to the GUI of their cameras SAL3D features like 3D metric calibration and the option to compute metric distance between points on a range map. Ximea includes on their website an example how to apply the peak detector on an image acquired using their cameras.

Silicon Software microEnable III/IV (sisome4.fgd)

Note:: The driver has been built using the SDK v5.0

This driver allows acquiring frames from a Silicon Software microEnable III/IV frame grabber card. It initializes the card from a MCF config file on first load of the driver. If the FrameGrabber::FrameGrabber constructor passes a null string parameter to the driver, on fgd loading it will pop up a Windows UI file open dialog to get the MCF file. Otherwise, the string parameter should be a pipe "|" separated list of the following parameters:

configfile: specifies a path to the MCF config file
hap: specifies a path to a HAP file
card: specifies the physical card to use (starting from 0)
port: specifies the port from the card to use (starting from 0)

For example:

configfile=c:\camera.mcf|card=1

Following is a list of considerations regarding the driver and the way it works:

On first load of the driver for a given board, the FrameGrabber object will grab from the active port set in the MCF file. On a second load (with a FrameGrabber object still allocated for that board), the new FrameGrabber object will grab from the non-active port in the previously set MCF file.
The acquired Frames will reference memory managed by the hardware FrameGrabber.
The FrameGrabber object will be finally unloaded when no Frame object points to the FrameGrabber memory. You can release the FrameGrabber memory for a Frame object using the Frame::copy() method.
Uses the ACQ_BLOCK acquisition method through Asynchronous Procedure Call.
Calling FrameGrabber::frame() blocks until a Frame is acquired. The FrameGrabber::wait() blocks until a Frame is acquired or a timeout happens, and it should be used before calling FrameGrabber::frame().
The FrameGrabber::wait() and FrameGrabber::frame() methods will block if the FrameGrabber::grab() method has not been called enabling the acquisition.
Freezing the acquisition flushes out the grabbed frames not acquired.
It was compiled and linked with the runtime 5.0.

DALSA Sapera supported cards (sapera.fgd)

Note:: The driver has been built using the SDK v7.00

This driver allows acquiring frames using the Sapera library backend. It has been tested and is known to work at least with the DALSA X64 XCelera-CL PX4. The configuration parameter fed to the constructor may be empty, in which case a dialog will appear to choose from a CCF configuration file. Otherwise, it must be a pipe "|" separated combination of the following parameters:

configfile: specifies a path to the CCF config file
server or serveridx: the name of the server, or index (0 should be the first frame grabber). If not specified, the first available is used.
device: the device number, 0 by default.
nbuffers: the number of buffers, 10 by default.
pixeldepth: the size in bits of a pixel of the camera.
ntaps: the number of taps used by the camera.
width: the width of the area captured by the camera.
height: the height of the area captured by the camera.

For example:

configfile=c:\port0.ccf|server=Xcelera-CL_PX4_1

Remarks:: It is possible to specify a configuration file and several of the other parameteres, like size. In this case, the ones prevailing are the ones specified through the parameter, not the ones in the configuration file.

Following is a list of some details concerning how the driver works:

The acquired Frames will reference memory managed by the hardware FrameGrabber.
The FrameGrabber object will be finally unloaded when no Frame object points to the FrameGrabber memory. You can release the FrameGrabber memory for a Frame object using the Frame::copy() method.
Calling FrameGrabber::frame() blocks until a Frame is acquired. The FrameGrabber::wait() blocks until a Frame is acquired or a timeout happens, and it should be used before calling FrameGrabber::frame().

Imperx supported cards (imperx.fgd)

Note:: The driver has been built using the SDK v1.2.0.78

This driver allows capturing frames from an Imperx frame grabber. It has been tested with a FrameLink Express card but it should work with other models.

The driver expects a configuration parameter. If it is empty, a dialog will appear asking for a configuration file. Otherwise, a pipe "|" separated list of the following parameters may be given (the configuration file is mandatory):

configfile: specifies a path to the CCF config file.
port: the port to use from the card.

Example:

configfile=c:\config.ccf|port=0

Warning:: The reconfig function is still not supported.

Matrox supported cards (matrox.fgd)

Note:: The driver has been built using the SDK v9.00.1950(R2)

This driver allows acquiring frames from a Matrox frame grabber card, and has been tested with a Solios eV-CL.

The configuration parameter fed to the constructor may be empty, in which case a dialog will appear to choose from a DCF configuration file. Otherwise, it must be a pipe "|" separated combination of the following parameters:

configfile: specifies a path to the DCF config file
sysdescriptor: specify the system descriptor (ex: M_SYSTEM_SOLIOS) (by default M_SYSTEM_DEFAULT)
sysnum: specify the system number (ex: 0) (by default M_DEFAULT, i.e. 0)
nbuffers: specify the number of buffers (10 by default)
pixeldepth: specify the data type (by default 8, you may need to check the Mil.h header file to look for proper values)
width: the width of the area captured by the camera.
height: the height of the area captured by the camera.

For example:

configfile=c:\config.dcf|sysnum=0

Following is a list of considerations regarding the driver and the way it works:

The acquired Frames will reference memory managed by the hardware FrameGrabber.
The FrameGrabber object will be finally unloaded when no Frame object points to the FrameGrabber memory. You can release the FrameGrabber memory for a Frame object using the Frame::copy() method.
Calling FrameGrabber::frame() blocks until a Frame is acquired. The FrameGrabber::wait() blocks until a Frame is acquired or a timeout happens, and it should be used before calling FrameGrabber::frame().
The FrameGrabber::wait() and FrameGrabber::frame() methods will block if the FrameGrabber::grab() method has not been called enabling the acquisition.
Freezing the acquisition flushes out the grabbed frames not acquired.

Bitflow supported cards (bitflow.fgd)

Note:: The driver has been built using the Bitflow SDK v5.40

This driver allows capturing frames from a BitFlow frame grabber.

The driver allows a configuration parameter. A pipe "|" separated list of the following parameters may be given:

channel: the acqusition channel (number, default 0)
nbuffers: number of buffers (default 100)
errors: "ignore" or "fatal"; how to behave on errors:

Example:

channel=1|nbuffers=50

Warning:: The reconfig function is still not supported.

IDS Camera (ids.fgd)

Note:: The driver has been built using the SDK v3.70

The IDS driver is tested and known to work with a USB microEye LE, but it should support any GigE or USB camera of the manufacturer.

Several configuration parameteres can be given to the driver through the configuration parameter, all of them separated by a pipe "|":

nbuffers: specifies the number of buffers, 50 by default.
device: use the camera with given CameraID. As the IDS manual says, 0 means any first camera, and 1-254 mean any CameraID predefined in the cameras. The user can configure the CameraID for each camera using the IDS tools.
f: fps, where n is the frames per second in case of mode live.
e: specify the exposure time in milliseconds.
p: in MHz, where n is the pixel clock.
r: (x,y,w,h) specifying the region of interest starting at x,y and size w,h.
m: (l or t) specifying the operation mode. l for live video, i.e., continuously acquiring, and t for external trigger.

You can check your camera manual for valid values of those parameters.

Example:

nbuffers=512|f=30|r=0,8,128,256|m=l would start a continuous acquisition without the need for a trigger at 30 fps, of the region between x=0 and x=128, and y=8 and y=264 (8+256). The buffers used by the camera are set to 512 as well.

Point Grey Cameras (flycapture.fgd)

Note:: The driver has been built using the FlyCapture SDK v2.1.03.05(r5)

The FlyCapture driver is tested and known to work with a Firefly MV and Chameleon, but it should support any camera of the manufacturer.

Warning:: In order for the driver's lost frames method to work, the frame counter embedded information is enabled when the driver is loaded. This means that the first 4 pixels of the first row of the image are overwritten with this information.; The camera only accepts a ROI defined by multiples of 4. Not complying with this rule will make the driver load fail.

Several configuration parameteres can be given to the driver through the configuration parameter, all of them separated by a pipe "|":

nbuffers: specifies the number of buffers, 1000 by default.
device: use the Nth device. 0 by default.
e: specify the exposure time in milliseconds.
r: (x,y,w,h) specifying the region of interest starting at x,y and size w,h. Remember that all four parameters must be multiples of 4.
m: (l or t) specifying the operation mode. l for live video, i.e., continuously acquiring, and t for external trigger. By default, live.

You can check your camera manual for valid values of those parameters.

Example:

nbuffers=512|r=0,8,128,256|m=t" would start a triggered acquisition of the region between x=0 and x=128, and y=8 and y=264 (8+256). The buffers used by the camera are set to 512 as well.

Ximea cameras (ximea.fgd)

Note:: The driver has been built using the Ximea SDK v1.0

The Ximea driver is tested and known to work inside Currera cameras. but it should support any camera of the manufacturer.

Several configuration parameteres can be given to the driver through the configuration parameter, all of them separated by a pipe "|":

"d" downsampling : set binning/skiping mode
"e" exposure time : set exposure time in milliseconds
"g" gain : set camera gain in dB
"t" trigger : set live video(0) or ext. trigger(1) mode
"w" width : set image width
"h" height : set image height
"x" offset X : set horizontal offset in ROI
"y" offset Y : set vertical offset in ROI
"r" do image transpose : set 1 to transpose image

You can check your camera manual for valid values of those parameters.

Example:

b=1|g=5|e=150|t=0|w=150|h=1000|x=100|y=100|r=1

Mesa Imaging TOF cameras (mesa.fgd) (only for 32-bit SAL3D)

Note:: The driver has been built using the Mesa SDK v1.0.14.706

The driver does not accept any parameters by now, and can acquire both COP and Frame using the TOFFrameGrabber interface.

File Frame Grabber (file.fgd)

With this driver, Frames stored in files can be provided as Frames acquired through a FrameGrabber. This may help debugging the Frame processing part of a program. The supported Frame file types are related to the Frame::Frame constructor which reads the picture from a file.

When loading the driver, if the string parameter of the FrameGrabber::FrameGrabber constructor is null, it will pop up a dialog asking for a list of picture files to open. Otherwise it expects a parameter specifying either a picture file or a file containing a list of pictures to be opened, in the form:

image: specify an image file.
listfile: specify a file which contains a list of picture files, each in a separate line.

Example:

image=frame0.jpg

All files are read at the initialization of the FrameGrabber driver, and they are stored in memory until destruction of the object. This way, Frames can be delivered quickly to the program grabbing from the related FrameGrabber object, although being constrained by the virtual memory available to the program.

After delivering the last file on the list, the first file will be delivered on next FrameGrabber::frame(). The FrameGrabber::wait() function will never block.

On reconfiguration, the image files are re-read from the given parameter.