Visual Servoing Platform  version 3.6.1 under development (2024-03-18)
vpPylonGrabber Class Referenceabstract

#include <visp3/sensor/vpPylonGrabber.h>

+ Inheritance diagram for vpPylonGrabber:

Public Types

enum  UserSetName {
  USERSET_DEFAULT , USERSET_USERSET1 , USERSET_USERSET2 , USERSET_USERSET3 ,
  USERSET_UNKNOWN
}
 

Public Member Functions

virtual ~vpPylonGrabber ()
 
virtual void acquire (vpImage< unsigned char > &I)=0
 
virtual void acquire (vpImage< vpRGBa > &I)=0
 
virtual void close ()=0
 
virtual void connect ()=0
 
virtual void disconnect ()=0
 
virtual float getBlackLevel ()=0
 
virtual std::ostream & getCameraInfo (std::ostream &os)=0
 
virtual Pylon::CInstantCamera * getCameraHandler ()=0
 
virtual unsigned int getCameraIndex () const =0
 
virtual std::string getCameraSerial (unsigned int index)=0
 
virtual float getExposure ()=0
 
virtual float getFrameRate ()=0
 
virtual float getGain ()=0
 
virtual unsigned int getNumCameras ()=0
 
virtual float getGamma ()=0
 
virtual bool loadUserSet (UserSetName user_set)=0
 
virtual UserSetName getUserSetDefault ()=0
 
virtual bool isConnected () const =0
 
virtual bool isCaptureStarted () const =0
 
virtual void open (vpImage< unsigned char > &I)=0
 
virtual void open (vpImage< vpRGBa > &I)=0
 
virtual vpPylonGrabberoperator>> (vpImage< unsigned char > &I)=0
 
virtual vpPylonGrabberoperator>> (vpImage< vpRGBa > &I)=0
 
virtual float setBlackLevel (float blacklevel_value)=0
 
virtual void setCameraIndex (unsigned int index)=0
 
virtual void setCameraSerial (const std::string &serial)=0
 
virtual float setExposure (bool exposure_on, bool exposure_auto, float exposure_value)=0
 
virtual float setGain (bool gain_auto, float gain_value)=0
 
virtual float setFrameRate (float frame_rate)=0
 
virtual float setGamma (bool gamma_on, float gamma_value=1)=0
 
virtual bool saveUserSet (UserSetName user_set, bool set_default=false)=0
 
virtual bool setUserSetDefault (UserSetName user_set)=0
 
virtual void startCapture ()=0
 
virtual void stopCapture ()=0
 
Inherited functionalities from vpFramegrabber
unsigned int getHeight () const
 
unsigned int getWidth () const
 

Public Attributes

bool init
 

Protected Attributes

unsigned int height
 
unsigned int width
 

Detailed Description

Allows to grab images from a Basler camera using Pylon SDK. This is an abstract base class which can't be instantiated. Use vpPylonFactory functions to create class instances instead. Currently only GigE and USB3 cameras are supported.

To get a vpPylonGrabber, use the following code.

Factory singleton class to create vpPylonGrabber subclass instances.
@ BASLER_GIGE
Basler GigE camera.
static vpPylonFactory & instance()
Get the vpPylonFactory singleton.
vpPylonGrabber * createPylonGrabber(DeviceClass dev_class)
Create an object of vpPylonGrabber.

To use this class install first Pylon SDK
https://www.baslerweb.com/en/support/downloads/software-downloads/#type=pylonsoftware;version=all
Installation instructions included.

Once installed, configure ViSP using cmake to detect Pylon SDK and build ViSP to include Pylon SDK support.

This class was tested under Ubuntu with pylon 5.0.9 and the following cameras:

  • acA640-90gm
  • acA1600-60gm

This class is inspired by vpFlyCaptureGrabber with much simplified methods.

Examples
testPylonGrabber.cpp, and tutorial-grabber-basler-pylon.cpp.

Definition at line 96 of file vpPylonGrabber.h.

Member Enumeration Documentation

◆ UserSetName

Valid values for user set names.

Enumerator
USERSET_DEFAULT 

The default user set.

USERSET_USERSET1 

User set 1.

USERSET_USERSET2 

User set 2.

USERSET_USERSET3 

User set 3.

USERSET_UNKNOWN 

User set not supported.

Definition at line 106 of file vpPylonGrabber.h.

Constructor & Destructor Documentation

◆ ~vpPylonGrabber()

virtual vpPylonGrabber::~vpPylonGrabber ( )
inlinevirtual

Default destructor.

Definition at line 102 of file vpPylonGrabber.h.

Member Function Documentation

◆ acquire() [1/2]

virtual void vpPylonGrabber::acquire ( vpImage< unsigned char > &  I)
pure virtual

Acquire a gray level image from the active camera.

Parameters
I: Image data structure (8 bits image).

Implements vpFrameGrabber.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp, and tutorial-grabber-basler-pylon.cpp.

◆ acquire() [2/2]

virtual void vpPylonGrabber::acquire ( vpImage< vpRGBa > &  I)
pure virtual

Acquire a color image from the active camera.

Parameters
I: Image data structure (RGBa image).

Implements vpFrameGrabber.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ close()

virtual void vpPylonGrabber::close ( )
pure virtual

Stop active camera capturing images and disconnect the active camera.

If you want to use again this camera, you may call setCameraIndex(const unsigned int &) and open(vpImage<unsigned char> &) or open(vpImage<vpRGBa> &) to connect again the camera.

Implements vpFrameGrabber.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ connect()

virtual void vpPylonGrabber::connect ( )
pure virtual

Connect the active camera.

See also
disconnect()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ disconnect()

virtual void vpPylonGrabber::disconnect ( )
pure virtual

Disconnect the active camera.

See also
connect()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ getBlackLevel()

virtual float vpPylonGrabber::getBlackLevel ( )
pure virtual

Return blacklevel value in % or raw value. If the camera doesn't support blacklevel property, return an exception.

According to SFNC (standard feature naming convention) of GenICam standard, Black level is used instead of brightness.

See "Terminology Changes" section of the page: https://www.ptgrey.com/kb/11020?countryid=237

See also
setBlackLevel()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getCameraHandler()

virtual Pylon::CInstantCamera* vpPylonGrabber::getCameraHandler ( )
pure virtual

Return the handler to the active camera or nullptr if the camera is not connected. This function was designed to provide a direct access to the Pylon SDK to get access to advanced functionalities that are not implemented in this class.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ getCameraIndex()

virtual unsigned int vpPylonGrabber::getCameraIndex ( ) const
pure virtual

Return the index of the active camera.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ getCameraInfo()

virtual std::ostream& vpPylonGrabber::getCameraInfo ( std::ostream &  os)
pure virtual

Print to the output stream active camera information (serial number, camera model, camera vendor, sensor, resolution, firmware version, ...).

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getCameraSerial()

virtual std::string vpPylonGrabber::getCameraSerial ( unsigned int  index)
pure virtual

Return the serial id of a camera with index.

Parameters
index: Camera index.
See also
setCameraSerial()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getExposure()

virtual float vpPylonGrabber::getExposure ( )
pure virtual

Return exposure value in ms. If the camera doesn't support exposure property, return an exception.

According to SFNC (standard feature naming convention) of GenICam standard, Exposure is used and deprecates shutter.

See "Terminology Changes" section of the page: https://www.ptgrey.com/kb/11020?countryid=237

See also
setExposure()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getFrameRate()

virtual float vpPylonGrabber::getFrameRate ( )
pure virtual

Return camera capture framerate. If the camera doesn't support framerate property, return an exception.

See also
setFrameRate()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getGain()

virtual float vpPylonGrabber::getGain ( )
pure virtual

Return camera gain value in dB or raw value. If the camera doesn't support gain property, return an exception.

See also
setGain()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getGamma()

virtual float vpPylonGrabber::getGamma ( )
pure virtual

Return gamma correction value. If the camera doesn't support gamma property, return an exception.

See also
setGamma()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getHeight()

unsigned int vpFrameGrabber::getHeight ( ) const
inlineinherited

Return the number of rows in the image.

Examples
AROgre.cpp, AROgreBasic.cpp, and testPylonGrabber.cpp.

Definition at line 106 of file vpFrameGrabber.h.

◆ getNumCameras()

virtual unsigned int vpPylonGrabber::getNumCameras ( )
pure virtual

Get the number of cameras of specific subclasses. GigE, USB, etc.

Returns
Return the number of cameras connected on the bus GigE or USB.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ getUserSetDefault()

virtual UserSetName vpPylonGrabber::getUserSetDefault ( )
pure virtual

Gets the configuration set being used as the default startup set.

See also
setUserSetDefault()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ getWidth()

unsigned int vpFrameGrabber::getWidth ( ) const
inlineinherited

Return the number of columns in the image.

Examples
AROgre.cpp, AROgreBasic.cpp, and testPylonGrabber.cpp.

Definition at line 108 of file vpFrameGrabber.h.

◆ isCaptureStarted()

virtual bool vpPylonGrabber::isCaptureStarted ( ) const
pure virtual

Return true if the camera capture is started.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ isConnected()

virtual bool vpPylonGrabber::isConnected ( ) const
pure virtual

Return true if the camera is connected.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ loadUserSet()

virtual bool vpPylonGrabber::loadUserSet ( UserSetName  user_set)
pure virtual

Loads the selected configuration into the camera's volatile memory and makes it the active configuration set.

Parameters
user_setSee vpPylonGrabber::UserSetName for valid values.
Returns
true for finished, false otherwise.
See also
saveUserSet()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ open() [1/2]

virtual void vpPylonGrabber::open ( vpImage< unsigned char > &  I)
pure virtual

Connect to the active camera, start capture and retrieve an image.

Parameters
I: Captured image.

Implements vpFrameGrabber.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp, and tutorial-grabber-basler-pylon.cpp.

◆ open() [2/2]

virtual void vpPylonGrabber::open ( vpImage< vpRGBa > &  I)
pure virtual

Connect to the active camera, start capture and retrieve an image.

Parameters
I: Captured image.

Implements vpFrameGrabber.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ operator>>() [1/2]

virtual vpPylonGrabber& vpPylonGrabber::operator>> ( vpImage< unsigned char > &  I)
pure virtual

Operator that allows to capture a grey level image.

Parameters
I: The captured image.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ operator>>() [2/2]

virtual vpPylonGrabber& vpPylonGrabber::operator>> ( vpImage< vpRGBa > &  I)
pure virtual

Operator that allows to capture a color image.

Parameters
I: The captured image.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ saveUserSet()

virtual bool vpPylonGrabber::saveUserSet ( UserSetName  user_set,
bool  set_default = false 
)
pure virtual

Saves the current active configuration set into the selected user set.

Parameters
user_setSee vpPylonGrabber::UserSetName for valid values.
set_defaultWhether to set the configuration set to be used as the default startup set.
Returns
true for finished, false otherwise.
See also
loadUserSet()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ setBlackLevel()

virtual float vpPylonGrabber::setBlackLevel ( float  blacklevel_value)
pure virtual

Set camera blacklevel mode and parameter.

Parameters
blacklevel_value: This is the level of black in an image. A high blacklevel will result in a low amount of black in the image.
Returns
The measured blacklevel after applying the new setting.

According to SFNC (standard feature naming convention) of GenICam standard, Black level is used instead of brightness.

See "Terminology Changes" section of the page: https://www.ptgrey.com/kb/11020?countryid=237

See also
getBlackLevel()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ setCameraIndex()

virtual void vpPylonGrabber::setCameraIndex ( unsigned int  index)
pure virtual

If multiples cameras are connected on the bus, select the camera to dial with.

Parameters
index: Current camera index, a value comprised between 0 (the first camera found on the bus) and the number of cameras found and returned by getNumCameras() minus 1.

If two cameras are connected on the bus, setting index to one allows to communicate with the second one. This identifier is not unique. That is why, it is also possible to select a camera by its serial number, which is unique using setCameraSerial().

Exceptions
vpException::badValue: If the index is greater or equal to the number of cameras connected to the bus.

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp, and tutorial-grabber-basler-pylon.cpp.

◆ setCameraSerial()

virtual void vpPylonGrabber::setCameraSerial ( const std::string &  serial)
pure virtual

Set the current camera from its unique serial identifier.

Parameters
serial: Camera serial string.
See also
getCameraSerial()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Examples
testPylonGrabber.cpp.

◆ setExposure()

virtual float vpPylonGrabber::setExposure ( bool  exposure_on,
bool  exposure_auto,
float  exposure_value 
)
pure virtual

Set camera exposure mode and parameter.

Parameters
exposure_on: If true turn exposure on, otherwise turn off.
exposure_auto: If true set auto exposure, if false set manual exposure applying exposure_value parameter.
exposure_value: This is the exposure value in ms.
Returns
The measured exposure time in ms after applying the new setting.

According to SFNC (standard feature naming convention) of GenICam standard, Exposure is used and deprecates shutter.

See "Terminology Changes" section of the page: https://www.ptgrey.com/kb/11020?countryid=237

See also
getExposure()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ setFrameRate()

virtual float vpPylonGrabber::setFrameRate ( float  frame_rate)
pure virtual

Set camera frame rate.

Parameters
frame_rate: Camera frame rate (fps) to set.
Returns
The camera current framerate.
See also
getFramerate()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ setGain()

virtual float vpPylonGrabber::setGain ( bool  gain_auto,
float  gain_value 
)
pure virtual

Set camera gain mode and value.

Parameters
gain_auto: If true set auto gain, if false set manual gain applying gain_value parameter.
gain_value: The amount of amplification that is applied to a pixel in manual mode. An increase in gain can result in an increase in noise.
Returns
The measured gain after applying the new setting.
See also
getGain()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ setGamma()

virtual float vpPylonGrabber::setGamma ( bool  gamma_on,
float  gamma_value = 1 
)
pure virtual

Set camera gamma correction mode and parameter.

Parameters
gamma_on: If true turn gamma correction on, otherwise turn off.
gamma_value: Parameter used to perform gamma correction of pixel intensity.
Returns
The measured gamma correction value after applying the new setting.
See also
getGamma()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ setUserSetDefault()

virtual bool vpPylonGrabber::setUserSetDefault ( UserSetName  user_set)
pure virtual

Sets the configuration set to be used as the default startup set.

Parameters
user_setSee vpPylonGrabber::UserSetName for valid values.
Returns
true for finished, false otherwise.
See also
getUserSetDefault()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ startCapture()

virtual void vpPylonGrabber::startCapture ( )
pure virtual

Start active camera capturing images.

See also
stopCapture()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

◆ stopCapture()

virtual void vpPylonGrabber::stopCapture ( )
pure virtual

Stop active camera capturing images.

See also
startCapture()

Implemented in vpPylonGrabberUsb, and vpPylonGrabberGigE.

Member Data Documentation

◆ height

◆ init

◆ width