Region that removes (masks out) source points falling inside it. More...

#include <nav2_collision_monitor/include/nav2_collision_monitor/exclusion_zone.hpp>

Collaboration diagram for nav2_collision_monitor::ExclusionZone:

Public Member Functions
	ExclusionZone (const nav2::LifecycleNode::WeakPtr &node, const std::string &zone_name, const nav2::TransformBuffer::SharedPtr tf_buffer, const std::string &base_frame_id, const std::string &global_frame_id, const tf2::Duration &transform_tolerance, const bool base_shift_correction)
	ExclusionZone constructor. More...

	~ExclusionZone ()
	ExclusionZone destructor.

bool	configure ()
	Reads ROS parameters and configures the zone. More...

bool	configure (const nav2_msgs::msg::ExclusionZoneDescription &desc)
	Configures the zone from a service description. More...

void	activate ()
	Activates the visualization publisher (if any)

void	deactivate ()
	Deactivates the visualization publisher (if any)

void	apply (const rclcpp::Time &curr_time, std::vector< Point > &data) const
	Removes from data all points that fall inside the (enabled) zone. No-op when the zone is disabled. Fail-safe (removes nothing) when the zone transform is unavailable. More...

std::string	getName () const
	Obtains the name of the zone. More...

bool	getEnabled () const
	Obtains the enabled state of the zone. More...

void	publish () const
	Publishes the zone footprint for visualization (if enabled)

Protected Member Functions
bool	getParameters ()
	Reads ROS parameters for the zone. More...

void	updateParametersCallback (const std::vector< rclcpp::Parameter > &parameters)
	Apply parameter updates after validation (dynamic reconfigure) More...

rcl_interfaces::msg::SetParametersResult	validateParameterUpdatesCallback (const std::vector< rclcpp::Parameter > &parameters)
	Validate incoming parameter updates before applying them. More...

bool	getZoneToBaseTransform (const rclcpp::Time &curr_time, tf2::Transform &tf_zone_to_base) const
	Resolve the zone-frame -> base-frame transform for this cycle. More...

Protected Attributes
nav2::LifecycleNode::WeakPtr	node_
	Collision Monitor node.

rclcpp::Logger	logger_ {rclcpp::get_logger("collision_monitor")}
	Collision monitor node logger.

rclcpp::Clock::SharedPtr	node_clock_
	Node clock (for throttled logging and message stamps)

std::mutex	mutex_
	Dynamic parameters handlers.

rclcpp::node_interfaces::PostSetParametersCallbackHandle::SharedPtr	post_set_params_handler_

rclcpp::node_interfaces::OnSetParametersCallbackHandle::SharedPtr	on_set_params_handler_

std::string	zone_name_
	Name of the zone.

nav2::TransformBuffer::SharedPtr	tf_buffer_
	TF buffer.

std::string	base_frame_id_
	Robot base frame ID.

std::string	global_frame_id_
	Global (fixed) frame ID, used to bridge the zone lookup in time.

tf2::Duration	transform_tolerance_
	Transform tolerance.

bool	base_shift_correction_
	Whether to correct the zone transform for base movement between data and current time.

double	frame_hold_timeout_ {0.0}
	Extra time (s) beyond the transform tolerance that a stale zone-frame pose may keep being used before the zone fails safe. 0 -> only the tolerance.

std::string	frame_id_
	Frame the zone shape is anchored to (tracked via TF). Defaults to base_frame_id_.

bool	is_circle_ {false}
	Whether the zone shape is a circle (otherwise polygon)

std::vector< Point >	poly_
	Zone polygon vertices, expressed in frame_id_ (for polygon type)

double	radius_ {0.0}
	Circle radius (for circle type)

double	radius_squared_ {0.0}
	radius squared, cached

double	min_height_
	Lower bound of the height band (base-frame z) a point must be within to be excluded.

double	max_height_
	Upper bound of the height band (base-frame z) a point must be within to be excluded.

bool	enabled_ {false}
	Whether the zone is currently active.

bool	visualize_ {false}
	Whether to publish the zone footprint for visualization.

nav2::Publisher< geometry_msgs::msg::PolygonStamped >::SharedPtr	zone_pub_
	Zone footprint publisher.

Detailed Description

Region that removes (masks out) source points falling inside it.

Unlike a Polygon, an ExclusionZone does not produce a robot Action. It is a pre-filter applied to a Source's collision points before the action polygons are evaluated. Its shape is defined in an arbitrary frame (frame_id) and is transformed into the robot base frame every cycle, so the zone can track a moving TF frame (e.g. a charging station the robot is docking onto).

Fail-safe: if the zone is enabled but its transform cannot be obtained, no points are removed (full collision protection is retained).

Definition at line 51 of file exclusion_zone.hpp.

Constructor & Destructor Documentation

◆ ExclusionZone()

nav2_collision_monitor::ExclusionZone::ExclusionZone	(	const nav2::LifecycleNode::WeakPtr &	node,
		const std::string &	zone_name,
		const nav2::TransformBuffer::SharedPtr	tf_buffer,
		const std::string &	base_frame_id,
		const std::string &	global_frame_id,
		const tf2::Duration &	transform_tolerance,
		const bool	base_shift_correction
	)

ExclusionZone constructor.

Parameters

node	Collision Monitor node pointer
zone_name	Name of the exclusion zone
tf_buffer	Shared pointer to a TF buffer
base_frame_id	Robot base frame ID (source points are expressed in this frame)
global_frame_id	Global (fixed) frame ID used to bridge the zone lookup in time
transform_tolerance	Transform tolerance
base_shift_correction	Whether to correct the zone transform for base movement in time

Definition at line 35 of file exclusion_zone.cpp.

References logger_, and zone_name_.

Member Function Documentation

◆ apply()

void nav2_collision_monitor::ExclusionZone::apply	(	const rclcpp::Time &	curr_time,
		std::vector< Point > &	data
	)		const

Removes from data all points that fall inside the (enabled) zone. No-op when the zone is disabled. Fail-safe (removes nothing) when the zone transform is unavailable.

Parameters

curr_time	Current node time, used for the zone-frame -> base-frame lookup
data	Source points in base_frame_id_; excluded points are erased in place

Definition at line 213 of file exclusion_zone.cpp.

References enabled_, getZoneToBaseTransform(), is_circle_, mutex_, and radius_squared_.

Here is the call graph for this function:

◆ configure() [1/2]

bool nav2_collision_monitor::ExclusionZone::configure ( )

Reads ROS parameters and configures the zone.

Returns: True if configured correctly, false otherwise

Definition at line 69 of file exclusion_zone.cpp.

References getParameters(), node_, node_clock_, updateParametersCallback(), validateParameterUpdatesCallback(), visualize_, zone_name_, and zone_pub_.

Here is the call graph for this function:

◆ configure() [2/2]

bool nav2_collision_monitor::ExclusionZone::configure ( const nav2_msgs::msg::ExclusionZoneDescription & desc )

Configures the zone from a service description.

Parameters

desc	Exclusion zone description message

Returns: True if configured correctly, false otherwise

Definition at line 95 of file exclusion_zone.cpp.

References base_frame_id_, enabled_, frame_hold_timeout_, frame_id_, is_circle_, logger_, max_height_, min_height_, node_, node_clock_, poly_, radius_, radius_squared_, visualize_, zone_name_, and zone_pub_.

◆ getEnabled()

bool nav2_collision_monitor::ExclusionZone::getEnabled ( ) const

Obtains the enabled state of the zone.

Returns: Whether the zone is enabled

Definition at line 350 of file exclusion_zone.cpp.

◆ getName()

std::string nav2_collision_monitor::ExclusionZone::getName ( ) const

Obtains the name of the zone.

Returns: Zone name

Definition at line 345 of file exclusion_zone.cpp.

◆ getParameters()

bool nav2_collision_monitor::ExclusionZone::getParameters ( )

protected

Reads ROS parameters for the zone.

Returns: True if all parameters were obtained, false otherwise

Definition at line 153 of file exclusion_zone.cpp.

References base_frame_id_, enabled_, frame_hold_timeout_, frame_id_, is_circle_, logger_, max_height_, min_height_, node_, poly_, radius_, radius_squared_, visualize_, and zone_name_.

Referenced by configure().

Here is the caller graph for this function:

◆ getZoneToBaseTransform()

bool nav2_collision_monitor::ExclusionZone::getZoneToBaseTransform	(	const rclcpp::Time &	curr_time,
		tf2::Transform &	tf_zone_to_base
	)		const

protected

Resolve the zone-frame -> base-frame transform for this cycle.

Parameters

curr_time	Current node time
tf_zone_to_base	Output zone-frame -> base-frame transform on success

Returns: True if the zone can be localised (within the hold window), false otherwise

Definition at line 263 of file exclusion_zone.cpp.

Referenced by apply().

Here is the caller graph for this function:

◆ updateParametersCallback()

void nav2_collision_monitor::ExclusionZone::updateParametersCallback ( const std::vector< rclcpp::Parameter > & parameters )

protected

Apply parameter updates after validation (dynamic reconfigure)

Parameters

parameters List of parameters that have been updated

Definition at line 441 of file exclusion_zone.cpp.

Referenced by configure().

Here is the caller graph for this function:

◆ validateParameterUpdatesCallback()

rcl_interfaces::msg::SetParametersResult nav2_collision_monitor::ExclusionZone::validateParameterUpdatesCallback ( const std::vector< rclcpp::Parameter > & parameters )

protected

Validate incoming parameter updates before applying them.

Parameters

parameters List of parameters being updated

Returns: Result indicating whether the update is accepted

Definition at line 403 of file exclusion_zone.cpp.

Referenced by configure().

Here is the caller graph for this function:

The documentation for this class was generated from the following files:

nav2_collision_monitor/include/nav2_collision_monitor/exclusion_zone.hpp
nav2_collision_monitor/src/exclusion_zone.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ExclusionZone()

Member Function Documentation

◆ apply()

◆ configure() [1/2]

◆ configure() [2/2]

◆ getEnabled()

◆ getName()

◆ getParameters()

◆ getZoneToBaseTransform()

◆ updateParametersCallback()

◆ validateParameterUpdatesCallback()