SPFA.h

Go to the documentation of this file.

/**
 * This file is part of ArmarX.
 *
 * ArmarX is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * ArmarX is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 * @author     Fabian Reister ( fabian dot reister at kit dot edu )
 * @author     Christian R. G. Dreher ( c dot dreher at kit dot edu )
 * @date       2021
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
#pragma once
 
#include <optional>
#include <vector>
 
#include <RobotAPI/libraries/aron/core/data/variant/forward_declarations.h>
 
#include <armarx/navigation/algorithms/ObstacleAwareVelocityLimit.h>
#include <armarx/navigation/algorithms/spfa/ShortestPathFasterAlgorithm.h>
#include <armarx/navigation/core/NavigationStackGeneralConfig.h>
#include <armarx/navigation/core/Trajectory.h>
#include <armarx/navigation/core/basic_types.h>
#include <armarx/navigation/core/types.h>
#include <armarx/navigation/global_planning/core.h>
#include <armarx/navigation/global_planning/optimization/OrientationOptimizer.h>
 
#include "GlobalPlanner.h"
 
namespace armarx::navigation::global_planning
{
 
    /**
     * @brief Parameters for AStar
     *
     */
    struct SPFAParams : public GlobalPlannerParams
    {
 
        /**
         * Spacing [mm] the planned path is resampled to before smoothing. Negative keeps the
         * default below.
         *
         * This is not only a density knob. The path is a polyline, so the straight chord
         * between two waypoints sags away from the route they were sampled from -- about 20 mm
         * at 200 mm spacing around a 45 degree corner. Where the corridor is only a little
         * wider than the clearance the checker enforces, that sag is the difference between a
         * path that passes and one that clips the corner, and no amount of optimizing can
         * remove it: it is a property of the spacing, not of the waypoint positions.
         */
        float resampleDistance{-1};
 
        /// Used when `resampleDistance` is negative.
        static constexpr float defaultResampleDistance{200.F};
 
        algorithms::spfa::ShortestPathFasterAlgorithm::Parameters algo;
 
        optimization::OrientationOptimizerParams optimizerParams;
 
        /**
         * Diagnostic switches for the post-processing stages. They are deliberately not part of
         * the Aron (de-)serialization: they exist to bisect the pipeline from tools such as the
         * `global_planning_analysis` application, not to be configured on the robot.
         */
        /// Run the SPFA position smoothing on the resampled path.
        bool enablePositionSmoothing{true};
 
        /**
         * Re-apply the obstacle-aware velocity limit after orientation optimization.
         *
         * Disabling this exposes the velocities as the earlier stages left them, which is the
         * only way to observe whether a stage produced a trajectory that violates the limit.
         */
        bool enableFinalVelocityClamp{true};
 
        Algorithms algorithm() const override;
        aron::data::DictPtr toAron() const override;
 
        static SPFAParams FromAron(const aron::data::DictPtr& dict);
    };
 
    // Helper class
    struct PlanningResult
    {
        core::Pose start;
        algorithms::spfa::ShortestPathFasterAlgorithm algorithm;
        std::optional<algorithms::spfa::ShortestPathFasterAlgorithm::Result> plan;
 
        /// Duration [s] of the SPFA grid search itself, which runs before `calculatePath`.
        float gridSearchDuration{0.F};
    };
 
    /**
     * @brief Information about collision recovery
     * 
     * When the robot starts in collision, this contains information about
     * the recovery position and the original (collision) start pose.
     */
    struct RecoveryInfo
    {
        core::Pose originalStartPose; ///< The original start pose (collision pose)
        Eigen::Vector2f recoveryPosition; ///< The found recovery position (collision-free)
    };
 
    class SPFA;
 
    class SPFAImpl
    {
    public:
        friend class SPFA;
        using Params = SPFAParams;
        using PlanningResult = ::armarx::navigation::global_planning::PlanningResult;
 
        SPFAImpl(const Params& params,
                 const core::GeneralConfig& generalParams,
                 const std::optional<navigation::algorithms::Costmap>& costmap);
 
        void updateCostmap(const std::optional<navigation::algorithms::Costmap>& costmap);
 
        std::optional<GlobalPlannerResult> plan(const core::Pose& start, const core::Pose& goal);
 
        PlanningResult executePlanner(const core::Pose& start);
        PlanningResult executePlannerFromPosition(const Eigen::Vector2f& startPosition);
        std::optional<GlobalPlannerResult>
        calculatePath(const PlanningResult& planner,
                      const core::Pose& goal,
                      const std::optional<RecoveryInfo>& recovery = std::nullopt);
 
        /// The obstacle-aware velocity limit this planner applies, for the current costmap.
        algorithms::ObstacleAwareVelocityLimit velocityLimit() const;
 
    protected:
        std::vector<Eigen::Vector2f> postProcessPath(const std::vector<Eigen::Vector2f>& path);
 
    private:
        Params params_;
        core::GeneralConfig generalConfig_;
        std::optional<navigation::algorithms::Costmap> costmap_;
    };
 
    /**
    * @class AStar
    * @ingroup Library-GlobalPlanner
    *
    * Implements the A* algorithm
    */
    class SPFA : public GlobalPlanner
    {
    public:
        using Params = SPFAParams;
        using PlanningResult = ::armarx::navigation::global_planning::PlanningResult;
 
        SPFA(const Params& params,
             const core::GeneralConfig& generalParams,
             const core::Scene& ctx);
        ~SPFA() override = default;
 
        std::optional<GlobalPlannerResult> plan(const core::Pose& goal) override;
        std::optional<GlobalPlannerResult> plan(const core::Pose& start,
                                                const core::Pose& goal) override;
 
        PlanningResult executePlanner(const core::Pose& start);
        std::optional<GlobalPlannerResult> calculatePath(const PlanningResult& planner,
                                                         const core::Pose& goal);
 
    private:
        SPFAImpl impl_;
    };
 
} // namespace armarx::navigation::global_planning