Parameters

GBPlanner Parameters

Compile Time Parameters

Verbosity

There are five levels of verbosity in the code:

SILENT
ERROR
WARN
INFO
DEBUG

Two separate variables control the verbosity level for planner related verbosity and parameter loading related verbosity.

Behavior Tree Parameters

• behavior_tree_path: Path to the file containing the behavior tree for the mission

In each of the demo folder inside config/\<robot_type\>/\<simlator_type\>/, a main_tree.xml file is provided. This includes a list of configured behaviors for exploration and inspection:

• lge_homing.xml: Robot will perform volumetric exploration operating in local exploration mode until the local exploration is exhausted. At this point, the robot will switch to the global repositioning mode to go to one of the unexplored frontiers and continue local exploration. If no frontiers exist in the map or the mission time set by the parameter PlanningParams/time_budget_limit (Details about the parameters are provided in the sections below). The exploration will take place inside the volume defined by BoundedSpaceParams/Global.
• lge_insp: Robot will perform volumetric exploration operating in local exploration mode until the local exploration is exhausted. At this point, the robot will switch to the global repositioning mode to go to one of the unexplored frontiers and continue local exploration. If no frontier exists, the robot will switch to the inspection mode and calculate a path to inspect all mapped surfaces inside BoundedSpaceParams/Global.

All the following parameters are set in config/\<robot_type\>/\<simlator_type\>/\<mission_name\>/gbplanner_config.yaml

Graph Building Parameters

• PlanningParams/graph_building_mode: Maximum allowed vertices in the graph.

	kBasic,  // Use basic sampling scheme. (default)
	kBatch   // Use batch sampling scheme.

• PlanningParams/num_vertices_max: Maximum allowed vertices in the graph.
• PlanningParams/num_edges_max: Maximum allowed edges in the graph.
• PlanningParams/num_loops_cutoff: Maximum number of times the planner will try to build the graph when it is not able to add any vertex in the graph.
• PlanningParams/num_loops_max: Graph building will terminate after these many loop iterations if the num_vertices_max or num_vertices_max is not reached.
• PlanningParams/edge_length_min: Minimum edge length in the graph.
• PlanningParams/edge_length_max: Maximum edge length in the graph.
• PlanningParams/edge_length_min: Estimated overshoot along an edge that can be caused by inaccurate path tracking.
• PlanningParams/nearest_range: A vertex is connected to other vertices in the graph in this range after collision checking.
• PlanningParams/geofence_checking_enable: Use geofence zones.
• PlanningParams/box_check_method: Method used to do collision checking for a point. Default = 0
  • 0: (Default) The cuboid set as the robot's shape (see "Robot Geomerty Related Parameters" section for more details) is divided into voxels and the occupancy of each voxel is checked. If all the voxels lie in free space, the robot is said to be in free space.
  • 1: Approximates the robot as a sphere with radius equal to half of the largest diagonal of the cuboid set as the robot's shape. The T/ESDF distance of the center of the robot is found from the Voxblox sdf layer. If this distance is less than the radius of the robot as calculated above, the robot is said to be in collision.
    This is a very fast collision checking method, however, the spherical approximation is not ideal for robots with larger deviation from spherical shape.
  • 2: The cuboid set as the robot's shape is divided into a grid (larger than voxel size) and the T/ESDF distance of each grid center is checked. If this distance is less than the grid resolution the robot box is not in free space. Note that unlike the first method (PlanningParams/box_check_method=0) in which each point to check is snapped to the closest voxel in the Voxblox grid, this method can check the T/ESDF distance of any point in the space.
• PlanningParams/line_check_method: Method used to do collision checking for a straight line. Default = 0
  • 0: The line to check is interpolated and each point is checked for collision using the method described for PlanningParams/box_check_method=0.
  • 1: (Default) Builds a trapezoid which will be generated by the vertical cross section of the robot around the line segment. The surfaces of this cuboid are checked for occupancy by checking each voxel on the surface.
  • 2: The line to check is interpolated and each point is checked for collision using the method described for PlanningParams/box_check_method=1.
  • 3: Builds a trapezoid which will be generated by the vertical cross section of the robot around the line segment. The surfaces of this cuboid are checked for collision by dividing the surface into a grid and checking each point on the grid similar to the method in PlanningParams/box_check_method=2.

Ground Robot Specific Parameters

• PlanningParams/max_ground_height: All vertices in the graph will be projected such that their height from the ground is equal to this value.
• PlanningParams/robot_height: Height of robot's odometry frame from the ground.
• PlanningParams/max_inclination: Maximum inclination of ground the robot can traverse on.

Robot Geomerty Related Parameters

• RobotParams/type: Type of robot. Options: kAerialRobot, kGroundRobot
• RobotParams/size: Actual size of the robot in meters [length(x), width(y), height(z)]
• RobotParams/size_extension_min: Minimum extension around the robot size used for collision checking [length(x), width(y), height(z)]
• RobotParams/size_extension: Extension around the robot size used by default. Must be larger than of equal to size_extension_min [length(x), width(y), height(z)]
• RobotParams/center_offset: Offset from the cuboid center to odometry frame [x,y,z]
• RobotParams/relax_ratio: Ratio to compute relaxed extension. relaxed_extension = relax_ratio * size_extension_min + (1-relax_ratio) * size_extension
• RobotParams/bound_mode: Bound mode to use by default. This decides which size extension is to be used. Possible values:

   kExtendedBound = 0,  // Use extension to actual size. (default)
   kRelaxedBound = 1,   // Use relaxed extension.
   kMinBound = 2,       // Use minimum bound allowed.
   kExactBound = 3,     // Use its exact size.
   kNoBound = 4,        // Consider a robot as a point.
  

• RobotParams/safety_extension: Dimensions of the freespace corridor used to improve the planned path for safety

Exploration Bounds

• BoundedSpaceParams/Global/type: Type of bound space. Options: kCuboid, kSphere
• BoundedSpaceParams/Global/min_val: Lower bound of the space [x,y,z] (Only for kCuboid type)
• BoundedSpaceParams/Global/max_val: Upper bound of the space [x,y,z] (Only for kCuboid type)
• BoundedSpaceParams/Global/radius: Radius of the spherial bound in meters (Only for kSphere type)

Sampling Parameters for Building the Graph

• PlanningParams/type: Type of sampling space to be used. Options:
  kAdaptiveExploration: Sampling space adjusted based on the geomerty of the surrounding environment
  kBasicExploration: Fixed size cuboid used for sampling

Sampling space:

• Local Space (Used when type = kBasicExploration):
  • BoundedSpaceParams/Local/type: Type of sampling space. Options: kCuboid, kSphere
  • BoundedSpaceParams/Local/min_val: Lower bound of the space [x,y,z] (Only for kCuboid type)
  • BoundedSpaceParams/Local/max_val: Upper bound of the space [x,y,z] (Only for kCuboid type)
• Local Adaptive Space (Used when type = kAdaptiveExploration)
  • BoundedSpaceParams/LocalAdaptiveExp/type: Type of sampling space. Options: kCuboid, kSphere (kSphere not supported for adaptive sampling)
  • BoundedSpaceParams/LocalAdaptiveExp/min_val: Lower bound of the minimum sampling space [x,y,z] (Only for kCuboid type)
  • BoundedSpaceParams/LocalAdaptiveExp/max_val: Upper bound of the minimum sampling space [x,y,z] (Only for kCuboid type)
  • Parameters for calculating the sampling space:
    • AdaptiveObbParams/type: Type of algorithm. Currently supported algorithm: kPca
    • AdaptiveObbParams/local_pointcloud_range: Size of the map around the robot to be used for calculating the sampling space
    • AdaptiveObbParams/bounding_box_size_max: Maximum size of the sampling space in any dimension

Random Sampler:

• kBasicExploration:
  • RandomSamplerParams/SamplerForExploration/x/pdf_type: Type of probability distribution to be used. Options:

     kConst,    // Constant value.
     kUniform,  // Uniformly sample, have to define a bound.
     kNormal,   // Normally sample, have to define the mean and std. 
    

  • RandomSamplerParams/SamplerForExploration/x/sample_mode: Set sampling space. Options:

     kManual,	// Parse params manually from the setting in yaml file.
     kLocal,		// Get from locally bounded space automatically. (Only in kUniform)
     kGlobal,	// Get from globally bounded space automatically.(Only in kUniform)
     kIgnore		// No sampling, return a const value 0.0.
    

    Same set of parameters exist for sampling in y, z, heading, and pitch
• kAdaptiveExploration:
  • RandomSamplerParams/SamplerForAdaptiveExp/x/pdf_type: Type of probability distribution to be used. Options:

     kConst,    // Constant value.
     kUniform,  // Uniformly sample, have to define a bound.
     kNormal,   // Normally sample, have to define the mean and std. 
    

  • RandomSamplerParams/SamplerForAdaptiveExp/x/sample_mode: Set sampling space. Options:

     kManual,	// Parse params manually from the setting in yaml file.
     kLocal,		// Get from locally bounded space automatically. (Only in kUniform)
     kGlobal,	// Get from globally bounded space automatically.(Only in kUniform)
     kIgnore		// No sampling, return a const value 0.0.
    

    Same set of parameters exist for sampling in y, z, and heading

Sensor Model Parameters

• SensorParams/sensor_list: List of names (string) of sensor models to be used for gain calculation. For each sensor in this list a sensor model needs to be created with the following parameters:
  • SensorParams/<sensor_name>/type: Type of sensor. Options: kLidar, kCamera
  • SensorParams/<sensor_name>/max_range: Max range of the sensor in meters.
  • SensorParams/<sensor_name>/rot_lims: The rotation limits for an actuated camera [min_val, max_val]. Range for each value: [-1.5, 1.5]
  • SensorParams/<sensor_name>/center_offset: Offset of the sensor base frame from robot's odometry frame [x,y,z]
  • SensorParams/<sensor_name>/rotations: Rotation of the sensor frame relative to robot's odomerty frame [roll, pitch, yaw]
  • SensorParams/<sensor_name>/fov: Field of view of the robot in radians [F_horizontal, F_vertical]
  • SensorParams/<sensor_name>/resolution: Angular resolution used for raycasting [res_horizontal, res_vertical]
  • SensorParams/<sensor_name>/frontier_percentage_threshold: Fraction of maximum possible volumetric gain for this sensor to classify a vertex as a frontier

Parameters for Exploration Gain Calculation

• PlanningParams/exp_sensor_list: List of names sensor models to be used for volumetric gain calculation. All names in this list must be in SensorParams/sensor_list and a model for each should exist as described in the Sensor Model Parameters section.
• PlanningParams/no_gain_zones_list: List of names of no gain zones. The voxels lying in these volumes are not used for gain calculation. Each zone should be defined as bellow:
  • NoGainZones/<zone_name>/type: Supported option: kCuboid
  • NoGainZones/<zone_name>/min_val: Lower bound of the zone [x,y,z]
  • NoGainZones/<zone_name>/max_val: Upper bound of the zone [x,y,z]
• PlanningParams/free_voxel_gain: Weight for the number of free voxels seen by the sensor term in volumetric gain calculation.
• PlanningParams/occupied_voxel_gain: Weight for the number of occupied voxels seen by the sensor term in volumetric gain calculation.
• PlanningParams/unknown_voxel_gain: Weight for the number of unknown voxels seen by the sensor term in volumetric gain calculation.
• PlanningParams/path_length_penalty: Weight for the path length penalty term in the exploration gain formulation.
• PlanningParams/path_direction_penalty: Weight for the path direction penalty term in the exploration gain formulation.
• PlanningParams/hanging_vertex_penalty: Weight for the penalty for the volumetric gain of a hanging vertex.
• PlanningParams/leafs_only_for_volumetric_gain: If the volumetric gain is to be evaluated for the leaf vertices only.
• PlanningParams/cluster_vertices_for_gain: If the vertices in the graph are to be clustered for volumetric gain calculatin.
• PlanningParams/clustering_radius: Radius to use for clustering. Not used if PlanningParams/cluster_vertices_for_gain is false.
• PlanningParams/nonuniform_ray_cast: If the step size in the ray cast should be increased after every few steps.
• PlanningParams/ray_cast_step_size_multiplier: Base step size in the ray cast.

Parameters for Extracting the Best Path

• PlanningParams/traverse_length_max: Maximum length of the path to be commanded.
• PlanningParams/traverse_time_max: Maximum allowed time to execute the path. If the estimated time to execute the path exceeds this time limit, the path will be truncated to fall within the limit.
• PlanningParams/planning_backward: If the path is to be executed backwards.
• PlanningParams/path_safety_enhance_enable: If the best path is to be improved for safety.
• PlanningParams/path_interpolation_distance: Final commanded path will be interpolated with this step size.

Parameters for Global Planner

• PlanningParams/relaxed_corridor_multiplier: The size of the freespace corridor used for path improvement will be changed by this factor in global planning step. Keep it 1.0 if the same size is to be used.
• PlanningParams/auto_global_planner_enable: If true, global planner will be trigered when no significant volumetric gain is found for any vertex in the graph for fixed number of consecutive planning iterations.
• PlanningParams/go_home_if_fully_explored: If true: if global planner is triggered and no frontier vertex exists in the global graph, then the planner will command the robot to return to the home location. Works only when PlanningParams/auto_global_planner_enable is true.
• PlanningParams/auto_homing_enable: If homing should be triggered to return to home location within the PlanningParams/time_budget_limit. Default is true.
• PlanningParams/time_budget_limit: Mission time limit.
• PlanningParams/auto_landing_enable: If the robot should land after PlanningParams/time_budget_before_landing seconds. Only works for RobotParams/type = kAerialRobot. If set to true, PlanningParams/go_home_if_fully_explored and PlanningParams/auto_homing_enable will be disabled.
• PlanningParams/time_budget_before_landing: Time after which landing will be engaged if PlanningParams/auto_landing_enable is true.
• PlanningParams/homing_backward: If the homing path is to be executed backwards.

Geofence Related Parameters

Note: The geofence zones are currently 2D

• Geofenceparams/AreaList: List of names of geofence zones. For each name in this list, a geofence model should be defined with the following parameters:
  • Geofenceparams/<zone_name>/center: Center point of the geofence [x,y,z] (The z does not matter as the zone is 2D).
  • Geofenceparams/<zone_name>/size: Dimensions of the rectangular zone centered around the Geofenceparams/<zone_name>/center [x,y,z] (The z does not matter as the zone is 2D).

Inspection Related Parameters

• PlanningParams/min_coverage_percentage: The planner selects viewpoints until this fraction of the mapped surface is covered by the viewpoints selected so far.
• PlanningParams/inspection_xy_spacing: Resolution along the x,y axes for generating the grid of inspection viewpoints.
• PlanningParams/inspection_z_spacing: Resolution along the z axis for generating the grid of inspection viewpoints.
• PlanningParams/inspection_thr_esdf_dist: After building the grid of viewpoints, only those having their T/ESDF distance less than this parameter are retained.
• PlanningParams/inspection_target_viewing_range: Distance to which the inspection viewpoints are projected to.
• PlanningParams/inspection_graph_vertices: Maximum vertices in the graph sampled to build the inspection graph.
• PlanningParams/max_inspection_vertices: Maximum viewpoints in the inspection path.
• PlanningParams/num_lkh_iterations: Maximum number of iterations of the TSP solver.

Mapping Parameters

Selecting TSDF vs ESDF:
The default method used is TSDF. To enable ESDF comment the use_tsdf parameter here.

Other parameters (set in config/<robot_type>/<simulator_type><mission_name>/voxblox_config.yaml):

• world_frame: Fixed frame used by the planner.
• tsdf_voxel_size: Voxel size used for mapping. Even if ESDF is used, the same parameter sets the voxel size.
• truncation_distance: Truncation distance for TSDF. Set to 2-5 times the voxel size.
• max_ray_length_m: Maximum distance upto which the ray casting should be done.
• update_mesh_every_n_sec: Time interval at which voxblox will generate the mesh. Setting this to 0 will disable mesh building (reducing the computational overhead of this process). However, this will also disable occupancy map visualization.

Planner Control Interface Parameters

Compile Time Parameters

Verbosity

Similar to GBPlanner, there are five levels of verbosity in the code:

SILENT
ERROR
WARN
INFO
DEBUG

Two separate variables control the verbosity level for planner related verbosity and parameter loading related verbosity.

Run Time Parameters:

These parameters are set in config/<robot_type>/<simulator_type><mission_name>/planner_control_interface_sim_config.yaml

• run_mode: If the planner is running on simulation or real robot. Options: kSim, kReal.
• trigger_mode: If the planner will be triggered manually or automatically at the beginning of the mission. Options: kManual, kAuto
• robot_type: Aerial or ground robot. Options: kAerial, kGround
• init_motion_enable: If the robot should perform initialization motion upon starting the node.
• planner_trigger_lead_time: If > 0, the planner will calculate the next path from the end pose of the current path; else, it will be calculated from the current robot pose.
• smooth_heading_enable: If the commanded change in heading along a path segment should not exceed the achievable change within the translation time along that segment. Otherwise, the allotted heading will be tangent to the path segments.
• path_end_dist_thr, path_end_yaw_thr, path_progression_pitch_thr: The next planning iteration is triggered when the robot's distance from the end of the path is <= path_end_dist_thr, the difference between end point yaw and robot yaw is <= path_end_yaw_thr, and difference between end point camera pitch and robot's camera pitch is <= path_progression_pitch_thr.
• Path progression parameters: The PCI keeps track of the waypoint (called carrot waypoint) in the path at a horizon from the current robot state. This carrot waypoint is incremented when the robot reaches within a threshold position, yaw, and pitch range of the current carrot waypoint. These ranges are defined by the following parameters:
  • path_progression_dist_thr, path_progression_dist_thr_min: Based on the angle between the lines from the current robot position to the carrot waypoint and the carrot waypoint to the next waypoint in the path, the position range is updated. It is set to be proportional to this angle such that the range is path_progression_dist_thr for angle 0 and path_progression_dist_thr_min for angle >= pi/2.
  • path_progression_yaw_thr, path_progression_yaw_thr_min: Similar to the position range, the yaw range is set to path_progression_yaw_thr if sign(carrot yaw - current yaw) == sign(next waypoint yaw - carrot yaw). Otherwise, it is set to path_progression_yaw_thr_min.
  • 'path_progression_pitch_thr`: Carrot waypoint reaching range for camera pitch. Note: this check is not for the robot's pitch but the sensor's pitch.
• interpolate_traj: If true, interpolates the trajectory in time by the parameter RobotDynamics/dt.
• reconnect_path: If true, attaches the remaining part of the current path to the next path.
• pub_singple_wp: If true, only the carrot waypoint (described above) is published on the topic /gbplanner_path. Otherwise, the entire path is published.
• init_motion/z_takeoff: Height from the current z to which the robot should takeoff to during the initialization motion. Only for robot_type = kAerial.
• init_motion/z_drop: Distance to go down from the takeoff height during the initialization motion. Only for robot_type = kAerial.
• init_motion/x_forward: Distance to move forward in x direction (of the fixed frame) after the above two initialization motion steps.
• RobotDynamics/v_max: Maximum commanded linear velocity. (m/s)
• RobotDynamics/v_init_max: Maximum commanded linear velocity during initialization motion. (m/s)
• RobotDynamics/v_homing_max: Maximum commanded linear velocity during homing. (m/s)
• RobotDynamics/yaw_rate_max: Maximum commanded yaw rate. (m/s)
• RobotDynamics/dt: Time step used for interpolating the trajectory. (rad/s)
• RobotDynamics/a_max: Acceleration used to create a trapezoidal velocity profile.