Image Component Library (ICL)
Public Member Functions | Private Attributes | List of all members
icl::markers::FiducialDetector Class Reference

Main Fiducial Detector class. More...

#include <FiducialDetector.h>

Inheritance diagram for icl::markers::FiducialDetector:
icl::utils::Uncopyable icl::utils::Configurable

Public Member Functions

 FiducialDetector (const std::string &plugin="bch", const utils::Any &markersToLoad=utils::Any(), const utils::ParamList &params=utils::ParamList(), const geom::Camera *camera=0) throw (utils::ICLException)
 create a FiducialDetector instance with speical plugin type More...
 
virtual ~FiducialDetector ()
 Destructor. More...
 
const std::string & getPluginType () const
 returns the current plugin type More...
 
void setCamera (const geom::Camera &camera)
 sets the current camera More...
 
const geom::CameragetCamera () const throw (utils::ICLException)
 returns the current camera (or throws an exception if no camera is available) More...
 
void loadMarkers (const utils::Any &which, const utils::ParamList &params=utils::ParamList()) throw (utils::ICLException)
 loads markers according to the current plugin type More...
 
void unloadMarkers (const utils::Any &which)
 unloads all already defined markers More...
 
const std::vector< Fiducial > & detect (const core::ImgBase *image) throw (utils::ICLException)
 detects markers in the given and returns all found markers More...
 
Fiducial::FeatureSet getFeatures () const
 returns the list of supported features More...
 
std::string getIntermediateImageNames () const
 returns a list (comma separated) of all available intermediate image results More...
 
const core::ImgBasegetIntermediateImage (const std::string &name) const throw (utils::ICLException)
 returns the intermediate result image associated with given name More...
 
core::Img8u createMarker (const utils::Any &whichOne, const utils::Size &size, const utils::ParamList &params)
 creates an image of a given markers More...
 
FiducialDetectorPlugingetPlugin ()
 returns the internal plugin More...
 
- Public Member Functions inherited from icl::utils::Configurable
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...
 

Private Attributes

Data * data
 hidden data pointer More...
 

Additional Inherited Members

- Public Types inherited from icl::utils::Configurable
typedef Function< void, const Property & > Callback
 Function type for changed properties. More...
 
- 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 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 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 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()) 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 inherited from icl::utils::Configurable
std::vector< Callbackcallbacks
 internally managed list of callbacks More...
 

Detailed Description

Main Fiducial Detector class.

Constructor & Destructor Documentation

icl::markers::FiducialDetector::FiducialDetector ( const std::string &  plugin = "bch",
const utils::Any markersToLoad = utils::Any(),
const utils::ParamList params = utils::ParamList(),
const geom::Camera camera = 0 
)
throw (utils::ICLException
)

create a FiducialDetector instance with speical plugin type

The given plugin type can be:

  • "art" for ARToolkit markers (visit the ARToolkit Webpage for more details) ART Fiducials can provide the full set of information including the 3D pose from a single marker
  • "bch" for ARToolkit+/Studierstube-Tracker like bch-code based binary markers (visit the Studierstube Tracker Homepage for more details) BCH Fiducials can provide the full set of information including the 3D pose from a single marker. Usually, the detection rate is faster and more accurate in comparison to artoolkit markers.
  • "amoeba" for The amoeba style hierarchical markers provided by the reactivision software Amoeba fiducials cannot be detected in 3D. They do only provide 2D center and rotation and the 2D boundary.
  • "icl1" for ICL's own markers, that were also used for the former version of deformable paper tracking. Here, 32 hierarchical markers are provided. These markers do also provide key-point association and 3D pose estimation. all allowed marker IDs can be used twice: positive IDs indicate 'normal' markers (with a black root region) while negative marker IDs indicate 'inverted' markers (with white root regions)

other parameters
For extraction of 3D marker information, usually a camera is needed. The camera can also set later using setCamera Even though the camera is passed per pointer, it is compied deeply into the FiducialDetector instance. The camera can be updated using setCamera() lateron
The also optionally given markersToLoad and params are directly passed to the loadMarkers method

benchmarks TODO

virtual icl::markers::FiducialDetector::~FiducialDetector ( )
virtual

Destructor.

Member Function Documentation

core::Img8u icl::markers::FiducialDetector::createMarker ( const utils::Any whichOne,
const utils::Size size,
const utils::ParamList params 
)

creates an image of a given markers

sice this function call is directly passed to the underlying FiducialDetectorPlugin instance, its implemention depends on this implementation.

Parameters
whichOnespecifies the marker to create in case of plugin type 'icl1' or 'bch', this is simply the marker ID. If the plugin type is art, whichOne needs to be an image filename. Amoeba markers cannot be created automatically because the marker layout is not free.
sizeresulting image size (please note, that the recommended image size aspect ratio for icl1-typed markers is 13:17 (e.g. 230:300)
paramsthis list contains additional parameters that are neccessary for marker creation.

The function parameters

bch needs an integer valued "border-width" parameter, which is used as border width. Please note that the bch-code center always consists of 6x6 pixels. The resulting image of size 2*border-width + 6 is finally scaled up to 'size' before it is returned. art needs a float valued 'border ratio' parameter. This is used to compute the border size for a given marker image. If the marker image (without border) has size A^2, then whole marker image (whith borders) has size (1+'border ratio')*A. Only finally, the image is scaled to it's destination size. icl1 does not need extra parameters amoeba is not supported

const std::vector<Fiducial>& icl::markers::FiducialDetector::detect ( const core::ImgBase image)
throw (utils::ICLException
)

detects markers in the given and returns all found markers

Please note, the preferred input core::format is core::Img8u. Other formats are converted to depth8u internally. Usually, your plugin will use gray images as input. You can query this information by calling getPropertyValue("preferred image type")

const geom::Camera& icl::markers::FiducialDetector::getCamera ( ) const
throw (utils::ICLException
)

returns the current camera (or throws an exception if no camera is available)

Fiducial::FeatureSet icl::markers::FiducialDetector::getFeatures ( ) const

returns the list of supported features

const core::ImgBase* icl::markers::FiducialDetector::getIntermediateImage ( const std::string &  name) const
throw (utils::ICLException
)

returns the intermediate result image associated with given name

If no image is associated with this name, an exception is thrown. Note, the image might be associated, but still be null, in particular if detect was not called one before

std::string icl::markers::FiducialDetector::getIntermediateImageNames ( ) const

returns a list (comma separated) of all available intermediate image results

The returned images can be used for debugging or for further processing. the Fiducial Detector does always add the two tokes "input" and "pp", which refers to the last input image and the last preprocessing result image

FiducialDetectorPlugin* icl::markers::FiducialDetector::getPlugin ( )

returns the internal plugin

const std::string& icl::markers::FiducialDetector::getPluginType ( ) const

returns the current plugin type

void icl::markers::FiducialDetector::loadMarkers ( const utils::Any which,
const utils::ParamList params = utils::ParamList() 
)
throw (utils::ICLException
)

loads markers according to the current plugin type

  • "bch":
    params is a string that is either a range "[a,b]" of markers that are used or a list "{a,b,c,...}" of allowed marker IDs or a single marker ID. The used bch codes are able to encode marker IDs in range [0,4095]. Please note that angular braces define a range, while curly braces define a list here.
    Artoolkit markers need extra param in the param list which is the real marker size (in mm) An example param list is ParamList("size",utils::Size(50,50));
  • "art":
    here, an image file-name or file-pattern is required. This image is automatically converted into an appropriate matching representation
  • "amoeba"
    Each amoeba marker is represented by a special two-level hierarchical code representation that is wrapped by the TwoLevelRegionStructure class. You can pass either a file, that contains a list of these codes (one code per line) or a single code or a comma- or space separated list of codes. Please note that the "amoeba" markers are only free to use in combination with the reacTIVision software.
  • "icl1"
    These are the 32 allowed icl1 marker IDs: 1294 1252 1287 1035 1245 993 1292 1250 1280 1028 1208 776 1238 986 1166 734 1285 1033 1243 991 1273 1021 1201 769 949 517 1231 979 1159 727 907 475. Other ID's will not be detected, but can be added in a more genereal list. E.g. by adding which ="[450-1300]", you can add all markers. Actually if you load a marker ID x, also the inverted marker (that has a white root-region) with ID -x is added.
void icl::markers::FiducialDetector::setCamera ( const geom::Camera camera)

sets the current camera

The camera is usually needed for extraction of 3D marker information. After setting a camera, some already existent Fiducials might become out of date. Therefore, detect must be called again when the camera was changed.

void icl::markers::FiducialDetector::unloadMarkers ( const utils::Any which)

unloads all already defined markers

usually, markers are unloaded with the same pattern that was also used for loading the markers before

Member Data Documentation

Data* icl::markers::FiducialDetector::data
private

hidden data pointer


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