Visual Servoing Platform  version 3.4.1 under development (2021-05-08)
vpUeyeGrabber Class Reference

#include <visp3/sensor/vpUeyeGrabber.h>

Public Member Functions

 vpUeyeGrabber ()
 
virtual ~vpUeyeGrabber ()
 
void acquire (vpImage< unsigned char > &I, double *timestamp_camera=NULL, std::string *timestamp_system=NULL)
 
void acquire (vpImage< vpRGBa > &I, double *timestamp_camera=NULL, std::string *timestamp_system=NULL)
 
std::string getActiveCameraModel () const
 
std::string getActiveCameraSerialNumber () const
 
std::vector< unsigned int > getCameraIDList () const
 
std::vector< std::string > getCameraModelList () const
 
std::vector< std::string > getCameraSerialNumberList () const
 
double getFramerate () const
 
unsigned int getFrameHeight () const
 
unsigned int getFrameWidth () const
 
bool isConnected () const
 
void loadParameters (const std::string &filename)
 
void open (vpImage< unsigned char > &I)
 
void open (vpImage< vpRGBa > &I)
 
bool setActiveCamera (unsigned int cam_index)
 
bool setColorMode (const std::string &color_mode)
 
bool setExposure (bool auto_exposure, double exposure_ms=-1)
 
bool setFrameRate (bool auto_frame_rate, double manual_frame_rate_hz=-1)
 
bool setGain (bool auto_gain, int master_gain=-1, bool gain_boost=false)
 
void setSubsampling (int factor)
 
void setVerbose (bool verbose)
 
void setWhiteBalance (bool auto_wb)
 

Detailed Description

Allows to grab images from an IDS camera using uEye SDK.

This class was tested with IDS UI328xCP-C and UI328xCP-C camera models.

By default, the first connected camera is the active one. The following code shows how to get information about all the connected cameras (index, id, model, serial number):

// Get info on connected cameras
std::vector<unsigned int> cam_ids = g.getCameraIDList();
std::vector<std::string> cam_models = g.getCameraModelList();
std::vector<std::string> cam_serials = g.getCameraSerialNumberList();
if (! cam_ids.size()) {
std::cout << "No camera detected. Plug a camera and try again..." << std::endl;
return EXIT_FAILURE;
}
std::cout << "Found " << cam_ids.size() << " cameras :"<< std::endl;
for (unsigned int i = 0; i < cam_ids.size(); i++) {
std::cout << (opt_camera == i ? " * Camera " : " Camera ") << i
<< " - ID: " << cam_ids[i] << " Model: " << cam_models[i] << " S/N: " << cam_serials[i] << std::endl;
}

If multiple cameras are connected, to select a specific one use the following code:

if (! g.setActiveCamera(opt_camera)) {
std::cout << "Unable to select camera " << opt_camera << std::endl;
return EXIT_FAILURE;
};

Create an image container, either for gray level or color images:

#ifdef USE_COLOR
vpImage<vpRGBa> I; // To acquire color images
#else
vpImage<unsigned char> I; // To acquire gray images
#endif

Then call open() to connect the active camera:

g.open(I);

From here you can modify camera default settings,

Depending on the settings, you may update image container size, especially if you want to create a window to display the image:

Now you can create an infinite loop to grab images:

while (1) {
g.acquire(I);
}
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 81 of file vpUeyeGrabber.h.

Constructor & Destructor Documentation

◆ vpUeyeGrabber()

vpUeyeGrabber::vpUeyeGrabber ( )

Default constructor. By default, the active camera is the first one that is found. To select a specific camera use setActiveCamera().

Definition at line 1136 of file vpUeyeGrabber.cpp.

◆ ~vpUeyeGrabber()

vpUeyeGrabber::~vpUeyeGrabber ( )
virtual

Destructor.

Definition at line 1145 of file vpUeyeGrabber.cpp.

Member Function Documentation

◆ acquire() [1/2]

void vpUeyeGrabber::acquire ( vpImage< unsigned char > &  I,
double *  timestamp_camera = NULL,
std::string *  timestamp_system = NULL 
)

Capture a new grayscale image.

Parameters
[out]I: Captured image.
[out]timestamp_camera: Time of image capture in milli-seconds with a resolution of 0.1 μs, or NULL if not wanted. The time of image capture is defined as:
  • The time when a (hardware or software) trigger event is received by the camera in trigger mode. The delay between the receipt of the trigger signal and the start of exposure depends on the sensor.
  • The time when the sensor starts to output image data in freerun mode. A rolling shutter sensors starts to output image data after exposure of the first row. With a global shutter sensor, image data is output after exposure of all rows.
[out]timestamp_system: Time with a resolution of 1 ms synchronized with the PC's system time, and resynchronized every 60 seconds. This may cause minor time shifts (average time about 3 ms). The format of the string is the following: YYYY:MM:DD:HH:MM:SS:mmm for year, month, day, hour, minute, second, millisecond.

To determine the exact interval between two image captures, it is therefore recommended to read out the camera timestamp provided in timestamp_camera.

See also
setColorMode()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1171 of file vpUeyeGrabber.cpp.

◆ acquire() [2/2]

void vpUeyeGrabber::acquire ( vpImage< vpRGBa > &  I,
double *  timestamp_camera = NULL,
std::string *  timestamp_system = NULL 
)

Capture a new color image.

Parameters
[out]I: Captured image.
[out]timestamp_camera: Time of image capture in milli-seconds with a resolution of 0.1 μs, or NULL if not wanted. The time of image capture is defined as:
  • The time when a (hardware or software) trigger event is received by the camera in trigger mode. The delay between the receipt of the trigger signal and the start of exposure depends on the sensor.
  • The time when the sensor starts to output image data in freerun mode. A rolling shutter sensors starts to output image data after exposure of the first row. With a global shutter sensor, image data is output after exposure of all rows.
[out]timestamp_system: Time with a resolution of 1 ms synchronized with the PC's system time, and resynchronized every 60 seconds. This may cause minor time shifts (average time about 3 ms). The format of the string is the following: YYYY:MM:DD:HH:MM:SS:mmm for year, month, day, hour, minute, second, millisecond.

To determine the exact interval between two image captures, it is therefore recommended to read out the camera timestamp provided in timestamp_camera.

See also
setColorMode()

Definition at line 1196 of file vpUeyeGrabber.cpp.

◆ getActiveCameraModel()

std::string vpUeyeGrabber::getActiveCameraModel ( ) const

Get active camera model.

See also
setActiveCamera(), getActiveCameraSerialNumber()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1206 of file vpUeyeGrabber.cpp.

◆ getActiveCameraSerialNumber()

std::string vpUeyeGrabber::getActiveCameraSerialNumber ( ) const

Get active camera serial number.

See also
setActiveCamera(), getActiveCameraModel()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1216 of file vpUeyeGrabber.cpp.

◆ getCameraIDList()

std::vector< unsigned int > vpUeyeGrabber::getCameraIDList ( ) const

Get camera ID list.

Returns
Vector of camera ID corresponding to each camera index. The size of this vector gives correponds also to the number of connected cameras.
See also
getCameraModelList(), getCameraSerialNumberList()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1228 of file vpUeyeGrabber.cpp.

◆ getCameraModelList()

std::vector< std::string > vpUeyeGrabber::getCameraModelList ( ) const

Get camera model list.

Returns
Vector of camera models corresponding to each camera index. The size of this vector gives correponds also to the number of connected cameras.
See also
getCameraIDList(), getCameraSerialNumberList()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1240 of file vpUeyeGrabber.cpp.

◆ getCameraSerialNumberList()

std::vector< std::string > vpUeyeGrabber::getCameraSerialNumberList ( ) const

Get camera serial number list.

Returns
Vector of camera serial numbers corresponding to each camera index. The size of this vector gives correponds also to the number of connected cameras.
See also
getCameraIDList(), getCameraModelList()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1252 of file vpUeyeGrabber.cpp.

◆ getFrameHeight()

unsigned int vpUeyeGrabber::getFrameHeight ( ) const

Return image width captured by the active camera.

Warning
Image width could differ from the one returned by open() depending on the subsampling settings loaded by loadParameters()
See also
open(), getFrameWidth()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1275 of file vpUeyeGrabber.cpp.

◆ getFramerate()

double vpUeyeGrabber::getFramerate ( ) const

Returns the current number of frames actually captured per second. This function needs to be called after acquire().

See also
acquire()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1263 of file vpUeyeGrabber.cpp.

◆ getFrameWidth()

unsigned int vpUeyeGrabber::getFrameWidth ( ) const

Return image height captured by the active camera.

Warning
Image width could differ from the one returned by open() depending on the subsampling settings loaded by loadParameters()
See also
open(), getFrameHeight()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1287 of file vpUeyeGrabber.cpp.

◆ isConnected()

bool vpUeyeGrabber::isConnected ( ) const

Return true if a camera is connected, false otherwise.

Definition at line 1296 of file vpUeyeGrabber.cpp.

◆ loadParameters()

void vpUeyeGrabber::loadParameters ( const std::string &  filename)

Load camera parameters from an .ini file.

Parameters
[in]filename: Camera parameters file that contains camera settings. Such a file could be produced using ueyedemo binary provided with IDS uEye Software Suite
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1306 of file vpUeyeGrabber.cpp.

◆ open() [1/2]

void vpUeyeGrabber::open ( vpImage< unsigned char > &  I)

Starts the driver and establishes the connection to the camera.

Parameters
[out]I: Grayscale image that is resized to match the capture settings.
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1315 of file vpUeyeGrabber.cpp.

◆ open() [2/2]

void vpUeyeGrabber::open ( vpImage< vpRGBa > &  I)

Starts the driver and establishes the connection to the camera.

Parameters
[out]I: Color image that is resized to match the capture settings.

Definition at line 1324 of file vpUeyeGrabber.cpp.

◆ setActiveCamera()

bool vpUeyeGrabber::setActiveCamera ( unsigned int  cam_index)

Select a camera from the camera list.

Parameters
cam_index: Camera index.
Returns
True if successful, false otherwise.
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1334 of file vpUeyeGrabber.cpp.

◆ setColorMode()

bool vpUeyeGrabber::setColorMode ( const std::string &  color_mode)

Updates active camera color mode.

Warning
Before caling this function the connexion with the active camera should be opened.
Parameters
[in]color_mode: Desired color mode. Admissible values are "MONO8", "RGB8" or "RGB32".
Note
- When acquiring gray level images using acquire(vpImage<unsigned char> &) we strongly recommend to set color mode to "MONO8".
- When acquiring color level images using acquire(vpImage<vpRGBa> &) we strongly recommend to set color mode to "RGB32".
Returns
true if color mode is applied, false if the color mode is unsupported.
See also
open(), setExposure(), setFrameRate(), setGain(), setSubsampling(), setWhiteBalance()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1354 of file vpUeyeGrabber.cpp.

◆ setExposure()

bool vpUeyeGrabber::setExposure ( bool  auto_exposure,
double  exposure_ms = -1 
)

Updates active camera exposure / shutter either to auto mode, or to specified manual parameters.

Warning
Before caling this function the connexion with the active camera should be opened.
Parameters
[in]auto_exposure: When true enable camera's hardware auto exposure / shutter. This function returns false if the camera does not support auto exposure mode. When set to false, set manual exposure time.
[in]exposure_ms: Manual exposure setting time in ms. Valid value range depends on active camera pixel clock rate.
Returns
True if successful, false otherwise.
See also
open(), setColorMode(), setFrameRate(), setGain(), setSubsampling(), setWhiteBalance()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1372 of file vpUeyeGrabber.cpp.

◆ setFrameRate()

bool vpUeyeGrabber::setFrameRate ( bool  auto_frame_rate,
double  manual_frame_rate_hz = -1 
)

Updates active camera frame rate either to auto mode, or to a specified manual value.

Enabling auto frame rate mode requires to enable auto shutter mode. Enabling auto frame rate mode will disable auto gain mode.

Warning
Before caling this function the connexion with the active camera should be opened.
Parameters
[in]auto_frame_rate: Updates camera's hardware auto frame rate mode. When true enable auto frame rate mode. When set to false, enables manual frame rate mode.
[in]manual_frame_rate_hz: Desired manual frame rate in Hz. Valid value range depends on current camera pixel clock rate. This parameter is only used when auto frame rate is disabled.
Returns
True if successful, false otherwise.

A typical usage is the following:

g.open(I);
if (! g.setFrameRate(true)) {
std::cout << "Unable to set auto frame rate" << std::endl;
double manual_fps = 10.; // 10 Hz is required if auto frame rate is not possible
if (g.setFrameRate(false, manual_fps)) {
std::cout << "Framerate set to: " << manual_fps << std::endl;
}
}
See also
open(), setColorMode(), setExposure(), setGain(), setSubsampling(), setWhiteBalance()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1407 of file vpUeyeGrabber.cpp.

◆ setGain()

bool vpUeyeGrabber::setGain ( bool  auto_gain,
int  master_gain = -1,
bool  gain_boost = false 
)

Updates active camera gain either to auto mode, or to specified manual parameters.

Auto gain mode is disabled if auto frame rate mode is enabled.

Warning
Before caling this function the connexion with the active camera should be opened.
Parameters
[in]auto_gain: Updates camera's hardware auto gain mode.
  • Set to true to enable auto gain. If this mode is not supported, returns false.
  • Set to false, to set manual gain and enable/disable gain boost/
[in]master_gain: Manual master gain percentage in range 0 - 100.
[in]gain_boost: Only in manual mode, enable/disable gain boost.
Returns
True if successful, false otherwise.
See also
open(), setColorMode(), setExposure(), setFrameRate(), setSubsampling(), setWhiteBalance()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1428 of file vpUeyeGrabber.cpp.

◆ setSubsampling()

void vpUeyeGrabber::setSubsampling ( int  factor)

Updates active camera image subsampling factor to reduce image size.

Warning
Before caling this function the connexion with the active camera should be opened.
Parameters
[in]factor: Desired subsampling factor. The number of rows and columns of the resulting image corresponds to the full resolution image size divided by this factor.
See also
open(), setColorMode(), setExposure(), setFrameRate(), setGain(), setWhiteBalance()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1443 of file vpUeyeGrabber.cpp.

◆ setVerbose()

void vpUeyeGrabber::setVerbose ( bool  verbose)

Enable/disable verbose mode.

Parameters
[in]verbose: true to enable, false to disable verbose mode.

Definition at line 1468 of file vpUeyeGrabber.cpp.

◆ setWhiteBalance()

void vpUeyeGrabber::setWhiteBalance ( bool  auto_wb)

Enables or disables the active camera auto white balance mode.

Warning
Before caling this function the connexion with the active camera should be opened.
Parameters
auto_wb: If true enable auto white balance mode. If false, disable auto white balance mode.
See also
open(), setColorMode(), setExposure(), setFrameRate(), setGain(), setSubsampling()
Examples:
tutorial-grabber-ids-ueye.cpp.

Definition at line 1458 of file vpUeyeGrabber.cpp.