Built-in Plugins

The registered implementations shipped with open_apero_core, by role, and GraphBeamSearch, the abstract base of the two beam searches; the abstract bases a new plugin derives from are on Plugin Interfaces. Their YAML keys are listed in the parameter reference, and the module pages explain each.

Generators

class RRAG : public open_apero::GraphGenerator

#include <open_apero_core/plugin/generator/rrag.h>

RRAG (rapidly-exploring random annulus graph): samples new nodes in the annulus [min_edge_length, max_edge_length] around existing clusters and maintains the graph.

The paper’s tree-shaped variants, RRAT and RRAT*, are registered as “RRT” and “RRTStar”.

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validates sample_max_tries >= 0, then the GraphGenerator edge lengths.

Parameters:

error_message – Output string describing any validation errors.

Returns:

True if all parameters are valid.

virtual void connectStartNode(Node *start_node) override

Gives an intermediate start node its outgoing edges to clusters within reach.

Called by the layer after expansion when the start node has no out-edges, so clusters born this cycle connect in the same cycle. No-op for a tree, whose start node is connected by construction.

virtual bool containsNode(const Node *node) const override

Whether node is still a member of this generator’s structure, intermediate nodes included.

Pure virtual again: Generator’s KD-tree default excludes intermediate nodes. Pointer-only check; must not dereference node.

virtual std::pair<GraphType*, Node*> generateInitNode(const RobotState &init_state) override

Create the initial graph node from the robot’s starting state.

Parameters:

init_state – The initial robot state.

Returns:

A pair of the graph and the initial node.

virtual bool generateNewEdges(NodeClusterPtrs &node_cluster, std::vector<Edge*> &new_edges) override

Generate edges connecting a new node cluster to the existing graph.

Parameters:

• node_cluster – The node cluster to connect.

• new_edges – Output vector of newly created edges.

Returns:

True if edges were successfully generated.

virtual NodeClusterPtrs generateNewNode(Node *start_node) override

Sample a new point and add it as a node cluster to the graph.

Parameters:

start_node – The current start node.

Returns:

Pointers to the newly created node cluster.

virtual std::vector<Edge*> getAllEdges(Node *start_node) const override

Retrieve every edge of the graph.

Parameters:

start_node – Unused.

Returns:

Vector of pointers to all edges.

virtual std::vector<Node*> getAllNodes(Node *start_node) const override

Retrieve every node of the graph.

Parameters:

start_node – Unused.

Returns:

Vector of pointers to all nodes.

virtual std::pair<Node*, Edge*> insertIntermediateNode(Node *start_node, Node *goal_node, Edge *edge, int node_index) override

Insert an intermediate node along an existing edge.

Parameters:

• start_node – The source node of the edge.

• goal_node – The target node of the edge.

• edge – The edge to split.

• node_index – Index of the intermediate point along the trajectory.

Returns:

A pair of the new intermediate node and the new edge.

virtual Node *insertIntermediateNodeAtCurrentState(Node *previous, const Edge &executed_edge) override

Insert a new intermediate node at the endpoint of executed_edge into the boost graph.

Never returns nullptr: the new vertex stays as a detached intermediate start node when no out-edge can be planned from it. Removes the previous intermediate start node either way.

Parameters:

• previous – The current start vertex in this graph.

• executed_edge – Edge whose endpoint gives the new node’s robot state.

inline virtual bool isEdgeBidirectional() const override

Graph edges are bidirectional.

inline virtual void resetEpisode() override

Resets graph state for a new episode.

explicit RRAG(AgentInterface &agent)

Construct a RRAG.

Parameters:

agent – Reference to the parent agent interface.

virtual void setNewStartNode(Node *previous_start, Node *new_start) override

Update the start node of the graph after the robot moves.

Parameters:

• previous_start – The old start node.

• new_start – The new start node.

virtual bool setNodeOrientation(Node *node, const Eigen::Quaterniond &orientation) override

Change the orientation of a node and update connected edges.

Parameters:

• node – The node to reorient.

• orientation – The new orientation quaternion.

Returns:

True if the orientation was successfully set.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Initialize parameters from the parameter map.

Parameters:

param_map – Pointer to the plugin parameter map.

virtual void updateNodeEdge(Node *start_node) override

Re-checks the nodes and edges a map update can affect, restores missing edges, and prunes.

Parameters:

start_node – The current start node.

virtual ~RRAG() = default

class RRT : public open_apero::TreeGenerator

#include <open_apero_core/plugin/generator/rrt.h>

RRT generator (RRAT in the paper) that expands a tree with random linear segments.

Subclassed by open_apero::generator::RRTStar

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validates sample_max_tries >= 0, then the GraphGenerator edge lengths.

virtual NodeClusterPtrs generateNewNode(Node *start_node) override

Samples a random state and generates a new node cluster near the tree.

Parameters:

start_node – The current root; seeds the first child of an empty tree (the nearest node comes from the KD-tree).

Returns:

Cluster of newly generated candidate nodes (empty on failure).

explicit RRT(AgentInterface &agent)

Constructs the RRT generator and binds it to the agent.

virtual void setNewStartNode(Node *previous_start, Node *new_start) override

Updates the tree root when the robot moves to a new start node.

Parameters:

• previous_start – The old root node being replaced.

• new_start – The new root node after the robot has moved.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads RRT-specific parameters (sample_max_tries) from the config map.

class RRTStar : public open_apero::generator::RRT

#include <open_apero_core/plugin/generator/rrt_star.h>

Extension of RRT (RRAT* in the paper) that rewires tree segments for cheaper paths.

Public Functions

virtual bool generateNewEdges(NodeClusterPtrs &node_cluster, std::vector<Edge*> &new_edges) override

Generates edges for a node cluster and rewires nearby nodes to cheaper parents.

Parameters:

• node_cluster – Cluster of newly generated nodes to connect into the tree.

• new_edges – Output list populated with the newly created edges.

Returns:

true on success.

void rewireTree(TreeNode *root)

Rewires the entire tree rooted at root to ensure optimal parent assignments.

Parameters:

root – The root of the tree to rewire.

explicit RRTStar(AgentInterface &agent)

Constructs the RRT* generator and binds it to the agent.

virtual void setNewStartNode(Node *previous_start, Node *new_start) override

Updates the tree root when the robot moves to a new start node.

Parameters:

• previous_start – The old root node being replaced.

• new_start – The new root node after the robot has moved.

Evaluators

class NaiveEvaluator : public open_apero::evaluator::SimulatedSensorEvaluator

#include <open_apero_core/plugin/evaluator/naive_evaluator.h>

Evaluates nodes by counting the number of yet unobserved visible voxels.

Public Functions

virtual double getRealAccumulatedGain() const override

Returns the map’s explored volume.

Returns:

Explored volume [m^3].

explicit NaiveEvaluator(AgentInterface &agent)

Constructs a NaiveEvaluator and binds it to the agent.

class SurfaceFrontierEvaluator : public open_apero::evaluator::SimulatedSensorEvaluator

#include <open_apero_core/plugin/evaluator/surface_frontier_evaluator.h>

Scores nodes by their visible surface frontiers.

Subclassed by open_apero::evaluator::VoxelWeightEvaluator

Public Functions

virtual double getRealAccumulatedGain() const override

Returns the map’s mapped surface area.

Returns:

Mapped surface area [m^2].

virtual void getVisualization(VisualizationMarkers *markers, const Node *node) override

Visualizes per-voxel frontier status at the node.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads frontier evaluator parameters (weights, checking distance) from the config map.

Parameters:

param_map – Pointer to the plugin parameter map.

Throws:

std::runtime_error – if the agent’s map is not an OccupancyMap.

explicit SurfaceFrontierEvaluator(AgentInterface &agent)

Constructs a SurfaceFrontierEvaluator and binds it to the agent.

class VoxelWeightEvaluator : public open_apero::evaluator::SurfaceFrontierEvaluator

#include <open_apero_core/plugin/evaluator/voxel_weight_evaluator.h>

Estimates observation impact from TSDF weights and frontier gain.

Public Functions

virtual void getVisualization(VisualizationMarkers *markers, const Node *node) override

Visualizes per-voxel weight-based gain contribution at the node.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads the impact factor and voxel weights.

Parameters:

param_map – Pointer to the plugin parameter map.

Throws:

std::runtime_error – if the agent’s map is not a TsdfMap.

explicit VoxelWeightEvaluator(AgentInterface &agent)

Constructs a VoxelWeightEvaluator and binds it to the agent.

class SimpleYawPlanningEvaluator : public open_apero::evaluator::YawPlanningEvaluator

#include <open_apero_core/plugin/evaluator/simple_yaw_planning_evaluator.h>

Scores the robot’s candidate orientations (RobotModel::sampleOrientations) through the YawPlanningEvaluator base; adds the visualization and getRealAccumulatedGain().

Public Functions

virtual double getRealAccumulatedGain() const override

Returns the total accumulated gain from the following evaluator.

Returns:

Accumulated gain value.

virtual void getVisualization(VisualizationMarkers *markers, const Node *node) override

Visualizes the gain of the best yaw orientation found for the node.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads visualize_followup, then the base keys; the following evaluator comes from following_evaluator_args.

explicit SimpleYawPlanningEvaluator(AgentInterface &agent)

Constructs a SimpleYawPlanningEvaluator and binds it to the agent.

Path Planners

class GraphBeamSearch : public open_apero::PathPlanner

#include <open_apero_core/plugin/path_planner/graph_beam_search.h>

Beam search over a graph, up to beam_depth edges; a subclass decides which paths a round keeps.

planPath() suppresses gains, offers the still-reachable tail of the previous path as candidates (check_previous_path), runs the subclass’s beam rounds (searchBeams()) and concludes the search.

Subclassed by open_apero::path_planner::GraphDepthWiseBeamSearch, open_apero::path_planner::GraphNodeWiseBeamSearch

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validates beam_width >= 1 and beam_depth >= 1, then the PathPlanner checks.

virtual std::pair<std::vector<Node*>, double> planPath(Node *start_node, GraphType *graph, Node *required_terminal_node) override

Select the next best path from the graph by beam search.

Parameters:

• start_node – The node to start the search from.

• graph – The graph to search over; a null graph has no path to any destination.

• required_terminal_node – Node the selected path must end at, or nullptr to search freely.

Returns:

A pair of the best path (as a vector of nodes) and its value.

inline virtual void resetEpisode() override

Resets path planner state for a new episode.

Clears the cached previous path, resets the gain-cost table (PathPlanner::resetEpisode()) and reseeds the RNG.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Initialize parameters from the parameter map.

Parameters:

param_map – Pointer to the plugin parameter map.

void setupRaw(Objective obj, int beam_depth, int beam_width, bool check_previous_path, bool is_gain_correlated = false, double gain_suppression_radius = 0.0)

Directly set search parameters for offline benchmarking.

Parameters:

• obj – The optimization objective.

• beam_depth – Maximum search depth.

• beam_width – Number of candidates retained per level (depth-wise) or per graph node (node-wise).

• check_previous_path – Whether to check if the previous path is still valid.

• is_gain_correlated – Whether nodes share gain anchors, so a path counts each anchor once.

• gain_suppression_radius – Radius [m] of the suppression over node clusters (suppressNonMaximumClusters); 0 suppresses nothing.

Protected Functions

GraphBeamSearch(AgentInterface &agent, std::string raw_seed_label)

Construct a beam search.

Parameters:

• agent – Reference to the parent agent interface.

• raw_seed_label – Seeding label of setupRaw(), one per search.

virtual void searchBeams(const Path &start_path, GraphType *graph, Node *required_terminal_node, PathSteps &steps, PathLedger &ledger, Path &best, double &best_score) = 0

The beam rounds: extends paths from start_path for up to beam_depth edges within the cost budget and offers every extension to updateBest().

Parameters:

• start_path – The path holding only the start node.

• graph – The graph to search over.

• required_terminal_node – Node the selected path must end at, or nullptr.

• steps – The search’s path steps.

• ledger – The search’s path ledger.

• best – The running best, as folded by updateBest().

• best_score – The running best’s score.

Protected Attributes

int p_beam_depth_ = 10

int p_beam_width_ = 1

bool p_check_previous_path_ = true

PathNodes previous_path_

SeededRng rng_

class GraphNodeWiseBeamSearch : public open_apero::path_planner::GraphBeamSearch

#include <open_apero_core/plugin/path_planner/graph_node_wise_beam_search.h>

Selects the next path using node-wise beam search (NBS) over a graph.

Advances depth by depth like depth-wise beam search, but keeps up to beam_width partial paths per graph node (a min-heap per node) instead of one global beam.

Public Functions

explicit GraphNodeWiseBeamSearch(AgentInterface &agent)

Construct a GraphNodeWiseBeamSearch path planner.

Parameters:

agent – Reference to the parent agent interface.

class GraphDepthWiseBeamSearch : public open_apero::path_planner::GraphBeamSearch

#include <open_apero_core/plugin/path_planner/graph_depth_wise_beam_search.h>

Selects the next path using depth-wise beam search (DBS) over a graph.

Expands paths depth by depth up to beam_depth, keeping the top beam_width candidates per level; with check_previous_path the previously selected path competes as a candidate.

Public Functions

explicit GraphDepthWiseBeamSearch(AgentInterface &agent)

Construct a GraphDepthWiseBeamSearch path planner.

Parameters:

agent – Reference to the parent agent interface.

class GraphShortestPathTreeSearch : public open_apero::PathPlanner

#include <open_apero_core/plugin/path_planner/graph_shortest_path_tree_search.h>

Selects a path from a shortest-path tree (SPT).

Computes shortest paths from the start node (Dijkstra) and scores the path to each goal candidate: nodes whose gain lies within top_node_percentage of the gain range below the maximum, plus frontier nodes.

Public Functions

explicit GraphShortestPathTreeSearch(AgentInterface &agent)

Construct a GraphShortestPathTreeSearch path planner.

Parameters:

agent – Reference to the parent agent interface.

virtual std::pair<std::vector<Node*>, double> planPath(Node *start_node, GraphType *graph, Node *required_terminal_node) override

Select the next best path using shortest path tree search.

Parameters:

• start_node – The node to start the search from.

• graph – The graph to search over; a null graph has no path to any destination.

• required_terminal_node – Node the selected path must end at, or nullptr to search freely.

Returns:

A pair of the best path (as a vector of nodes) and its value.

inline virtual void resetEpisode() override

Reseed the tie-break RNG for a new episode.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Initialize parameters from the parameter map.

Parameters:

param_map – Pointer to the plugin parameter map.

inline void setupRaw(Objective obj, double top_node_percentage, bool is_gain_correlated = false)

Directly set search parameters for offline benchmarking.

Parameters:

• obj – The optimization objective.

• top_node_percentage – Fraction of the gain range, below the maximum gain, whose nodes are candidates.

• is_gain_correlated – Whether nodes share gain anchors, so a path counts each anchor once.

class GraphTspSearch : public open_apero::PathPlanner

#include <open_apero_core/plugin/path_planner/graph_tsp_search.h>

Selects the next path by solving a Traveling Salesman Problem over the graph.

The tour minimizes the summed edge cost through the selected nodes (the top top_node_percentage of the gain range plus frontier nodes). objective is read if present but unused, and the cost budget is ignored here; the agent enforces it during execution. Costs are rounded down to integers after scaling by cost_scale (1000 gives millisecond resolution for time costs).

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validate that cost_scale is finite and positive.

Parameters:

error_message – Receives the reason on failure.

Returns:

True if the parameters are valid.

explicit GraphTspSearch(AgentInterface &agent)

Construct a GraphTspSearch path planner.

Parameters:

agent – Reference to the parent agent interface.

virtual std::pair<std::vector<Node*>, double> planPath(Node *start_node, GraphType *graph, Node *required_terminal_node) override

Select the next best path by solving a TSP over the graph.

The tour comes from the routing solver and is not constrained to a destination.

Parameters:

• start_node – The node to start the search from.

• graph – The graph to search over.

• required_terminal_node – Must be nullptr; any destination yields an empty path.

Returns:

A pair of the best path (as a vector of nodes) and its value.

inline virtual void resetEpisode() override

Reseed the tie-break RNG for a new episode.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Initialize parameters from the parameter map.

Parameters:

param_map – Pointer to the plugin parameter map.

inline void setupRaw(Objective obj, double top_node_percentage)

Directly set search parameters for offline benchmarking.

Parameters:

• obj – The optimization objective.

• top_node_percentage – Fraction of the gain range, below the maximum gain, whose nodes the tour visits.

class TreeBestValue : public open_apero::PathPlanner

#include <open_apero_core/plugin/path_planner/tree_best_value.h>

Selects the whole root-to-node path that scores best under the objective.

Scores the path from the root to every node of the tree rooted at the current node by the configured Objective (PathPlanner::updateBest) and returns the best one.

Public Functions

virtual std::pair<std::vector<Node*>, double> planPath(Node *start_node, GraphType *graph, Node *required_terminal_node) override

Select the next best path by finding the highest-value subtree.

Parameters:

• start_node – The node to start the search from.

• graph – Unused for tree-based search (may be nullptr).

• required_terminal_node – Tree node the selected path must end at, or nullptr to search freely.

Returns:

A pair of the best path (as a vector of nodes) and its value.

inline virtual void resetEpisode() override

Reseed the random-child RNG for a new episode.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Initialize parameters from the parameter map.

Parameters:

param_map – Pointer to the plugin parameter map.

explicit TreeBestValue(AgentInterface &agent)

Construct a TreeBestValue path planner.

Parameters:

agent – Reference to the parent agent interface.

class NoOpPathPlanner : public open_apero::PathPlanner

#include <open_apero_core/plugin/path_planner/no_op_path_planner.h>

PathPlanner placeholder for layers whose planPath implementation performs selection without a graph path planner. Always returns an empty path.

Public Functions

explicit NoOpPathPlanner(AgentInterface &agent)

virtual std::pair<std::vector<Node*>, double> planPath(Node *start_node, GraphType *graph, Node *required_terminal_node) override

Select the best path from start_node that ends at required_terminal_node.

Must return an EMPTY path, never a fallback step, when the destination is unreachable; finishing through concludeSearch() guarantees this. The path traverses at least one edge, so start_node is never a valid destination.

Parameters:

• start_node – The node to start path selection from.

• graph – Pointer to the planning graph; nullptr when the layer’s generator is a tree (TreeGenerator).

• required_terminal_node – Node the selected path must end at, or nullptr to search freely.

Returns:

The best path and its value, or an empty path when the destination is unreachable.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Set up the object from a parameter map.

Besides the configured keys, a PluginFactory supplies “param_namespace” (the namespace the keys came from; a plugin derives its children’s default namespaces from it) and “verbose_text”.

Parameters:

param_map – Pointer to a map of parameter name-value string pairs.

Cost Computers

class IdentityCost : public open_apero::CostComputer

#include <open_apero_core/plugin/cost_computer/identity_cost.h>

Prices every edge at 1: path cost and the budget count edges.

Public Functions

virtual bool computeCost(Edge *edge) override

Compute the cost for a given edge: 1, or 0 for a trajectory of fewer than 2 states.

Parameters:

edge – Pointer to the edge whose cost is computed.

Returns:

False for a trajectory of fewer than 2 states.

explicit IdentityCost(AgentInterface &agent)

Construct an IdentityCost cost computer.

Parameters:

agent – Reference to the parent agent interface.

class TrajectoryLength : public open_apero::CostComputer

#include <open_apero_core/plugin/cost_computer/trajectory_length.h>

Cost computer that computes the traveled distance of a trajectory segment.

The cost of an edge is set to the total Euclidean path length of the trajectory associated with that edge. This is useful for planners that seek to minimize total distance traveled.

Public Functions

virtual bool computeCost(Edge *edge) override

Compute the path length cost for a given edge.

Parameters:

edge – Pointer to the edge whose cost is computed.

Returns:

True on success.

virtual double getCostLowerBound(const RobotState &start, const RobotState &goal) override

The straight-line distance between the sensor positions.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Initialize parameters from the parameter map.

Parameters:

param_map – Pointer to the plugin parameter map.

explicit TrajectoryLength(AgentInterface &agent)

Construct a TrajectoryLength cost computer.

Parameters:

agent – Reference to the parent agent interface.

class TrajectoryTime : public open_apero::CostComputer

#include <open_apero_core/plugin/cost_computer/trajectory_time.h>

Cost computer that computes the execution time of a single trajectory segment.

The cost of an edge is set to the time required to execute the trajectory associated with that edge. This is useful for time-optimal planning.

Public Functions

virtual bool computeCost(Edge *edge) override

Compute the execution time cost for a given edge.

Parameters:

edge – Pointer to the edge whose cost is computed.

Returns:

True on success.

virtual double getCostLowerBound(const RobotState &start, const RobotState &goal) override

The larger of the sensor distance over max_linear_velocity and the yaw difference over max_yaw_rate.

Holds for a trajectory whose every step keeps those limits, as RobotModel::steer() promises.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Initialize parameters from the parameter map.

Parameters:

param_map – Pointer to the plugin parameter map.

explicit TrajectoryTime(AgentInterface &agent)

Construct a TrajectoryTime cost computer.

Parameters:

agent – Reference to the parent agent interface.

Backtrackers

class Reverse : public open_apero::Backtracker

#include <open_apero_core/plugin/backtracker/reverse.h>

Replays previously executed trajectory segments in reverse order.

Maintains a fixed-size buffer of recent forward trajectories (oldest segment evicted first when full). Each buildTrajectory call pops the most recent segment and returns its reverse.

Public Functions

virtual bool buildTrajectory(const RobotState &state, RobotTrajectory *out) override

Build a recovery trajectory from the robot’s current state.

Strategy hook implemented by concrete backtrackers (Reverse / RotateInPlace / RotateReverse). Returns false if no recovery is currently possible (e.g. Reverse with an empty queue).

Parameters:

• state – Robot’s current state (start of the recovery trajectory).

• out – Output trajectory; first waypoint must be at time 0 and size() must be >= 2 on success.

Returns:

true if a valid trajectory was produced.

virtual bool checkParamsValid(std::string *error_message) override

Check whether the current parameter set is valid.

Parameters:

error_message – Pointer to a string that will be filled with an error description on failure.

Returns:

True if parameters are valid, false otherwise. Default implementation always returns true.

virtual bool recordExecutedEdge(const Edge &edge) override

Record an executed edge for use in future recovery trajectories. Called by the owning layer in onStateReached whenever a non-backtrack edge has just been executed.

inline virtual void resetEpisode() override

Resets per-episode backtracker state. Default no-op.

explicit Reverse(AgentInterface &agent)

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Set up the object from a parameter map.

Besides the configured keys, a PluginFactory supplies “param_namespace” (the namespace the keys came from; a plugin derives its children’s default namespaces from it) and “verbose_text”.

Parameters:

param_map – Pointer to a map of parameter name-value string pairs.

class RotateInPlace : public open_apero::Backtracker

#include <open_apero_core/plugin/backtracker/rotate_in_place.h>

Rotates the robot in place by a configurable step angle. Tracks an initial-rotation budget so isInitialExplorationDone() can flag when the start-of-episode sweep is finished.

Subclassed by open_apero::backtracker::RotateReverse

Public Functions

virtual bool buildTrajectory(const RobotState &state, RobotTrajectory *out) override

Build a recovery trajectory from the robot’s current state.

Strategy hook implemented by concrete backtrackers (Reverse / RotateInPlace / RotateReverse). Returns false if no recovery is currently possible (e.g. Reverse with an empty queue).

Parameters:

• state – Robot’s current state (start of the recovery trajectory).

• out – Output trajectory; first waypoint must be at time 0 and size() must be >= 2 on success.

Returns:

true if a valid trajectory was produced.

virtual bool checkParamsValid(std::string *error_message) override

Validates rotation_step > 0 and initial_rotate_angle >= 0.

virtual bool isInitialExplorationDone() override

Whether the backtracker has finished its initial sweep (e.g. a one-time rotation at episode start). The owning layer consults this to decide whether to bump its priority.

inline virtual void resetEpisode() override

Resets per-episode backtracker state. Default no-op.

explicit RotateInPlace(AgentInterface &agent)

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Set up the object from a parameter map.

Besides the configured keys, a PluginFactory supplies “param_namespace” (the namespace the keys came from; a plugin derives its children’s default namespaces from it) and “verbose_text”.

Parameters:

param_map – Pointer to a map of parameter name-value string pairs.

class RotateReverse : public open_apero::backtracker::RotateInPlace

#include <open_apero_core/plugin/backtracker/rotate_reverse.h>

Two-strategy backtracker: first does the initial rotation sweep (and further rotations whenever the reverse queue is empty), otherwise reverses the most recent forward trajectory.

Public Functions

virtual bool buildTrajectory(const RobotState &state, RobotTrajectory *out) override

Build a recovery trajectory from the robot’s current state.

Strategy hook implemented by concrete backtrackers (Reverse / RotateInPlace / RotateReverse). Returns false if no recovery is currently possible (e.g. Reverse with an empty queue).

Parameters:

• state – Robot’s current state (start of the recovery trajectory).

• out – Output trajectory; first waypoint must be at time 0 and size() must be >= 2 on success.

Returns:

true if a valid trajectory was produced.

virtual bool checkParamsValid(std::string *error_message) override

Validates rotation_step > 0 and initial_rotate_angle >= 0.

virtual bool recordExecutedEdge(const Edge &edge) override

Record an executed edge for use in future recovery trajectories. Called by the owning layer in onStateReached whenever a non-backtrack edge has just been executed.

inline virtual void resetEpisode() override

Resets per-episode backtracker state. Default no-op.

explicit RotateReverse(AgentInterface &agent)

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Set up the object from a parameter map.

Besides the configured keys, a PluginFactory supplies “param_namespace” (the namespace the keys came from; a plugin derives its children’s default namespaces from it) and “verbose_text”.

Parameters:

param_map – Pointer to a map of parameter name-value string pairs.

class ExecutedTrajectoryQueue

#include <open_apero_core/plugin/backtracker/reverse.h>

The executed trajectories a reversing backtracker replays: at most a capacity of them, newest last, the oldest evicted first.

Public Functions

inline void clear()

inline bool empty() const

bool popReversed(RobotTrajectory *out)

Removes the newest trajectory and returns it reversed.

Returns:

False, leaving out untouched, when the queue is empty.

bool record(const Edge &edge, int capacity, std::string *error)

Records the trajectory of an executed edge; a backtracker’s own edge is skipped.

Parameters:

• edge – The executed edge.

• capacity – Maximum number of trajectories held (> 0).

• error – Set when the edge is refused.

Returns:

False, recording nothing, when the trajectory has fewer than 2 states.

Robot Models

class SimpleRobot : public open_apero::RobotModel

#include <open_apero_core/plugin/robot_model/simple_robot.h>

Robot model defined by geometric collision and contact spheres for traversability checking.

Subclassed by open_apero::robot_model::SimpleFallbackRobot

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validates that all required parameters are set and consistent.

virtual bool getBodyBounds(const RobotState &state, Eigen::Vector3d *min, Eigen::Vector3d *max) const override

Box over every collision and contact sphere as placed at state, each grown by its safe margin.

False when a placement fails or the robot has no spheres.

inline bool getCollisionSpheresWorldFrame(const RobotState *robot_state, GeometricSpheres &collision_spheres) const

Returns collision spheres in the world frame.

inline bool getContactSpheresWorldFrame(const RobotState *robot_state, GeometricSpheres &contact_spheres) const

Returns contact spheres in the world frame.

virtual bool getGeometricSpheresWorldFrame(const RobotState *robot_state, GeometricSpheres &spheres, bool use_contact_spheres) const

Transforms collision or contact spheres into the world frame for a given robot state.

Parameters:

• robot_state – The current robot pose.

• spheres – Output list of spheres in world coordinates.

• use_contact_spheres – If true, returns contact spheres; otherwise returns collision spheres.

Returns:

true on success.

virtual double getStateClearance(const RobotState &state, Map *map) const override

Smallest relative margin any collision sphere keeps (see getSphereClearance).

Contact spheres are excluded. 1.0 when no map, no distance field or no sphere constrains it.

virtual Traversability placeRobotAtSensorPose(RobotState *robot_state, const Transform3d &sensor_transform, Map *map = nullptr) const override

Places the robot so its sensor is at the given pose; robot_state is always written.

kTraversable / kUntraversable vouch for the isStateTraversable verdict, including every planner constraint it applies (hit regions, bounding volume); kUnset makes no claim and the caller must ask isStateTraversable. Never returns kPotentiallyTraversable.

Parameters:

• robot_state – Output robot state to populate (always written).

• sensor_transform – Sensor transform in world frame.

• map – Optional planner map for map-aware placement and vouching.

Returns:

Placement-layer traversability verdict (see above).

virtual bool planTrajectory(const RobotState &start, const RobotState &goal, Map *map, RobotTrajectory *trajectory) override

Plans a feasible trajectory from start to goal via a straight-line steer.

Returns false if the steer produces no motion or is untraversable. Subclasses may override to add a fallback strategy (see SimpleFallbackRobot).

virtual void resetEpisode() override

Reseeds the sampling RNG and clears the mapped region for a new episode.

virtual bool samplePosition(Eigen::Vector3d *pos, double z_default) const override

Samples a position within the bounding volume, optionally narrowed to the mapped region.

With restrict_sampling_to_mapped_region every sampled axis is confined to the intersection of the bounding volume and the mapped region; z is sampled only when sample_z is set.

virtual bool samplePositionNear(const Eigen::Vector3d &center, double max_distance_3d, double max_distance_xy, Eigen::Vector3d *pos, double z_default) const override

Samples a random position in the neighborhood of a point of interest.

Same bounds and z convention as samplePosition, further restricted to within max_distance_3d of center in 3D and max_distance_xy horizontally (both apply). The default returns false, like samplePosition().

Parameters:

• center – Point to sample around, in world frame.

• max_distance_3d – Maximum 3D distance from center.

• max_distance_xy – Maximum horizontal distance from center.

• pos – Output sampled position.

• z_default – Z value used when the robot is configured for 2D sampling.

Returns:

true if a position was sampled; false if no bounds are configured or the neighborhood holds no admissible position.

inline virtual bool samplesHeight() const override

Whether sampled positions vary in height; false for a robot that plans in a plane. Default: true.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads collision geometry, bounds, and traversability settings.

explicit SimpleRobot(AgentInterface &agent)

Constructs SimpleRobot and binds it to the agent.

virtual RobotTrajectory steer(const RobotState &start, const RobotState &goal, Map *map = nullptr) const override

Steers from start toward goal using position and yaw stepping.

The robot rotates in-place to face the travel direction, translates at v_max, then rotates to match the goal orientation.

Precondition: start and goal are level (zero pitch). Each step rebuilds the orientation from yaw alone, so a pitched start loses its pitch and a pitched goal throws std::runtime_error.

Parameters:

• start – The start robot state.

• goal – The goal robot state.

• map – Optional planner map for map-aware trajectory generation.

Returns:

A dense trajectory of robot states advancing by dt per step.

virtual void update() override

Refreshes the cached mapped region that restricts where samples are drawn.

virtual ~SimpleRobot() = default

class SimpleFallbackRobot : public open_apero::robot_model::SimpleRobot

#include <open_apero_core/plugin/robot_model/simple_fallback_robot.h>

SimpleRobot extended with a local sampling-based fallback planner.

Inherits all geometry, kinematics, and collision logic from SimpleRobot. Its planTrajectory() runs an OMPL planner over a bounded local state space when the base class’s straight-line steer is untraversable.

Public Functions

virtual bool planTrajectory(const RobotState &start, const RobotState &goal, Map *map, RobotTrajectory *trajectory) override

Plans a feasible trajectory from start to goal.

Tries the straight-line steer first; if it is untraversable but both endpoints are traversable, runs the OMPL planner in a local window around start/goal and validates its result.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads SimpleRobot parameters plus OMPL planner configuration.

With a planner configured and AgentInterface::getRandomSeed() >= 0, seeds OMPL’s RNG before building the planner. That RNG is process-global: the last robot set up decides the seed.

Parameters:

param_map – Pointer to the plugin parameter map.

explicit SimpleFallbackRobot(AgentInterface &agent)

~SimpleFallbackRobot() override = default

Sensor Models

class IterativeRayCaster : public open_apero::sensor_model::CameraModel

#include <open_apero_core/plugin/sensor_model/iterative_ray_caster.h>

Starts coarse and doubles the ray density in each farther distance section.

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validates the derived ray grid, which needs at least two rays per axis.

Parameters:

error_message – Populated with a description of the first validation failure.

Returns:

true if all parameters are valid.

virtual bool getVisibleVoxels(VoxelOccupancyMap *result, const Transform3d &sensor_transform) override

Returns visible voxels using adaptive ray splitting.

Parameters:

• result – Output map of voxel positions to occupancy states.

• sensor_transform – Sensor transform in world frame.

Returns:

true on success.

explicit IterativeRayCaster(AgentInterface &agent)

Constructs the IterativeRayCaster and binds it to the agent.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads ray step, downsampling, and split distances.

virtual ~IterativeRayCaster() = default

class IterativeRayCasterLidar : public open_apero::sensor_model::LidarModel

#include <open_apero_core/plugin/sensor_model/iterative_ray_caster_lidar.h>

Lidar ray caster that starts coarse and doubles the ray density in each farther distance section.

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validates the LiDAR, ray_step > 0, downsampling_factor > 0 and at least 2 rays per axis.

virtual bool getVisibleVoxels(VoxelOccupancyMap *result, const Transform3d &sensor_transform) override

Returns visible voxels using adaptive ray splitting.

Parameters:

• result – Output map of voxel positions to occupancy states.

• sensor_transform – Sensor transform in world frame.

Returns:

true on success.

IterativeRayCasterLidar(AgentInterface &agent)

Constructs the IterativeRayCasterLidar and binds it to the agent.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads ray step, downsampling, and split distances.

virtual ~IterativeRayCasterLidar() = default

class SimpleRayCaster : public open_apero::sensor_model::CameraModel

#include <open_apero_core/plugin/sensor_model/simple_ray_caster.h>

Casts one ray per voxel at the observation boundary.

Public Functions

virtual bool checkParamsValid(std::string *error_message) override

Validates the camera, ray_step > 0, downsampling_factor > 0 and at least 2 rays per axis.

virtual bool getVisibleVoxels(VoxelOccupancyMap *result, const Transform3d &sensor_transform) override

Casts one ray per voxel column at max-distance resolution and collects visible voxels.

Parameters:

• result – Output map of voxel positions to occupancy states.

• sensor_transform – Sensor transform in world frame.

Returns:

true on success.

virtual void setupFromParamMap(Configurable::ParamMap *param_map) override

Loads SimpleRayCaster parameters (ray step, downsampling factor) from the config map.

explicit SimpleRayCaster(AgentInterface &agent)

Constructs the SimpleRayCaster and binds it to the agent.

virtual ~SimpleRayCaster() = default