CRegistrationDeciderOrOptimizer.h

Go to the documentation of this file.

/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          http://www.mrpt.org/                          |
   |                                                                        |
   | Copyright (c) 2005-2017, Individual contributors, see AUTHORS file     |
   | See: http://www.mrpt.org/Authors - All rights reserved.                |
   | Released under BSD License. See details in http://www.mrpt.org/License |
   +------------------------------------------------------------------------+ */

#ifndef CREGISTRATIONDECIDEROROPTIMIZER_H
#define CREGISTRATIONDECIDEROROPTIMIZER_H

#include <mrpt/obs/CActionCollection.h>
#include <mrpt/obs/CSensoryFrame.h>
#include <mrpt/obs/CObservation.h>
#include <mrpt/graphs/CNetworkOfPoses.h>
#include <mrpt/utils/COutputLogger.h>
#include <mrpt/utils/CTimeLogger.h>
#include <mrpt/graphslam/misc/CWindowManager.h>

#include <string>
#include <map>

namespace mrpt
{
namespace graphslam
{
/**\brief Interface for implementing node/edge registration deciders or
 * optimizer classes.
 *
 * Specific interfaces - for implementing node/edge deciders / optimizers -
 * can inherit from CRegistrationDeciderOrOptimizer so that they can make use
 * of the generic methods defined in the latter.
 *
 * \note \b Convention: For the already implemented deciders/optimizers the
 * following naming convention has been used:
 * - NRD: Node Registration Decider class
 * - ERD: Edge Registration Decider class
 * - GSO: GraphSlam Optimizer class
 *
 * \ingroup mrpt_graphslam_grp
 */
template <class GRAPH_T = typename mrpt::graphs::CNetworkOfPoses2DInf>
class CRegistrationDeciderOrOptimizer : public mrpt::utils::COutputLogger
{
   public:
        /**\Default Ctor*/
        CRegistrationDeciderOrOptimizer();
        /**\Dtor*/
        virtual ~CRegistrationDeciderOrOptimizer();
        /**\brief Generic method for fetching the incremental action-observations
         * (or
         * observation-only) measurements
         *
         * \return True if operation was successful. Criteria for Success depend on
         * the decider/optimizer implementing this method
         */
        virtual bool updateState(
                mrpt::obs::CActionCollection::Ptr action,
                mrpt::obs::CSensoryFrame::Ptr observations,
                mrpt::obs::CObservation::Ptr observation) = 0;
        /**\brief Fetch a CWindowManager pointer.
         *
         * CWindowManager instance should contain a CDisplayWindow3D* and,
         * optionally, a CWindowObserver pointer so that interaction with the
         * window is possible
         */
        virtual void setWindowManagerPtr(
                mrpt::graphslam::CWindowManager* win_manager);

        /**\brief Fetch a std::mutex for locking the GRAPH_T
         * resource.
         *
         * Handy for realising multithreading in the derived classes.
         *
         * \warning Beware that prior to the decider/optimizer public method call,
         * the CCriticalSection will already be locked from CGraphSlamEngine_t
         * instance, but this isn't effective in multithreaded implementations where
         * the decider/optimizer itself has to lock the function at which the extra
         * thread runs.
         */
        virtual void setCriticalSectionPtr(std::mutex* graph_section);
        /**\brief Initialize visual objects in CDisplayWindow (e.g. \em add an
         * object to scene).
         *
         * \exception std::exception If the method is called without having first
         * provided a CDisplayWindow3D* to the class instance
         *
         * \sa setWindowManagerPtr, updateVisuals
         */
        virtual void initializeVisuals();
        /**\brief Update the relevant visual features in CDisplayWindow.
         *
         *\exception std::exception If the method is called without having first
         * provided a CDisplayWindow3D* to the class instance
         *
         * \sa setWindowManagerPtr, initializeVisuals
         */
        virtual void updateVisuals();
        /**\brief Get a list of the window events that happened since the last call.
         *
         * Method in derived classes is automatically called from the
         * CGraphSlamEngine_t instance. After that, decider/optimizer should just
         * fetch the parameters that it is interested in.
         */
        virtual void notifyOfWindowEvents(
                const std::map<std::string, bool>& events_occurred);
        /**\brief Load the necessary for the decider/optimizer configuration
         * parameters.
         */
        virtual void loadParams(const std::string& source_fname);
        /**\brief Print the problem parameters - relevant to the decider/optimizer
         * to the
         * screen in a unified/compact way.
         */
        virtual void printParams() const;
        /**\brief Fill the provided string with a detailed report of the
         * decider/optimizer state.
         *
         * Report should include (part of) the following:
         * - Timing of important methods
         * - Properties fo class at the current time
         * - Logging of commands until current time
         */
        virtual void getDescriptiveReport(std::string* report_str) const;

        /**\brief Fetch the graph on which the decider/optimizer will work on.
         *
         */
        virtual void setGraphPtr(GRAPH_T* graph);

        /**\brief Initialize the COutputLogger, CTimeLogger instances given the
         * name of the decider/optimizer at hand
         */
        virtual void initializeLoggers(const std::string& name);
        virtual void setClassName(const std::string& name);
        bool isMultiRobotSlamClass();

        std::string getClassName() const { return m_class_name; };
   protected:
        /**\brief Handy function for making all the visuals assertions in a
         * compact manner
         */
        virtual void assertVisualsVars();
        /**\brief Pointer to the graph that is under construction */
        GRAPH_T* m_graph;
        std::mutex* m_graph_section;

        /** \name Visuals-related variables methods
         */
        /**\{*/
        /**\brief Pointer to the CWindowManager object used to store
         * visuals-related instances
         */
        mrpt::graphslam::CWindowManager* m_win_manager;
        /**\brief Window to use */
        mrpt::gui::CDisplayWindow3D* m_win;
        /**\brief CWindowObserver object for monitoring various visual-oriented
         * events.*/
        mrpt::graphslam::CWindowObserver* m_win_observer;
        bool m_initialized_visuals;
        /**\}*/

        /**\brief Time logger instance */
        mrpt::utils::CTimeLogger m_time_logger;
        /**\brief Name of the class instance */
        std::string m_class_name;
        /**\brief Boolean indicating if the current class can be used in
         * multi-robot SLAM operations
         */
        bool is_mr_slam_class;

        /**\brief Separator string to be used in debugging messages
         */
        static const std::string header_sep;
        static const std::string report_sep;
};
}
}  // end of namespaces

#include "CRegistrationDeciderOrOptimizer_impl.h"
#endif /* end of include guard: CREGISTRATIONDECIDEROROPTIMIZER_H */