Parameters

GBPlanner Parameters

Compile Time Parameters

There are three parameters than need to be set at compile time in the CMakeLists.txt of the planner_common package.

1. COL_CHECK_METHOD: Selects the method used to check if the robot will be in free space at a sampled point in space. Possible values:
   • 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 (COL_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.
2. EDGE_CHECK_METHOD: Selects the method used to check if a straight line segment connecting two points is collision free. Possible values:
   • 0: The line to check is interpolated and each point is checked for collision using the method described for COL_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 COL_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 COL_CHECK_METHOD=2.
3. RAY_CAST_METHOD: Selects the method used for ray casting which is used to calculate the volumetric gain of a robot state. Possible values:
   • 0: Regular ray casting. Each ray starts from the robot state and goes upto the max range unless it encounters an occupied voxel.
   • 1: (Default) Iterative ray casting. Each subsequent ray in the scan starts from a point such that it does not check the voxels checked by previous rays. This methods speeds up the ray casting process by upto 2x for high ray casting reslution.

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.

All the following parameters are set in config/<robot_name>/gbplanner_config.yaml

Graph Building Parameters

• 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.

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, and heading
• 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>/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).

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_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_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
• output_type: Mode of output, topic of action. Options: kAction, kTopic
• init_motion_enable: If the robot should perform initialization motion upon starting the node.
• planner_trigger_lead_time: Next planning iteration will be triggered these many seconds before completion of the current path.
• 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 alloted heading will be tangent to the path segments.
• 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 calculating the trajectory. (rad/s)