Image Component Library (ICL)
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | Private Types | Private Attributes | Static Private Attributes | Friends | List of all members
icl::utils::Configurable Class Reference

Interface for classes that can be configured from configuration-files and GUI-Components. More...

#include <Configurable.h>

Inheritance diagram for icl::utils::Configurable:
icl::cv::CheckerboardDetector icl::cv::CornerDetectorCSS icl::cv::HoughLineDetector icl::cv::ORBFeatureDetector icl::cv::RegionDetector icl::cv::TemplateTracker icl::filter::ProximityOp icl::filter::UnaryOp icl::geom::ConfigurableDepthImageSegmenter icl::geom::CoplanarPointPoseEstimator icl::geom::PointCloudGrabber icl::geom::RansacBasedPoseEstimator icl::io::DCDeviceFeatures icl::io::DCDeviceFeaturesImpl icl::io::Grabber icl::io::icl_openni::MapGeneratorOptions icl::io::pylon::PylonCameraOptions icl::markers::FiducialDetector icl::markers::FiducialDetectorPlugin icl::markers::MarkerGridDetector icl::markers::MarkerGridPoseEstimator icl::markers::MultiCamFiducialDetector icl::markers::QuadDetector icl::math::LLM icl::physics::SoftObject icl::qt::AbstractPlotWidget

Classes

struct  Property
 Represents a single property. More...
 

Public Types

typedef Function< void, const Property & > Callback
 Function type for changed properties. More...
 

Public Member Functions

virtual ~Configurable ()
 virtual destructor More...
 
 Configurable (const Configurable &other)
 Copy constructor. More...
 
Configurableoperator= (const Configurable &other)
 Assignment operator. More...
 
void setConfigurableID (const std::string &ID) throw (ICLException)
 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) throw (ICLException)
 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) throw (ICLException)
 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...
 

Static Public Member Functions

static std::string create_default_ID (const std::string &prefix)
 this function can be used in subclasses to create a default ID More...
 
static Configurableget (const std::string &id)
 returns configurable by given ID More...
 
static void register_configurable_type (const std::string &classname, Function< Configurable * > creator) throw (ICLException)
 registers a configurable type More...
 
static std::vector< std::string > get_registered_configurables ()
 returns a list of all registered configurable classnames More...
 
static Configurablecreate_configurable (const std::string &classname) throw (ICLException)
 creates a configurable by given name More...
 

Static Public Attributes

static const std::vector< std::string > EMPTY_VEC
 used as shortcut – just an empty vector of std::strings More...
 

Protected Member Functions

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()) throw (ICLException)
 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...
 
Propertyprop (const std::string &propertyName) throw (ICLException)
 this CAN be used e.g. to store a property value in internal property-list More...
 
const Propertyprop (const std::string &propertyName) const throw (ICLException)
 this CAN be used e.g. to store a property value in internal property-list More...
 
 Configurable (const std::string &ID="", bool ordered=true) throw (ICLException)
 create this configurable with given ID More...
 
void call_callbacks (const std::string &propertyName, const Configurable *caller) const
 calls all registered callbacks More...
 

Protected Attributes

std::vector< Callbackcallbacks
 internally managed list of callbacks More...
 

Private Types

typedef std::map< std::string, PropertyPropertyMap
 by default internally use property list More...
 

Private Attributes

PropertyMap m_properties
 list of all properties More...
 
bool m_isOrdered
 whether to use property ordering More...
 
std::map< int, std::string > m_ordering
 ordering of the properties More...
 
std::map< const Configurable *, std::string > m_childConfigurables
 internal list of child configurables More...
 
Configurablem_elderConfigurable
 internal pointer to elder configurable More...
 
std::string m_ID
 internal ID, that is used to provide global access to all instantiated configurables at runtime by given ID; More...
 
std::vector< std::string > m_deactivated
 list of patterns for deactiavted properties More...
 
UncopiedInstance< Mutexm_mutex
 locks all accesses to property values More...
 

Static Private Attributes

static std::map< std::string, Configurable * > m_instances
 static list of all instantiated Configurables More...
 

Friends

class ConfigurableProxy
 

Detailed Description

Interface for classes that can be configured from configuration-files and GUI-Components.

The Configurable-interface can be used to define a classes parameters/properties that shall be changed at runtime. The Configurable-subclasses can define properties that can be accessed by string identifiers. Each property has a type, a type-dependend description of possible values, a current value and a so called volatileness. Please see class interface and it's function descriptions for more details. A list of supported property types is provided in the documentation of the method icl::Configurable::getPropertyType

Implementing the Configurable Interface

It is strongly recommended to use the Configurable's property storage mechanism to manage a classes properties. Special behaviour to the adaption of certain properties can easily be added by registering a callback to an own member function. Alternatively, all Configurable's virtual methods can be reimplemented to obtain special behaviour. In this case the programmer himself can provide storage for the classes properties, but this is – as said above – not recommended due to the complex interface.

Child Configurables

Configurables can not only have a list of properties that can be got and set, but also a list of chlidren. All child-properties will also become properties of it's parent. However, the first section prefix (which is used for the property-tab's label) can be adapted. Note that this behaviour must be preserved if the virtual functions setPropertyValue and getPropertyValue are reimplemented. Usually, you can simply call Configurable::[set/get]PropertyValue(...) at the end of you versions of these methods.

Configurable Registration

Configurable class should be registered statically using one of the two registration macros REGISTER_CONFIGURABLE or REGISTER_CONFIGURABLE_DEFAULT. This is strongly recommended since the class interface of a configurable class does not give information about the properties that are provided by a specific Configurable class. Instead, all classes, that implement the Configurable interface, can be registered statically, which allows for runtime exploration of possible Configurable classes and their supported properties.

The example application icl-configurable-info can be used to explore allowed properties.

In order to make the static registration process as easy as possible, special macros are provided. Example:

namespace icl{
// MyConfigurable.h
struct MyConfigurable{
MyConfigurable();
void foo(){}
...
};
}
// MyConfigurable.cpp
namespace icl{
MyConfigurable::MyConfigurable(){
addProperty(....);
}
void MyConfigurable::foo() {...}
// registration at the end of the .cpp file
// within the icl-namespace
}

If no default constructor is available, the macro REGISTER_CONFIGURABLE can be used. Here, you can also specify how an instance of that class is created. Example:

namespace icl{
// MyComplexConfigurable.h
struct MyComplexConfigurable{
// no default constructor
MyComplexConfigurable(int i, float j);
void foo(){}
...
};
}
// MyComplexConfigurable.cpp
namespace icl{
MyComplexConfigurable::MyComplexConfigurable(int i, float j){
addProperty(....);
}
void MyComplexConfigurable::foo() {...}
// provide default arguments here
REGISTER_CONFIGURABLE(MyComplexConfigurable, return new MyComplexConfigurable(1,4.5));
}

For classes with pure-virtual methods, it is recommended to provide a dummy non-virtual extension of that class whose name is extended by a _VIRTUAL postfix. In this case, listing the Configurable classnames shows explicitly, that a class is a virtual interface. Example:

namespace icl{
// MyVirtualConfigurable.h
struct MyVirtualConfigurable{
MyVirtualConfigurable();
// pure virtual method
virtual void foo(int bar) = 0;
...
};
}
// MyVirtualConfigurable.cpp
namespace icl{
MyVirtualConfigurable::MyVirtualConfigurable(){
addProperty(....);
}
struct MyVirtualConfigurable_VIRTUAL : public MyVirtualConfigurable{
virtual void foo(int){}
};
// register the dummy implementation
REGISTER_CONFIGURABLE_DEFAULT(MyVirtualConfigurable_VIRTUAL);
}

Example (Image Convolution)

There are several examples available in the ICL-source try. Use the ICL-tool icl-configurable-info -list to obtain a list of all Configurable implementations and their supported properties.

Member Typedef Documentation

Function type for changed properties.

typedef std::map<std::string,Property> icl::utils::Configurable::PropertyMap
private

by default internally use property list

Constructor & Destructor Documentation

icl::utils::Configurable::Configurable ( const std::string &  ID = "",
bool  ordered = true 
)
throw (ICLException
)
protected

create this configurable with given ID

all instantiated configurables are globally accessible by static getter functions If given ID is "", then this configurable is not added to the static list. Configurables can later be put into the static list by using setConfigurableID

virtual icl::utils::Configurable::~Configurable ( )
inlinevirtual

virtual destructor

icl::utils::Configurable::Configurable ( const Configurable other)

Copy constructor.

the configurable ID is not copied. Use setConfigurableID afterwards

Member Function Documentation

virtual void icl::utils::Configurable::adaptProperty ( const std::string &  name,
const std::string &  newType,
const std::string &  newInfo,
const std::string &  newToolTip 
)
throw (ICLException
)
virtual

this function can be used to adapt a specific property afterwards

Please note: The newly given type and info value must of cause be compatible with the current property type. The type of a property cannot be changed. Please note also, that this Function also needs to be reimplemented if getPropertyInfo or getPropertyType was reimplemented. A range property can e.g. be adapted to a menu property, which then again restricts possible values. You can also set a properties type from range:spinbox to range:slider

void icl::utils::Configurable::addChildConfigurable ( Configurable configurable,
const std::string &  childPrefix = "" 
)
protected

This adds another configurable as child.

Child configurables can be added with a given prefix. If this prefix is not "", the childs properties will get an own tab in the configurables GUI. Note: if the prefix is not "", it should end with a '.' character. If not, an additional '.' is added automatically in order to move all properties into a dedicated tab

void icl::utils::Configurable::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() 
)
throw (ICLException
)
protected

This can be used by derived classes to store supported properties in the internal list.

Throws an exception if the property name is already defined. Note: properties names can structured using '.'-delimiters. e.g. properties like general.threshold,general.mean,filer.mask-size. This is then later translated into a structured configuratable GUI.

void icl::utils::Configurable::call_callbacks ( const std::string &  propertyName,
const Configurable caller 
) const
protected

calls all registered callbacks

Parameters
propertyNamethe name of the property to check
callerthe instance calling the function
static Configurable* icl::utils::Configurable::create_configurable ( const std::string &  classname)
throw (ICLException
)
static

creates a configurable by given name

See also
Configurable Registration
static std::string icl::utils::Configurable::create_default_ID ( const std::string &  prefix)
static

this function can be used in subclasses to create a default ID

The ID will be the first not used prefixNUMBER where number is an integer value 0,1,...

void icl::utils::Configurable::deactivateProperty ( const std::string &  pattern)

adds an additional deativation pattern

By this means, extended or also accumulating Configurable-instances can hide some of their inherited/accumulated properties. E.g. special ICLFilter::UnaryOp instances can hide the UnaryOp-properties 'Clip To ROI' and 'Check Only' if it is not appropriate to adapt these. The given pattern can be an abitrary regular expression which compared icl::match(const std::string&, const std::string&,int); E.g. to deactivate all UnaryOp-properties, you can add the filter reg-ex '^UnaryOp' more precisesly, you could also add the filter-reg-ex '^UnaryOp..*' which ensures that a '.' and some other characters follow the 'UnaryOp' string. Commonly the '^Foo' can be used to remove all properties with given prefix 'Foo'.

void icl::utils::Configurable::deleteDeactivationPattern ( const std::string &  pattern)

removed a formerly added deactivation pattern

Please note, that usually this should not be used because there is most probably a reason why a property was deactivated before.

static Configurable* icl::utils::Configurable::get ( const std::string &  id)
static

returns configurable by given ID

returns instantiated Configurable by given ID or NULL, if the ID was not found

static std::vector<std::string> icl::utils::Configurable::get_registered_configurables ( )
static

returns a list of all registered configurable classnames

See also
Configurable Registration
const std::string& icl::utils::Configurable::getConfigurableID ( ) const
inline

returns the configurables static ID

virtual std::string icl::utils::Configurable::getPropertyInfo ( const std::string &  propertyName) const
inlinevirtual

get information of a properties valid values

This is the second function of the minimal configuration interface: If received a specific property type with getType(), it's possible to get the corresponding range, value-list or menu with this funcitons. The Syntax of the returned strings are:

  • "[A,B]:C" for a range with min=A, max=B and stepping = C or [A,B] with no stepping
  • "[A,B]" for float- and int-properties with min=A and max=B
  • ",A,B,C,..." for a value-list and A,B,C are ascii doubles (real commas can be escaped using )
  • ",A,B,C,..." for a menu and A,B,C are strings (real commas can be escaped using )
  • nothing for "info"- and "color"-typed properties
  • MAX_LENGTH for string typed properties
  • flag-properties always have the possible values "on|1|true" or "off|0|false" Note: The received string can be translated into C++ data with some static utility function in this Grabber class.

Reimplemented in icl::cv::CornerDetectorCSS.

virtual std::vector<std::string> icl::utils::Configurable::getPropertyList ( ) const
virtual

returns a list of All properties, that can be set using setProperty

This function should usually not be used. Instead, you should call getPropertyListWithoutDeactivated

Returns
list of supported property names

Reimplemented in icl::cv::CornerDetectorCSS.

std::vector<std::string> icl::utils::Configurable::getPropertyListWithoutDeactivated ( ) const

this returns a filtered list of properties (using all filters added by deactivateProperty)

virtual std::string icl::utils::Configurable::getPropertyToolTip ( const std::string &  propertyName) const
inlinevirtual

returns the tooltip description for a given property

Reimplemented in icl::cv::CornerDetectorCSS.

virtual std::string icl::utils::Configurable::getPropertyType ( const std::string &  propertyName) const
inlinevirtual

get type of property

This is a new minimal configuration interface: When implementing generic video device configuration utilities, the programmer needs information about the properties received by getPropertyList(). With the getType(const string&) function, you can explore all possible params and properties, and receive a type string which defines of which type the given property was:
(for detailed description of the types, see also the get Info function) Types are:

  • "range" this is the same as "range:slider" (see below)
  • "range:slider" the property is a double value in a given range
  • "range:spinbox" the property is an int-value in given range with stepping 1
  • "value-list" the property is a double value in a list of possible values
  • "menu" the property is a string value in a list of possible values
  • "flag" the property is a boolean flag that can be set to "on" and "off"
  • "command" property param has no additional parameters (this feature is
  • "float" the property value can be any valid float value within a given range
  • "int" the property value can be any valid int value within a given range
  • "string" the property is a string value with a given maximum length
  • "color" the property has RGBA values in range 0-255 used e.g. for triggered abilities of grabbing devices, like "save user settings" for the PWCGrabber
  • "info" the property is an unchangable internal value (it cannot be set actively)
  • ... (propably some other types are defined later on)

Reimplemented in icl::cv::CornerDetectorCSS.

virtual Any icl::utils::Configurable::getPropertyValue ( const std::string &  propertyName) const
virtual

returns the current value of a property or a parameter

If the property is actually owned by a child-configurable, the function forwards to that configurable

Reimplemented in icl::cv::CornerDetectorCSS.

virtual int icl::utils::Configurable::getPropertyVolatileness ( const std::string &  propertyName) const
inlinevirtual

Returns whether this property may be changed internally.

For example a video grabber's current stream position. This can be changed from outside, but it is changed when the stream is played. The isVolatile function should return a msec-value that describes how often the corresponding feature might be updated internally or just 0, if the corresponding feature is not volatile at all. The default implementation of isVolatile returns 0 for all features. So if there is no such feature in your grabber, this function must not be adapted at all. "info"-typed Properties might be volatile as well

Reimplemented in icl::cv::CornerDetectorCSS.

bool icl::utils::Configurable::isOrderedFlagSet ( ) const
inline

returns whether the ordered flag is set

virtual void icl::utils::Configurable::loadProperties ( const std::string &  filename,
const std::vector< std::string > &  propertiesToSkip = EMPTY_VEC 
)
virtual

reads a camera config file from disc

@ see saveProperties

Configurable& icl::utils::Configurable::operator= ( const Configurable other)

Assignment operator.

the configurable ID is not copied. Use setConfigurableID afterwards

Property& icl::utils::Configurable::prop ( const std::string &  propertyName)
throw (ICLException
)
protected

this CAN be used e.g. to store a property value in internal property-list

Throws an exception if the given propertyName is not supported

const Property& icl::utils::Configurable::prop ( const std::string &  propertyName) const
throw (ICLException
)
protected

this CAN be used e.g. to store a property value in internal property-list

Throws an exception if the given propertyName is not supported

static void icl::utils::Configurable::register_configurable_type ( const std::string &  classname,
Function< Configurable * >  creator 
)
throw (ICLException
)
static

registers a configurable type

See also
Configurable Registration
void icl::utils::Configurable::registerCallback ( const Callback cb)
inline

add a callback for changed properties

void icl::utils::Configurable::removeChildConfigurable ( Configurable configurable)
protected

removes the given child configurable

void icl::utils::Configurable::removedCallback ( const Callback cb)

removes a callback that was registered before

virtual void icl::utils::Configurable::saveProperties ( const std::string &  filename,
const std::vector< std::string > &  propertiesToSkip = EMPTY_VEC 
) const
virtual

writes all available properties into a file

Parameters
filenamedestination xml-filename
propertiesToSkipsome common grabber parameters e.g. trigger-settings cause problems when they are read from configuration files, hence these parameters are skipped at default
void icl::utils::Configurable::setConfigurableID ( const std::string &  ID)
throw (ICLException
)

sets the ID of this configurable

The ID is used for accessing the configurable globally

virtual void icl::utils::Configurable::setPropertyValue ( const std::string &  propertyName,
const Any value 
)
throw (ICLException
)
virtual

sets a property value

If this method is specialized in subclasses, the parent method shold be called at the end in order to call all registered callbacks. If the property is actually owned by a child-configurable, the function forwards to that configurable

Reimplemented in icl::filter::UnaryOp, and icl::cv::CornerDetectorCSS.

virtual bool icl::utils::Configurable::supportsProperty ( const std::string &  propertyName) const
virtual

base implementation for property check (seaches in the property list)

This function may be reimplemented in an optimized way in particular subclasses.

void icl::utils::Configurable::syncChangesTo ( Configurable others,
int  num = 1 
)

this can be used to let this instance also apply property changes to others

Please take care to not create cyclic dependency graphs

Friends And Related Function Documentation

friend class ConfigurableProxy
friend

Member Data Documentation

std::vector<Callback> icl::utils::Configurable::callbacks
protected

internally managed list of callbacks

const std::vector<std::string> icl::utils::Configurable::EMPTY_VEC
static

used as shortcut – just an empty vector of std::strings

std::map<const Configurable*, std::string> icl::utils::Configurable::m_childConfigurables
private

internal list of child configurables

std::vector<std::string> icl::utils::Configurable::m_deactivated
private

list of patterns for deactiavted properties

Configurable* icl::utils::Configurable::m_elderConfigurable
private

internal pointer to elder configurable

std::string icl::utils::Configurable::m_ID
private

internal ID, that is used to provide global access to all instantiated configurables at runtime by given ID;

std::map<std::string,Configurable*> icl::utils::Configurable::m_instances
staticprivate

static list of all instantiated Configurables

bool icl::utils::Configurable::m_isOrdered
private

whether to use property ordering

UncopiedInstance<Mutex> icl::utils::Configurable::m_mutex
mutableprivate

locks all accesses to property values

adding and adapting properties is not thread safe!

std::map<int,std::string> icl::utils::Configurable::m_ordering
private

ordering of the properties

PropertyMap icl::utils::Configurable::m_properties
private

list of all properties


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