diff --git a/configuration/packages/configuring-costmaps.rst b/configuration/packages/configuring-costmaps.rst index 79375c72cb..0df2d7687c 100644 --- a/configuration/packages/configuring-costmaps.rst +++ b/configuration/packages/configuring-costmaps.rst @@ -346,6 +346,7 @@ Costmap Filters Parameters costmap-plugins/keepout_filter.rst costmap-plugins/speed_filter.rst + costmap-plugins/binary_filter.rst Example ******* diff --git a/configuration/packages/costmap-plugins/binary_filter.rst b/configuration/packages/costmap-plugins/binary_filter.rst new file mode 100644 index 0000000000..5deecf3c53 --- /dev/null +++ b/configuration/packages/costmap-plugins/binary_filter.rst @@ -0,0 +1,99 @@ +.. _binary_filter: + +Binary Filter Parameters +======================== + +Binary Filter - is a Costmap Filter that publishes a boolean topic, flipping binary state when the encoded filter space value (corresponding to the filter mask point where the robot is) is higher than given threshold. It then flips back when lower or equal. + +Filter space value is being calculated as: ``Fv = base + multiplier * mask_value``, where ``base`` and ``multiplier`` are being published in a filter info by Costmap Filter Info Server. The example of usage are include: camera operating on/off to turn off cameras in sensitive areas, headlights switch on/off for moving indoors to outdoors, smart house light triggering, etc. + +.. image:: ../images/binary_filter/binary_filter.png + :align: center + +``: is the corresponding plugin name selected for this type. + +:````.enabled: + + ====== ======= + Type Default + ------ ------- + bool True + ====== ======= + + Description + Whether it is enabled. + +:````.filter_info_topic: + + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + Name of the incoming `CostmapFilterInfo `_ topic having filter-related information. Published by Costmap Filter Info Server along with filter mask topic. For more details about Map and Costmap Filter Info servers configuration please refer to the :ref:`configuring_map_server` configuration page. + +:````.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. Used when filter mask and current costmap layer are in different frames. + +:````.default_state: + + ==== ======= + Type Default + ---- ------- + bool false + ==== ======= + + Description + Default state of binary filter. + +:````.binary_state_topic: + + ====== ============== + Type Default + ------ -------------- + string "binary_state" + ====== ============== + + Description + Topic of ``std_msgs::msg::Bool`` type to publish binary filter state to. + +:````.flip_threshold: + + ====== ======= + Type Default + ------ ------- + double 50.0 + ====== ======= + + Descrioption + Threshold for binary state flipping. Filter values higher than this threshold, will set binary state to non-default. + +Example +******* +.. code-block:: yaml + + global_costmap: + global_costmap: + ros__parameters: + ... + plugins: ["static_layer", "obstacle_layer", "inflation_layer"] + filters: ["binary_filter"] + ... + binary_filter: + plugin: "nav2_costmap_2d::BinaryFilter" + enabled: True + filter_info_topic: "/costmap_filter_info" + transform_tolerance: 0.1 + default_state: False + binary_state_topic: "/binary_state" + flip_threshold: 50.0 diff --git a/configuration/packages/images/binary_filter/binary_filter.png b/configuration/packages/images/binary_filter/binary_filter.png new file mode 100644 index 0000000000..74dee21a7b Binary files /dev/null and b/configuration/packages/images/binary_filter/binary_filter.png differ diff --git a/migration/Humble.rst b/migration/Humble.rst index 2abd60d438..7d2509ced5 100644 --- a/migration/Humble.rst +++ b/migration/Humble.rst @@ -57,3 +57,5 @@ Costmap Filters *************** Costmap Filters now are have an ability to be enabled/disabled in run-time by calling ``toggle_filter`` service for appropriate filter (`PR #3229 `_). + +Added new binary flip filter, allowing e.g. to turn off camera in sensitive areas, turn on headlights/leds/other safety things or switch operating mode when robot is inside marked on mask areas (`PR #3228 `_).