icl::io::Grabber Class Reference

Common interface class for all grabbers. More...

#include <Grabber.h>

Inheritance diagram for icl::io::Grabber:

Public Types
typedef utils::Function< void, const core::ImgBase * >	callback
	new image callback type More...
Public Types inherited from icl::utils::Configurable
typedef Function< void, const Property & >	Callback
	Function type for changed properties. More...

Public Member Functions
	Grabber ()
virtual	~Grabber ()
	Destructor. More...
const core::ImgBase *	grab (core::ImgBase **dst=0)
	grab function calls the Grabber-specific acquireImage-method and applies distortion if necessary More...
template<class T >
bool	desiredUsed () const
	returns whether the desired parameter for the given type is used More...
template<class T >
void	useDesired (const T &t)
	sets desired parameters (only available for core::depth,utils::Size and core::format) More...
void	useDesired (core::depth d, const utils::Size &size, core::format fmt)
	sets up the grabber to use all given desired parameters More...
template<class T >
void	ignoreDesired ()
	set the grabber to ignore the desired param of type T More...
void	ignoreDesired ()
	sets up the grabber to ignore all desired parameters More...
template<class T >
T	getDesired () const
	returns the desired value for the given type T More...
virtual void	registerCallback (callback cb)
	registers a callback that is called each time, a new image is available More...
virtual void	removeAllCallbacks ()
	removes all registered image callbacks More...
virtual void	notifyNewImageAvailable (const core::ImgBase *image)
	this function can be implemented by subclasses in order to notify, that a new image is available More...
Public Member Functions inherited from icl::utils::Configurable
virtual	~Configurable ()
	virtual destructor More...
	Configurable (const Configurable &other)
	Copy constructor. More...
Configurable &	operator= (const Configurable &other)
	Assignment operator. More...
void	setConfigurableID (const std::string &ID)
	sets the ID of this configurable More...
const std::string &	getConfigurableID () const
	returns the configurables static ID More...
bool	isOrderedFlagSet () const
	returns whether the ordered flag is set More...
void	deactivateProperty (const std::string &pattern)
	adds an additional deativation pattern More...
void	deleteDeactivationPattern (const std::string &pattern)
	removed a formerly added deactivation pattern More...
std::vector< std::string >	getPropertyListWithoutDeactivated () const
	this returns a filtered list of properties (using all filters added by deactivateProperty) More...
virtual void	adaptProperty (const std::string &name, const std::string &newType, const std::string &newInfo, const std::string &newToolTip)
	this function can be used to adapt a specific property afterwards More...
void	registerCallback (const Callback &cb)
	add a callback for changed properties More...
void	removedCallback (const Callback &cb)
	removes a callback that was registered before More...
void	syncChangesTo (Configurable *others, int num=1)
	this can be used to let this instance also apply property changes to others More...
virtual void	setPropertyValue (const std::string &propertyName, const Any &value)
	sets a property value More...
virtual std::vector< std::string >	getPropertyList () const
	returns a list of All properties, that can be set using setProperty More...
virtual bool	supportsProperty (const std::string &propertyName) const
	base implementation for property check (seaches in the property list) More...
virtual void	saveProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC) const
	writes all available properties into a file More...
virtual void	loadProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC)
	reads a camera config file from disc More...
virtual std::string	getPropertyType (const std::string &propertyName) const
	get type of property More...
virtual std::string	getPropertyInfo (const std::string &propertyName) const
	get information of a properties valid values More...
virtual Any	getPropertyValue (const std::string &propertyName) const
	returns the current value of a property or a parameter More...
virtual std::string	getPropertyToolTip (const std::string &propertyName) const
	returns the tooltip description for a given property More...
virtual int	getPropertyVolatileness (const std::string &propertyName) const
	Returns whether this property may be changed internally. More...

Protected Member Functions
virtual void	setDesiredFormatInternal (core::format fmt)
	internally set a desired format More...
virtual void	setDesiredSizeInternal (const utils::Size &size)
	internally set a desired format More...
virtual void	setDesiredDepthInternal (core::depth d)
	internally set a desired format More...
virtual core::format	getDesiredFormatInternal () const
	returns the desired format More...
virtual core::depth	getDesiredDepthInternal () const
	returns the desired format More...
virtual utils::Size	getDesiredSizeInternal () const
	returns the desired format More...
virtual const core::ImgBase *	acquireImage ()
	main interface method, that is implemented by the actual grabber instances More...
const core::ImgBase *	adaptGrabResult (const core::ImgBase *src, core::ImgBase **dst)
	Utility function that allows for much easier implementation of grabUD. More...
Protected Member Functions inherited from icl::utils::Uncopyable
	Uncopyable ()
	Empty base constructor. More...
Protected Member Functions inherited from icl::utils::Configurable
void	addProperty (const std::string &name, const std::string &type, const std::string &info, const Any &value=Any(), const int volatileness=0, const std::string &tooltip=std::string())
	This can be used by derived classes to store supported properties in the internal list. More...
void	addChildConfigurable (Configurable *configurable, const std::string &childPrefix="")
	This adds another configurable as child. More...
void	removeChildConfigurable (Configurable *configurable)
	removes the given child configurable More...
Property &	prop (const std::string &propertyName)
	this CAN be used e.g. to store a property value in internal property-list More...
const Property &	prop (const std::string &propertyName) const
	this CAN be used e.g. to store a property value in internal property-list More...
	Configurable (const std::string &ID="", bool ordered=true)
	create this configurable with given ID More...
void	call_callbacks (const std::string &propertyName, const Configurable *caller) const
	calls all registered callbacks More...

Private Member Functions
void	processPropertyChange (const utils::Configurable::Property &prop)
	callback for changed configurable properties More...

Private Attributes
Data *	data
	hidden data More...

Friends
template<class X >
class	GrabberHandle
	grant private method access to the grabber handle template More...
class	GenericGrabber
	grant private method access to the GenericGrabber class More...

static string conversion functions
static std::string	translateSteppingRange (const utils::SteppingRange< double > &range)
	translates a SteppingRange into a string representation More...
static utils::SteppingRange< double >	translateSteppingRange (const std::string &rangeStr)
	creates a SteppingRange out of a string representation More...
static std::string	translateDoubleVec (const std::vector< double > &doubleVec)
	translates a vector of doubles into a string representation More...
static std::vector< double >	translateDoubleVec (const std::string &doubleVecStr)
	creates a vector of doubles out of a string representation More...
static std::string	translateStringVec (const std::vector< std::string > &stringVec)
	translates a vector of strings into a single string representation More...
static std::vector< std::string >	translateStringVec (const std::string &stringVecStr)
	creates a vector of strins out of a single string representation More...

distortion functions
void	enableUndistortion (const std::string &filename)
	enables the undistorion More...
void	enableUndistortion (const ImageUndistortion &udist)
	enables the undistortion plugin for the grabber using radial and tangential distortion parameters More...
void	enableUndistortion (const utils::ProgArg &pa)
	enables undistortion from given programm argument. More...
void	enableUndistortion (const core::Img32f &warpMap)
	enables undistortion for given warp map More...
void	setUndistortionInterpolationMode (core::scalemode mode)
	sets how undistortion is interpolated (supported modes are interpolateNN and interpolateLIN) More...
void	disableUndistortion ()
	disables distortion More...
bool	isUndistortionEnabled () const
	returns whether distortion is currently enabled More...
const core::Img32f *	getUndistortionWarpMap () const
	returns the internal warp map or NULL if undistortion is not enabled More...

Additional Inherited Members
Static Public Member Functions inherited from icl::utils::Configurable
static std::string	create_default_ID (const std::string &prefix)
	this function can be used in subclasses to create a default ID More...
static Configurable *	get (const std::string &id)
	returns configurable by given ID More...
static void	register_configurable_type (const std::string &classname, Function< Configurable * > creator)
	registers a configurable type More...
static std::vector< std::string >	get_registered_configurables ()
	returns a list of all registered configurable classnames More...
static Configurable *	create_configurable (const std::string &classname)
	creates a configurable by given name More...
Static Public Attributes inherited from icl::utils::Configurable
static const std::vector< std::string >	EMPTY_VEC
	used as shortcut – just an empty vector of std::strings More...
Protected Attributes inherited from icl::utils::Configurable
std::vector< Callback >	callbacks
	internally managed list of callbacks More...

Detailed Description

Common interface class for all grabbers.

The Grabber is ICL's common interface for image acquisition tools. A large set of Grabbers is available and wrapped by the GenericGrabber class. We strongly recommend to use the GenericGrabber class for image acquisition within applications.

The Grabber itself has a very short interface for the user: usually, a grabber is instantiated and its grab() method is called to aquire the next available image.

Desired parameters

In addition, the Grabber supports a set of so called 'desired-parameters'. These can be set to overwrite the image parameters that are used by the underlying implementation. A FileGrabber e.g. will by default return images that have the same parameter that the grabbed image file provides. However, in some situations, the user might want to adapt these parameters E.g. if the image parameters that are provided by the grabber are not suitable for an algorithm. If this is the case, the Grabber's desired parameters can be set using the Grabber::setDesired-template.
Currently, the image parameters 'core::depth', 'size' and 'core::format' can be adapted seperately by setting desired parameters. Once desired parameters are set, the can be reset to the grabber's default by calling grabber::ignoreDesired<T> where one of the types core::depth, core::format or icl::utils::Size is used as type T.

Image Undistortion

The Grabber does also provide an interface to set up image undistortion parameters. The can be estimated with ICL's distortion calibration tool. The undistortion operation is accelerated using an internal warp-table. By these means, image undistion is directly applied on the grabbed images, which lets the user then work with undistored images.

Implementing Grabbers

In order to implement a new Grabber class, some steps are necessary. First, the new Grabber needs to be implemented. This must implement the Grabber::acquireImage method, that uses an underlying image source to acquire a single new image. This can have any parameters and core::depth (usually, the image parameters are somehow related to the output of the underlying image source). If the grabber is available, one should think about adapting the grabber to inherit the icl::GrabberHandle class that adds the ability of instantiating one Grabber several times without having to handle double device accesses explicitly.

Properties

The Grabber implements the Configurable interface that is used to implement dynamically settable properties. Each Grabber must have at least the two properties 'core::format' and 'size'. These are handled in a special way by the automatically created Grabber- property-GUIs available in the ICLQt package.

Callbacks

As a very new experimental features, ICL's Grabber interface provides methods to register callback functions to the grabber that are then called automatically whenever a new image is available. This feature needs to be implemented explicitly for each grabber backend and does sometimes not even make sense. Furthermore, it' could lead to some strange behaviour of the whole application, because the internal image akquisition process is suddenly linked to the further image processing steps directly. This feature should not be used for writing applications that are scheduled by the speed of the internal image aquisition loop. Therefore, images should never be processed in the callback functions that are registred.

So far only a few grabbers provide this feature at all. If it is not provided, the registered callbacks will never be called.

Member Typedef Documentation

callback

typedef utils::Function<void,const core::ImgBase*> icl::io::Grabber::callback

new image callback type

Constructor & Destructor Documentation

Grabber()

icl::io::Grabber::Grabber

(

)

~Grabber()

virtual icl::io::Grabber::~Grabber ( )

virtual

Destructor.

Member Function Documentation

acquireImage()

virtual const core::ImgBase* icl::io::Grabber::acquireImage ( )

inlineprotectedvirtual

main interface method, that is implemented by the actual grabber instances

This method is defined in the grabber implementation. It acquires a new image using the grabbers specific image acquisition back-end

Reimplemented in icl::io::DCGrabber, icl::io::pylon::PylonGrabber, icl::io::FileGrabber, icl::io::OpenNIGrabber, icl::io::PixelSenseGrabber, icl::io::VideoGrabber, icl::io::RSBGrabber, icl::io::OptrisGrabber, icl::io::SharedMemoryGrabber, icl::io::XiGrabber, icl::io::KinectGrabber, icl::io::OpenCVCamGrabber, icl::io::SwissRangerGrabber, icl::io::OpenCVVideoGrabber, icl::io::ZmqGrabber, icl::io::Kinect2Grabber, icl::io::V4L2Grabber, icl::qt::QtVideoGrabber, icl::qt::QtCameraGrabber, icl::io::CreateGrabber, and icl::io::DemoGrabber.

adaptGrabResult()

const core::ImgBase* icl::io::Grabber::adaptGrabResult ( const core::ImgBase *  src, core::ImgBase **  dst  )

protected

Utility function that allows for much easier implementation of grabUD.

called by the grabbers grab() method

desiredUsed()

template<class T >

bool icl::io::Grabber::desiredUsed ( ) const

inline

returns whether the desired parameter for the given type is used

This method is only available for the type core::depth,icl::utils::Size and core::format

disableUndistortion()

void icl::io::Grabber::disableUndistortion

(

)

disables distortion

enableUndistortion() [1/4]

void icl::io::Grabber::enableUndistortion

(

const std::string &

filename

)

enables the undistorion

enableUndistortion() [2/4]

void icl::io::Grabber::enableUndistortion

(

const ImageUndistortion &

udist

)

enables the undistortion plugin for the grabber using radial and tangential distortion parameters

enableUndistortion() [3/4]

void icl::io::Grabber::enableUndistortion

(

const utils::ProgArg &

pa

)

enables undistortion from given programm argument.

where first argument is the filename of the xml file and second is the size of picture

enableUndistortion() [4/4]

void icl::io::Grabber::enableUndistortion

(

const core::Img32f &

warpMap

)

enables undistortion for given warp map

getDesired()

template<class T >

T icl::io::Grabber::getDesired ( ) const

inline

returns the desired value for the given type T

This method is only available for core::depth,utils::Size and core::format

getDesiredDepthInternal()

virtual core::depth icl::io::Grabber::getDesiredDepthInternal ( ) const

protectedvirtual

returns the desired format

getDesiredFormatInternal()

virtual core::format icl::io::Grabber::getDesiredFormatInternal ( ) const

protectedvirtual

returns the desired format

getDesiredSizeInternal()

virtual utils::Size icl::io::Grabber::getDesiredSizeInternal ( ) const

protectedvirtual

returns the desired format

getUndistortionWarpMap()

const core::Img32f* icl::io::Grabber::getUndistortionWarpMap

(

)

const

returns the internal warp map or NULL if undistortion is not enabled

grab()

const core::ImgBase* icl::io::Grabber::grab

(

core::ImgBase **

dst = 0

)

grab function calls the Grabber-specific acquireImage-method and applies distortion if necessary

If dst is not NULL, it is exploited and filled with image data

ignoreDesired() [1/2]

template<class T >

void icl::io::Grabber::ignoreDesired ( )

inline

set the grabber to ignore the desired param of type T

This method is only available for core::depth,utils::Size and core::format

ignoreDesired() [2/2]

void icl::io::Grabber::ignoreDesired

(

)

sets up the grabber to ignore all desired parameters

isUndistortionEnabled()

bool icl::io::Grabber::isUndistortionEnabled

(

)

const

returns whether distortion is currently enabled

notifyNewImageAvailable()

virtual void icl::io::Grabber::notifyNewImageAvailable ( const core::ImgBase *  image )

virtual

this function can be implemented by subclasses in order to notify, that a new image is available

When this function is called, it will automatically call all callbacks with the given image.

processPropertyChange()

void icl::io::Grabber::processPropertyChange ( const utils::Configurable::Property &  prop )

private

callback for changed configurable properties

registerCallback()

virtual void icl::io::Grabber::registerCallback ( callback  cb )

virtual

registers a callback that is called each time, a new image is available

This feature must not be implemented by specific grabber implementations. And it is up to the implementation whether the image that is passed to the callback has the "desired parameters" or not. Most likely, an internal image buffer is passed, which does not have the desired paremters. The output image is also usually not undistorted.

removeAllCallbacks()

virtual void icl::io::Grabber::removeAllCallbacks ( )

virtual

removes all registered image callbacks

setDesiredDepthInternal()

virtual void icl::io::Grabber::setDesiredDepthInternal ( core::depth  d )

protectedvirtual

internally set a desired format

setDesiredFormatInternal()

virtual void icl::io::Grabber::setDesiredFormatInternal ( core::format  fmt )

protectedvirtual

internally set a desired format

setDesiredSizeInternal()

virtual void icl::io::Grabber::setDesiredSizeInternal ( const utils::Size &  size )

protectedvirtual

internally set a desired format

setUndistortionInterpolationMode()

void icl::io::Grabber::setUndistortionInterpolationMode

(

core::scalemode

mode

)

sets how undistortion is interpolated (supported modes are interpolateNN and interpolateLIN)

Please note, that this method has no effect if the undistortion was not enabled before using one of the Grabber::enableUndistortion methods. Furthermore, the setting is lost if the undistortion is deactivated using Grabber::disableUndistortion

translateDoubleVec() [1/2]

static std::string icl::io::Grabber::translateDoubleVec ( const std::vector< double > &  doubleVec )

static

translates a vector of doubles into a string representation

translateDoubleVec() [2/2]

static std::vector<double> icl::io::Grabber::translateDoubleVec ( const std::string &  doubleVecStr )

static

creates a vector of doubles out of a string representation

translateSteppingRange() [1/2]

static std::string icl::io::Grabber::translateSteppingRange ( const utils::SteppingRange< double > &  range )

static

translates a SteppingRange into a string representation

translateSteppingRange() [2/2]

static utils::SteppingRange<double> icl::io::Grabber::translateSteppingRange ( const std::string &  rangeStr )

static

creates a SteppingRange out of a string representation

translateStringVec() [1/2]

static std::string icl::io::Grabber::translateStringVec ( const std::vector< std::string > &  stringVec )

static

translates a vector of strings into a single string representation

translateStringVec() [2/2]

static std::vector<std::string> icl::io::Grabber::translateStringVec ( const std::string &  stringVecStr )

static

creates a vector of strins out of a single string representation

useDesired() [1/2]

template<class T >

void icl::io::Grabber::useDesired ( const T &  t )

inline

sets desired parameters (only available for core::depth,utils::Size and core::format)

useDesired() [2/2]

void icl::io::Grabber::useDesired	(	core::depth	d,
		const utils::Size &	size,
		core::format	fmt
	)

sets up the grabber to use all given desired parameters

Friends And Related Function Documentation

GenericGrabber

friend class GenericGrabber

friend

grant private method access to the GenericGrabber class

GrabberHandle

template<class X >

friend class GrabberHandle

friend

grant private method access to the grabber handle template

Member Data Documentation

data

Data* icl::io::Grabber::data

private

hidden data

---

The documentation for this class was generated from the following file:

• /Users/alneuman/vm/icl/ICLIO/src/ICLIO/Grabber.h