Collision Detector Node

The Collision Detector is a node similar to the Collision Monitor, so it is recommended to read the Using Collision Monitor tutorial first.

In some cases, the user may want to be informed about the detected obstacles without affecting the robot’s velocity and instead take a different action within an external node. For example, the user may want to blink LEDs or sound an alarm when the robot is close to an obstacle. Another use case could be to detect data points in particular regions (e.g extremely close to the sensor) and warn of malfunctioning sensors. For this purpose, the Collision Detector node was introduced. It works similarly to the Collision Monitor, but does not affect the robot’s velocity. It will only inform that data from the configured sources has been detected within the configured polygons via message to the collision_detector_state topic.

See the package’s README for more information.

Features

Similarly to the Collision Monitor, the Collision Detector uses robot’s relative polygons to define “zones”. However, unlike the Collision Monitor that uses different behavior models, the Collision Detector does not use any of them and therefore the action_type should always be set to none. If set to anything else, it will throw an error

The zones around the robot and the data sources are the same as for the Collision Monitor, with the exception of the footprint polygon, which is not supported by the Collision Detector.

Any data source can optionally define one or more exclusion zones. An exclusion zone is a region that removes (masks out) that source’s points which fall inside it, before the detector polygons are evaluated. Unlike the polygons above, an exclusion zone does not trigger detection, it is a per-source pre-filter. A typical use case is ignoring known structure the robot deliberately approaches, such as a charging dock or a conveyor, whose returns would otherwise trip the detection zones. Another common use case is self-filtering: masking out returns from parts of the robot itself (e.g. arms, mast, bumpers, or trailers) that fall within a sensor’s field of view, which would otherwise be mistaken for obstacles. Anchoring the zone to the relevant robot frame keeps the mask aligned with that structure as it moves. A zone can be a polygon or circle anchored to an arbitrary frame_id (e.g. dock_link), so it tracks that frame as the robot moves, with an optional height band for 3D sources. The filter is fail-safe: if the zone transform is unavailable, no points are removed. Each zone inherits its owning source’s base_shift_correction policy, so the mask and the source points are always transformed under the same assumptions. See YAML at the bottom for an example.

Parameters

frequency

Type	Default
double	10.0

Description:

Frequency of the main loop that checks for detections.

base_frame_id

Type	Default
string	“base_footprint”

Description:

Robot base frame.

odom_frame_id

Type	Default
string	“odom”

Description:

Which frame to use for odometry.

transform_tolerance

Type	Default
double	0.1

Description

Time with which to post-date the transform that is published, to indicate that this transform is valid into the future.

source_timeout

Type	Default
double	2.0

Description:

Maximum time interval in which source data is considered as valid. If no new data is received within this interval, an additional warning will be displayed. Setting source_timeout: 0.0 disables it. This parameter can be overridden per observation source.

base_shift_correction

Type	Default
bool	True

Description:

Whether to correct source data towards to base frame movement, considering the difference between current time and latest source time. If enabled, produces more accurate sources positioning in the robot base frame, at the cost of slower performance. This will cause average delays for ~1/(2*odom_rate) per each cmd_vel calculation cycle. However, disabling this option for better performance is not recommended for the fast moving robots, where during the typical rate of data sources, robot could move unacceptably far. Thus reasonable odometry rates are recommended (~100 hz).

polygons

Type	Default
vector<string>	N/A

Description:

List of zones to check for data points. Causes an error, if not specialized.

observation_sources

Type	Default
vector<string>	N/A

Description:

List of data sources (laser scanners, pointclouds, etc…). Causes an error, if not specialized.

Polygons parameters

<polygon name> is the corresponding polygon name ID selected for this type.

<polygon_name>.type

Type	Default
string	N/A

Description:

Type of polygon shape. Available values are polygon, circle. Causes an error, if not specialized.

<polygon_name>.points

Type	Default
string	N/A

Description:

Polygon vertices, listed in "[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]" format (e.g. "[[0.5, 0.25], [0.5, -0.25], [0.0, -0.25], [0.0, 0.25]]" for the square in the front). Used for polygon type. Minimum 3 points for a triangle polygon. If not specified, the collision detector will use dynamic polygon subscription to polygon_sub_topic

<polygon_name>.polygon_sub_topic

Type	Default
string	N/A

Description:

Topic to listen the polygon points from. Causes an error, if not specified and points are also not specified. If both points and polygon_sub_topic are specified, the static points takes priority.

<polygon_name>.radius

Type	Default
double	N/A

Description:

Circle radius. Used for circle type. Causes an error, if not specialized.

<polygon_name>.action_type

Type	Default
string	N/A

Description:

Only none action type is supported (more options available for collision monitor)

<polygon_name>.min_points

Type	Default
int	4

Description:

Minimum number of data readings within a zone to trigger the action. Former max_points parameter for Humble, that meant the maximum number of data readings within a zone to not trigger the action). min_points is equal to max_points + 1 value.

<polygon_name>.trigger_consecutive_points

Type	Default
int	1

Description:

Number of consecutive processing cycles with points_inside >= min_points required to enter the triggered state. A value of 1 means trigger in a single processing cycle.

<polygon_name>.release_consecutive_points

Type	Default
int	1

Description:

Number of consecutive processing cycles with points_inside < min_points required to leave the triggered state. A value of 1 means release in a single processing cycle. In practice, values greater than 1 can reduce sensor noise flicker while remaining responsive.

<polygon_name>.visualize

Type	Default
bool	False

Description:

Whether to publish the polygon in a separate topic.

<polygon_name>.polygon_pub_topic

Type	Default
string	<polygon_name>

Description:

Topic name to publish a polygon to. Used only if visualize is true.

<source name>.enabled

Type	Default
bool	True

Description:

Whether to use this source for collision detection. (Can be dynamically set)

Observation sources parameters

<source name> is the corresponding data source name ID selected for this type.

<source name>.type

Type	Default
string	“scan”

Description:

Type of polygon shape. Could be scan, pointcloud, range or polygon.

<source name>.transport_type

Type	Default
string	“raw”

Description:

For pointcloud data, specify the transport plugin to use:

• raw: No compression. Default; highest bandwidth usage.

• draco: Lossy compression via Google.

• zlib: Lossless compression via Zlib compression.

• zstd: Lossless compression via Zstd compression.

See the known transports for more details.

<source name>.topic

Type	Default
string	“scan”

Description:

Topic to listen the source data from.

<source name>.min_height

Type	Default
double	0.05

Description:

Minimum height the PointCloud projection to 2D space started from. Applicable for pointcloud type.

<source name>.max_height

Type	Default
double	0.5

Description:

Maximum height the PointCloud projection to 2D space ended with. Applicable for pointcloud type.

<source name>.obstacles_angle

Type	Default
double	PI / 180 (1 degree)

Description:

Angle increment (in radians) between nearby obstacle points at the range arc. Two outermost points from the field of view are not taken into account (they will always exist regardless of this value). Applicable for range type.

<source name>.sampling_distance

Type	Default
double	0.1

Description:

Internally the polygon is sampled for collision detection. sampling_distance is the distance between sampled points of the polygon. Applicable for polygon source type.

<source name>.enabled

Type	Default
bool	True

Description:

Whether to use this source for collision detection. (Can be dynamically set)

<source name>.source_timeout

Type	Default
double	(node parameter source_timeout value)

Description:

Maximum time interval in which source data is considered as valid. If no new data is received within this interval, an additional warning will be displayed. Setting source_timeout: 0.0 disables it. Overrides node parameter for each source individually, if desired.

<source name>.exclusion_zones

Type	Default
vector<string>	[]

Description:

List of exclusion zone name IDs defined for this source. Each name refers to a zone parameter block (see Exclusion zones parameters). Points from this source that fall inside an enabled zone are removed before the detector polygons are evaluated.

Exclusion zones parameters

<zone name> is a parameter block referenced by name from a source’s exclusion_zones list. Zone names are global across the node. Exclusion zones remove (mask out) a source’s points and never trigger detection. Each zone inherits the owning source’s base_shift_correction policy.

<zone name>.type

Type	Default
string	“polygon”

Description:

Type of zone shape. Available values are polygon and circle.

<zone name>.points

Type	Default
string	“”

Description:

Zone polygon vertices, listed in "[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y], ...]" format, expressed in frame_id. Used for polygon type. Minimum 3 points. Causes an error, if invalid for a polygon zone.

<zone name>.radius

Type	Default
double	N/A

Description:

Circle radius. Used for circle type. Must be greater than 0. Causes an error, if not specified for a circle zone.

<zone name>.frame_id

Type	Default
string	(node base_frame_id)

Description:

Frame the zone shape is anchored to and tracked via TF (e.g. dock_link). Leaving it empty, or equal to the base frame, makes a static, robot-relative zone.

<zone name>.frame_hold_timeout

Type	Default
double	0.0

Description:

Extra time (in seconds) beyond transform_tolerance that the last known pose of a stale zone frame_id keeps being used before the zone fails safe and stops masking points. While held, the zone is frozen at its last valid pose in the odom_frame_id frame, so it stays world-fixed even if the robot moves. Useful to ride out brief detection dropouts of a marker-based zone frame. 0.0 means only the transform tolerance applies.

<zone name>.min_height

Type	Default
double	-inf

Description:

Lower bound (in the base frame z) of the height band a point must be within to be masked. Unbounded by default so 2D sources are fully covered.

<zone name>.max_height

Type	Default
double	+inf

Description:

Upper bound (in the base frame z) of the height band a point must be within to be masked. Unbounded by default so 2D sources are fully covered.

<zone name>.enabled

Type	Default
bool	False

Description:

Whether this zone actively masks points. (Can be dynamically set)

<zone name>.visualize

Type	Default
bool	False

Description:

Whether to publish the zone footprint as a geometry_msgs/PolygonStamped for visualization.

bond_heartbeat_period

Type	Default
double	0.25

Description

The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0.

allow_parameter_qos_overrides

Type	Default
bool	true

Description

Whether to allow QoS profiles to be overwritten with parameterized values.

Example

Here is an example of configuration YAML for the Collision Detector.

collision_detector:
  ros__parameters:
    base_frame_id: "base_footprint"
    odom_frame_id: "odom"
    transform_tolerance: 0.5
    source_timeout: 5.0
    base_shift_correction: True
    polygons: ["PolygonFront"]
    PolygonFront:
      type: "polygon"
      points: "[[0.3, 0.3], [0.3, -0.3], [0.0, -0.3], [0.0, 0.3]]"
      action_type: "none"
      min_points: 4
      visualize: True
      polygon_pub_topic: "polygon_front"
    observation_sources: ["scan", "pointcloud"]
    scan:
      source_timeout: 0.2
      type: "scan"
      topic: "scan"
      enabled: True
    pointcloud:
      type: "pointcloud"
      topic: "/intel_realsense_r200_depth/points"
      transport_type: "raw"  # raw or/ with compression (zlib, draco, zstd)
      min_height: 0.1
      max_height: 0.5
      enabled: True
      exclusion_zones: ["dock"]   # references the "dock" zone block below
    # Exclusion zone blocks are referenced by name from a source's "exclusion_zones" list.
    dock:
      enabled: True
      type: "polygon"          # "polygon" or "circle"
      frame_id: "dock_link"    # frame the zone is anchored to; empty -> robot base frame (static)
      points: "[[0.5, 0.5], [0.5, -0.5], [-0.5, -0.5], [-0.5, 0.5]]"  # polygon type only
      # radius: 0.5            # circle type only (must be > 0)
      min_height: -1.0         # base-frame z band a point must be within to be masked
      max_height: 1.0
      visualize: True          # publish the zone footprint as a PolygonStamped