Skip to main content
Version: 0.11.0

Collision Avoidance

SAFETY WARNING

Making changes to any of the following variables may decrease system safety. It is recommended that users only modify these parameters in consultation with Clearpath Robotics Support.

note

Changes to any of the following variables will only take effect after power cycling the UGV.

The collision avoidance feature of OutdoorNav allows our platforms to detect, replan and then navigate around any obstacles that may be present in the UGV's path. The workflow of this feature can be seen in the figure below.

Collision avoidance workflow

The detection sensors available on the UGV will have their data filtered, if necessary into data that can be fed into the costmap(s). The costmap will then use this filtered data to generate two costmaps (local and global).

  • global costmap: A large costmap (whose size gets set relative to the Waypoints of the desired mission) the replanned paths around detected obstacles.
  • local costmap: A smaller costmap that is used solely for detecting potential collisions and triggering the path replanner.

Therefore, there are two components in which we can tune the behaviour of the collision avoidance feature: the sensor filters or the costmap generation. We will expand on these below.

Sensor Tuning

The following table lists the sensors that are useable with the OutdoorNav software. The sensor drivers can be turned on/off using these environment variables, however, the sensor will always remain powered on. The environment variables, should be added to the /opt/onav/<onav_version>/config/sensors.env file, where onav_version is the currently running version of OutdoorNav.

Environment VariableDescriptionData Type
SWIFTNAV_ENABLE_DRIVEREnable/disable the Swiftnav Piksi/Duro ROS driver, if integrated.bool
UBLOX_ENABLE_DRIVEREnable/disable the UBlox ROS driver, if integrated.bool
MICROSTRAIN_ENABLE_DRIVEREnable/disable the Microstrain GX5/CV5 ROS driver, if integrated.bool
XSENS_ENABLE_DRIVEREnable/disable the XSens MTI ROS driver, if integrated.bool
VLP_ENABLE_DRIVEREnable/disable the Velodyne ROS driver, if integrated (front unit if more than one).bool
REAR_VLP_ENABLE_DRIVEREnable/disable the Velodyne ROS driver, if integrated (rear unit if more than one).bool
LMS1XX_ENABLE_DRIVEREnable/disbale the Sick LMS1XX ROS driver, if integrated (front unit if more than one).bool
REAR_LMS1XX_ENABLE_DRIVEREnable/disbale the Sick LMS1XX ROS driver, if integrated (rear unit if more than one).bool
HOKUYO_ENABLE_DRIVEREnable/disbale the Hokuyo ROS driver, if integrated (front unit if more than one).bool
REAR_HOKUYO_ENABLE_DRIVEREnable/disbale the Hokuyo ROS driver, if integrated (rear unit if more than one).bool
D435_ENABLE_DRIVEREnable/disable the Realsense ROS driver, if integrated (front unit if more than one).bool
REAR_D435_ENABLE_DRIVEREnable/disable the Realsense ROS driver, if integrated (rear unit if more than one).bool

Sensor Filters

info

It is currently only possible to use one filter of the 3D LiDAR filters (voxel, cropbox, radius, or statistical outlier) at a time on any source of data. In future releases we plan on expanding this to work as a filter chain.

The following list of environment variables can be used to filter the sensor data in order to modify/improve the sensory input to the OutdoorNav autonomy. It is recommended that you first consult the following links before attempting to modify these parameters.

Voxel Grid Filter

Applicable for 3D LiDAR data published on the ../pointcloud topic.

Eg. Velodyne, Ouster or Realsense PointCloud2 data.

Environment VariableDescriptionData Type (Default)
<type>_ENABLE_FILTER_VOXELEnable/disable the PCL voxel filter for the sensor of type <type>.

type = {VLP, D435, REAR_VLP, REAR_D435}
bool
(false)
PCL_FIL_FILTER_VOXEL_LEAF_SIZEThe size of a leaf (on x,y,z), in meters, used for downsampling. Range: 0.0 to 1.0.double (0.01)

Cropbox Filter

Applicable for 3D LiDAR data published on the ../pointcloud topic.

Eg. Velodyne, Ouster or Realsense PointCloud2 data.

Environment VariableDescriptionData Type (Default)
<type>_ENABLE_FILTER_CROPBOXEnable/disable the PCL cropbox filter for the sensor of type <type>.

type = {VLP, D435, REAR_VLP, REAR_D435}
bool
(false)
PCL_FILTER_CROPBOX_MIN_XThe lower bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0.double
(0.01)
PCL_FILTER_CROPBOX_MAX_XThe upper bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0.double
(2.0)
PCL_FILTER_CROPBOX_MIN_YThe lower bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0.double
(-10.0)
PCL_FILTER_CROPBOX_MAX_YThe upper bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0.double
(10.0)
PCL_FILTER_CROPBOX_MIN_ZThe lower bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0.double
(-0.5)
PCL_FILTER_CROPBOX_MAX_ZThe upper bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0.double
(10.0)

Radius Outlier Filter

Applicable for 3D LiDAR data published on the ../pointcloud topic.

Eg. Velodyne, Ouster or Realsense PointCloud2 data.

Environment VariableDescriptionData Type (Default)
<type>_ENABLE_FILTER_RADIUS_OUTLIEREnable/disable the PCL radius outlier filter for the sensor of type <type>.

type = {VLP, D435, REAR_VLP, REAR_D435}
bool
(false)
PCL_FILTER_ROR_RADIUS_SEARCHThe number of points within this distance, in meters, from the query point will need to be equal or greater than PCL_FILTER_ROR_MIN_NEIGHBORS in order to be classified as an inlier point (i.e. will not be filtered).double
(0.05)
PCL_FILTER_ROR_MIN_NEIGHBORSThe number of points within PCL_FILTER_ROR_RADIUS_SEARCH from the query point will need to be equal or greater than this number in order to be classified as an inlier point (i.e. will not be filtered).int
(10)

Statistical Outlier Filter

Applicable for 3D LiDAR data published on the ../pointcloud topic.

Eg. Velodyne, Ouster or Realsense PointCloud2 data.

Environment VariableDescriptionData Type (Default)
<type>_ENABLE_FILTER_STATISTICAL_OUTLIEREnable/disable the PCL statistical outlier filter for the sensor of type <type>.

type = {VLP, D435, REAR_VLP, REAR_D435}
bool
(false)
PCL_FILTER_SOR_MEAN_KThe number of points (k) to use for mean distance estimation Range: 2 to 100.double
(5.0)
PCL_FILTER_SOR_STD_DEVThe standard deviation multiplier threshold. All points outside the mean +- sigma * std_mul will be considered outliers. Range: 0.0 to 5.0.double
(0.3)

PointCloud to LaserScan Filter

The following filter is enabled by default and is applied after any 3D LiDAR filtering has occured. It projects the final pointcloud topic onto the 2D plane that is then used to generate the costmap.

Environment VariableDescriptionData Type (Default)
<type>_ENABLE_POINTCLOUD_TO_LASERSCANEnable/disable the pointcloud to laserscan outlier filter for the sensor of type <type>.

type = {VLP, D435, REAR_VLP, REAR_D435}
bool
(false)
PCL_TO_SCAN_MIN_HEIGHTThe minimum height to sample in the point cloud, in meters.double
(0.2)
PCL_TO_SCAN_MAX_HEIGHTThe maximum height to sample in the point cloud, in meters.double
(1.2)
PCL_TO_SCAN_MIN_ANGLEThe minimum scan angle, in radians.double
(3.14)
PCL_TO_SCAN_MAX_ANGLEThe maximum scan angle, in radians.double
(3.14)
PCL_TO_SCAN_ANGLE_INCREMENTResolution of laser scan, in radians, per ray.double
(0.00218)
PCL_TO_SCAN_TIMEThe scan rate in seconds.double
(0.3333)
PCL_TO_SCAN_MIN_RANGEThe minimum ranges to return, in meters.double
(0.3)
PCL_TO_SCAN_MAX_RANGEThe maximum ranges to return, in meters.double
(100.0)

DepthImage to LaserScan Filter

Applicable for depth image data published on the ../depth/image_rect_raw topic.

Eg. Realsense DepthImage data.

Environment VariableDescriptionData Type (Default)
<type>_ENABLE_DEPTH_TO_LASERSCANEnable/disable the depth image to laserscan outlier filter for the sensor of type <type>.

type = {D435, REAR_D435}
bool
(false)
DEPTH_TO_SCAN_HEIGHTThe number of pixel rows to use to generate the laserscan. For each column, the scan will return the minimum value for those pixels centered vertically in the image.int
DEPTH_TO_SCAN_TIMETime between scans (seconds). Typically, 1.0/frame_rate. This value is not easily calculated from consecutive messages, and is thus left to the user to set correctly.double
DEPTH_TO_SCAN_MIN_RANGEThe minimum ranges to return in meters. Ranges less than this will be output as -Inf.double
DEPTH_TO_SCAN_MAX_RANGEThe maximum ranges to return in meters. Ranges greater than this will be output as +Inf.double

Costmap Tuning

The following section provides a list of environment variables that can be modified in order to tune OutdoorNav. All of the environment variables listed below can be modified in the /opt/onav/<onav_version>/config/autonomy.env file, where onav_version is the currently running version of OutdoorNav.

Costmap Inputs

The following table lists the environment variables that can be used to enable/disable which sensor is used as part of the collision avoidance feature of OutdoorNav.

Environment VariableDescriptionData Type
VLP_ENABLE_COSTMAPEnable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one).bool
REAR_VLP_ENABLE_COSTMAPEnable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one).bool
LMS1XX_ENABLE_COSTMAPEnable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one).bool
REAR_LMS1XX_ENABLE_COSTMAPEnable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one).bool
HOKUYO_ENABLE_COSTMAPEnable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one).bool
REAR_HOKUYO_ENABLE_COSTMAPEnable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one).bool
D435_ENABLE_COSTMAPEnable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one).bool
REAR_D435_ENABLE_COSTMAPEnable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one).bool

Costmap Generation

The following list of environment variables can be used to modify some of the navigation inputs of to the OutdoorNav autonomy. It is recommended that you first consult the following link(s) before attempting to modify these parameters.

Environment VariableDescriptionData Type
COSTMAP_LIDAR_<2D/3D>_OBSTACLE_RANGEThe maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one).double
COSTMAP_LIDAR_<2D/3D>_RAYTRACE_RANGEThe maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one).double
COSTMAP_REAR_LIDAR_<2D/3D>_OBSTACLE_RANGEThe maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (rear unit if more than one).double
COSTMAP_REAR_LIDAR_<2D/3D>_RAYTRACE_RANGEThe maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one).double

Limitations

The collision avoidance feature as it currently stands, does come with some limitations. These are listed listed below:

Detection range limits

The maximum collision avoidance range for the OutdoorNav Software is UGV-dependent and is related to the maximum speed of the UGV. These ranges for Clearpath Robotics UGVs are:

  • Jackal UGV: 4.5 meters
  • Husky UGV: 4.5 meters
  • Warthog UGV: 15.0 meters

While the sensors are able to detect objects at further distances, the OutdoorNav Software only considers obstacles detected within these distances for collision avoidance. That is, the UGV will only begin to decelerate as it detects obstacles within this range.

The detection itself is also related to the horizontal size (width/diameter) of the obstacle. The limitations in detecting objects with small horizontal size are described in the table below.

Maximum Reliable Obstacle Detection Distance from UGV, according to Obstacle Horizontal Size

Object Size (Horizontal)Starter Sensor KitStandard/(CUstom w/ VLP) Sensor Kit
Less than 0.6 cmNo reliable detectionNo reliable detection
0.6 to 1.0 cm0.8 mNo reliable detection
1.0 to 3.0 cm2.0 m1.75 m
Greater than 3.0 cmMaximum collision avoidance distance (UGV-specific; see above)Maximum collision avoidance distance (UGV-specific; see above)

Finally, the OutdoorNav Software bounds the obstacle detection to prevent ground hits and to remove detections above the UGV body. The following bounds are relative to the ground, assuming a flat surface. Obstacles that are entirely below the lower bound or entirely above the upper bound are not considered obstacles and will not be avoided.

Obstacle Detection Vertical Bounds

Vertical BoundJackal UGVHusky UGVWarthog UGV
Lower Detection Bound0.3 m0.3 m0.3 m
Upper Detection Bound0.8 m1.3 m1.8 m
note

The vertical detection bounds above are for the Standard Sensor Kit or a custom sensor configuration that includes a Velodyne. The vertical detection bounds for the Starter Sensor Kit have yet to be determined.

Tall grass

Description: Grass that is taller than 15cm may occasionally be detected as the robot is driving.

Workaround Available?: Yes (Mitigation)

Mitigating Solution: There are a couple of ways to reduce the amount of detections of long blades of grass.

1) Apply either a radial filter or a statistical outlier filter on the pointcloud data to filter out the stray detections.

  • File: /opt/onav/<onav_version>/config/sensors.env
  • Environment variable(s): <sensor_type>_ENABLE_FILTER_RADIUS_OUTLIER, <sensor_type>_ENABLE_FILTER_STATISTICAL_OUTLIER

2) Increase the pointcloud to laserscan conversion filter minimum height parameter. The environment variable

  • File: /opt/onav/<onav_version>/config/sensors.env
  • Environment variable(s): PCL_TO_SCAN_MIN_HEIGHT

Pitch changes

Description: Pitch changes along the UGVs planned path may cause the ground to be detected and unwanted replanning may occur. This occurs because since we do not track change in pitch of the robot, and since we filter the sensor data such that essentially chop off the lower portion of the data. With the change in pitch this lower plane will then cause ground detections.

Workaround Available?: Yes (Mitigation)

Mitigating Solution: Limit the range from the base_link that the costmap generates lethal obstacles, for a specific sensor. Eg. If your UGV has both a 3D and a 2D LiDAR. We want to limit the range at which the 2D LiDAR will generate obstacles since the 3D LiDAR will cover a majority of the detections. You would be able to reduce the range that the 2D LiDAR generates obstacles, so that it does not overlap with the detection field of the 3D LiDAR.

  • File: /opt/onav/<onav_version>/config/autonomy.env
  • Environment variable(s): COSTMAP_LIDAR_2D_OBSTACLE_RANGE and/or COSTMAP_REAR_LIDAR_2D_OBSTACLE_RANGE

Branches across narrow path

Description: If there are overhanging branches across a path (ie. not coming from the ground), the navigation may not be able to maneuver through them.

Workaround Available?: Limited to None

Mitigating Solution: Reduction of the global costmap inflation_radius and/or costmap_scaling_factor parameters may provide sufficient space for the navigation to replan though the branches.

  • File: /opt/onav/<onav_version>/app/autonomy/params/<platform>/navigation/costmap_global.yaml
  • Environment variable(s): /navigation/global_costmap/inflation/inflation_radius and/or /navigation/global_costmap/inflation/cost_scaling_factor
info

See the bottom of this page for information on how the costmap inflation layer costs are computed based on the above two parameters.

Reflective surfaces

Description: Reflective surfaces on or around the robot can cause false positive obstacle placement at incorrect locations on the costmap.

Workaround Available?: No software workaround available.

Mitigating Solution: Remove/cover/re-position all reflective surfaces on the robot.