Creating a map with keepout zones.

To create a map with keepout zones, we are going to follow this tutorial.

ROS2 Nav2 uses keepout zones based on filter masks. Filter mask is an image file (png, bmp or pgm) with metadata stored in a separate yaml file.

Let's create a new image file, in our case, I am going to use a copy of my map.pgm file, and call it keepout_mask.pgm.

I am going to use GIMP graphical editor to alter this file:

                    $ sudo apt install gimp
                

As you already know, in a costmap, we have [0..255] or [0..100] shades, it is used by the Map Server (converted to [0..100], can also be -1 for an unknown value) and the higher the value, the more it "costs" to drive across that pixel.

Depending on a mode selected, the color of the pixel is converted to occupacy grid values according to the following rules:
trinary (default): If darkness is larger than an occupied_thresh value, the map is occupied (100), if less than free_thresh, it is 0. Anything in between is set to -1 (unknown status).
scale: If darkness is larger than an occupied_thresh value, the map is occupied (100), if less than free_thresh, it is 0. Anything in between is linearly interpolated to the nearest integer in [0..100] range.
raw: Pixel values are in [0..100] range, accordingly, occupancy is set to [0..100]. If pixel value is larger than 100, occupancy is set to -1.

Here free_thresh and occupied_thresh thresholds are expressed in percentage of maximum lightness/darkness level (255).

Map mode and thresholds are placed in YAML metadata file as mode, free_thresh and occupied_thresh fields.
There is another parameter in a YAML metadata file called negate. By default it is set to false. When it is set to true, blacker pixels will be considered as free, whiter pixels - as occupied.

In the GIMP lightness is expressed through color components value (e.g. R in percent scale) and might be set by moving L slider in color changing tool:

Before:

After:

Same thing in RViz:

Keepout filter also allows us to create preferred lanes, by marking such lanes as passable.

Quote: World map itself and filter mask could have different sizes, origin and resolution which might be useful e.g. for cases when filter mask is covering smaller areas on maps or when one filter mask is used repeatedly many times (like annotating a keepout zone for same shape rooms in the hotel). For this case, you need to correct resolution and origin fields in YAML as well so that the filter mask is correctly laid on top of the original map.
Another important note is that since Costmap2D does not support orientation, the last third “yaw” component of the origin vector should be equal to zero. For example: origin: [1.25, -5.18, 0.0].

                    image: keepout_mask.pgm
                    mode: trinary
                    resolution: 0.05
                    origin: [-8.14, -7.81, 0]
                    negate: 0
                    occupied_thresh: 0.8
                    free_thresh: 0.65