Skip to content
Snippets Groups Projects

Resolve "Factory documentation"

Merged Resolve "Factory documentation"
299-factory-documentation into devel
Merged Joan Solà Ortega requested to merge 299-factory-documentation into devel
Viewing commit c907f392
Prev Next
Show latest version
1 file
+ 42
− 34
Compare changes
  • Side-by-side
  • Inline
include/core/common/factory.h
+ 42
− 34
@@ -50,28 +50,28 @@ namespace wolf
* - Examples of specific factories existing in Wolf are:
* \code
*
* // SensorFactory
* typedef Factory<SensorBase, // Type of objects to be created: SensorBasePtr
* const std::string&, // Name of the sensor
* const Eigen::VectorXd&, // Sensor extrinsics
* const ParamsSensorBasePtr> // Sensor parameters
* SensorFactory;
*
* // ProcessorFactory
* typedef Factory<ProcessorBase, // Type of object created: ProcessorBasePtr
* const std::string&, // Name of the processor
* const ParamsProcessorBasePtr> // Parameters for creating the processor
* ProcessorFactory;
* // FactorySensor
* typedef Factory<SensorBase, // Type of objects to be returned: SensorBasePtr
* const std::string&, // Type of the sensor: name of the derived sensor class
* const Eigen::VectorXd&, // Sensor extrinsics
* const ParamsSensorBasePtr> // Sensor parameters
* FactorySensor;
*
* // FactoryProcessor
* typedef Factory<ProcessorBase, // Type of object returned: ProcessorBasePtr
* const std::string&, // Type of the processor: name of the derived processor class
* const ParamsProcessorBasePtr> // Parameters for creating the processor
* FactoryProcessor;
*
* // AutoConfProcessorFactory
* typedef Factory<ProcessorBase, // Type of object created: ProcessorBasePtr
* const std::string&, // Name of the processor
* const ParamsServer> // Parameters for creating the processor
* AutoConfProcessorFactory;
* typedef Factory<ProcessorBase, // Type of object returned: ProcessorBasePtr
* const std::string&, // Type of the processor: name of the derived processor class
* const ParamsServer> // Parameters for creating the processor
* AutoConfProcessorFactory;
*
* // Landmarks from YAML
* typedef Factory<LandmarkBase, // Type of node created: LandmarkBasePtr
* const YAML::Node&> // YAML node with the lmk params
* typedef Factory<LandmarkBase, // Type of node created: LandmarkBasePtr
* const YAML::Node&> // YAML node with the lmk params
* LandmarkFactory;
* \endcode
*
@@ -86,7 +86,7 @@ namespace wolf
* > The specific type of landmark (e.g. LandmarkCorner2d, LandmarkAHP, LandmarkPolyline2d, etc) is indicated by a string that we call TYPE in this documentation.
*
* Specific object creation is invoked by the method ````create(TYPE, params ... )````, where
* - the TYPE of object to create is identified with a string
* - the TYPE of object to create is identified with a string. This string matches the name of the derived class.
* - the params may be provided in different forms -- see TypeInput.
*
* The methods to create specific objects are called __creators__.
@@ -102,9 +102,11 @@ namespace wolf
*
* #### Define correct TYPE names
* We use a std::string with literally the same text as the derived class name, e.g.:
* - ParamsSensorCamera -> ````"ParamsSensorCamera"````
* - ParamsSensorLaser2d -> ````"ParamsSensorLaser2d"````
* - LandmarkPolyline2d -> ````"LandmarkPolyline2d"````
* - ParamsSensorCamera -> ````"ParamsSensorCamera"````
* - SensorCamera -> ````"SensorCamera"````
* - ParamsSensorLaser2d -> ````"ParamsSensorLaser2d"````
* - SensorLaser2d -> ````"SensorLaser2d"````
* - LandmarkPolyline2d -> ````"LandmarkPolyline2d"````
* - etc.
*
* #### Access the factory
@@ -112,12 +114,18 @@ namespace wolf
* The first thing to know is that we have defined typedefs for the templates that we are using. For example:
*
* \code
* typedef Factory<ParamsSensorBase, std::string> FactoryParamsSensor;
* typedef Factory<ParamsProcessorBase, std::string> FactoryParamsProcessor;
* typedef Factory<LandmarkBase, YAML::Node> FactoryLandmark;
* typedef Factory<ParamsSensorBase, std::string> FactoryParamsSensor;
* typedef Factory<ParamsProcessorBase, std::string> FactoryParamsProcessor;
* typedef Factory<LandmarkBase, YAML::Node> FactoryLandmark;
* typedef Factory<SensorBase,
* const std::string&,
* const Eigen::VectorXd&,
* const ParamsSensorBasePtr> FactorySensor;
*
* \endcode
*
* Second to know, the Factory class is a <a href="http://stackoverflow.com/questions/1008019/c-singleton-design-pattern#1008289">singleton</a>: it can only exist once in your application.
* Second to know, the Factory class is a <a href="http://stackoverflow.com/questions/1008019/c-singleton-design-pattern#1008289">singleton</a>:
* it can only exist once in your application.
* To access it, use the static method get(),
*
* \code
@@ -150,7 +158,7 @@ namespace wolf
*
* \code
* static ParamsSensorBasePtr create(const std::string& _intrinsics_dot_yaml)
* static LandmarkBasePtr create(const YAML::Node& _lmk_yaml_node)
* static LandmarkBasePtr create(const YAML::Node& _lmk_yaml_node)
* \endcode
*
* See further down for an implementation example.
@@ -164,7 +172,7 @@ namespace wolf
* that knows how to create your specific object, e.g.:
*
* \code
* FactoryLandmark::get().registerCreator("POLYLINE 2d", LandmarkPolyline2d::create);
* FactoryLandmark::get().registerCreator("LandmarkPolyline2d", LandmarkPolyline2d::create);
* \endcode
*
* #### Automatic registration
@@ -172,7 +180,7 @@ namespace wolf
* For example, in sensor_camera_yaml.cpp we find the line:
*
* \code
* const bool registered_camera_intr = FactoryParamsSensor::get().registerCreator("CAMERA", createParamsSensorCamera);
* const bool registered_camera_intr = FactoryParamsSensor::get().registerCreator("ParamsSensorCamera", createParamsSensorCamera);
* \endcode
*
* which is a static invocation (i.e., it is placed at global scope outside of the ParamsSensorCamera class).
@@ -183,7 +191,7 @@ namespace wolf
* The method unregisterCreator() unregisters the ObjectXxx::create() method. It only needs to be passed the string of the object type.
*
* \code
* Factory<MyTypeBase, MyTypeInput>::get().unregisterCreator("CAMERA");
* Factory<MyTypeBase, MyTypeInput>::get().unregisterCreator("ParamsSensorCamera");
* \endcode
*
* #### Create objects using the factory
@@ -193,13 +201,13 @@ namespace wolf
* To create e.g. a LandmarkPolyline2d from a YAML node you type:
*
* \code
* LandmarkBasePtr lmk_ptr = Factory<LandmarkBasePtr, YAML::Node>::get().create("POLYLINE 2d", lmk_yaml_node);
* LandmarkBasePtr lmk_ptr = Factory<LandmarkBasePtr, YAML::Node>::get().create("LandmarkPolyline2d", lmk_yaml_node);
* \endcode
*
* or even better, make use of the convenient typedefs:
*
* \code
* LandmarkBasePtr lmk_ptr = FactoryLandmark::get().create("POLYLINE 2d", lmk_yaml_node);
* LandmarkBasePtr lmk_ptr = FactoryLandmark::get().create("LandmarkPolyline2d", lmk_yaml_node);
* \endcode
*
* ### Examples
@@ -224,7 +232,7 @@ namespace wolf
* }
*
* // Create a new landmark
* LandmarkBasePtr lmk_ptr = new LandmarkPolyline2d(points, first_defined, last_defined, first_id);
* LandmarkBasePtr lmk_ptr = std::make_shared<LandmarkPolyline2d>(points, first_defined, last_defined, first_id);
* lmk_ptr->setId(id);
*
* return lmk_ptr;
@@ -239,7 +247,7 @@ namespace wolf
* // Register landmark creator (put the register code inside an unnamed namespace):
* namespace
* {
* const bool registered_lmk_polyline_2d = FactoryLandmark::get().registerCreator("POLYLINE 2d", LandmarkPolyline2d::create);
* const bool registered_lmk_polyline_2d = FactoryLandmark::get().registerCreator("LandmarkPolyline2d", LandmarkPolyline2d::create);
* }
*
* \endcode