Keepout Zones and Saving/Loading Planning Scene

The Keepout Zones feature is designed to quickly define regions in the workspace where the robot(s) is prohibited from entering or interacting. This is crucial for avoiding obstacles and ensuring safe operation in dynamic environments. This guide informs on how to create, manipulate, and manage keepout zones within the planning scene.

Keepout zones are implemented as 3D cubes in the planning scene. This how-to guide will walk through:

1. Creating and visualizing keepout zones in the 3D planning scene.
2. Manipulating keepout zones, including moving, rotating, and deleting them.
3. Naming keepout zones and setting their color and transparency.
4. Saving and loading keepout zone configurations to the planning scene.

Creating a Keepout Zone

You can create a keepout zone in the 3D planning scene by defining its size, orientation and position. This keepout zone will prevent the robot from moving into this region.

To create a keepout zone:

1. Open the Mode menu in the top left of the MoveIt Pro Desktop App and select Planning Scene Editor.
2. Click the + Keep-Out Zone button to create a new keepout zone.
3. Adjust the size, position, and orientation parameters of the keepout zone. The parameters are as follows:
   • Size: Set the width, height, and length of the keepout zone. Drag the jog strip beside each field, or type the value.
   • Position: Set the x, y, and z coordinates to position the keepout zone in the workspace, the same way.
   • Orientation: Use roll, pitch, and yaw sliders to rotate the keepout zone around its axes.

Size and position have no upper limit

Dragging a jog strip raises or lowers its value by how far you drag, not by where you release, so a zone can be made any size and placed at any coordinate — there is no end of travel to reach. Hold Shift while dragging to move ten times finer, or click the strip and use the arrow keys to change the value one step at a time (Shift plus an arrow key for a tenth of a step).

Size stops at 0.01 m, the smallest box the planning scene accepts. The red stretch on a size strip marks the values below it, and slides into view from the left as the zone gets smaller, so the floor is visible on the ruler rather than announced only once you hit it.

Orientation keeps an ordinary slider, because roll, pitch, and yaw span the whole circle and the slider's ends are the real ends of the value.

Manipulating Keepout Zones

Once a keepout zone has been created, you can manipulate it further. It initially appears already selected, with an outline. You can move, rotate, or delete the keepout zone using the interactive marker that appears when the zone is selected. A deselected keepout zone loses the outline and the interactive marker, and both return when you select it again.

Select a zone in the 3D Visualizer to show its name, transparency, color, Clone and Delete buttons, size, position, and rotation in the sidebar.

The Runtime names a new zone keep-out-zone-1, keep-out-zone-2, and so on, one past the highest generated number currently in the planning scene. Deleting the highest-numbered zone makes its number available again; deleting all generated zones restarts numbering at keep-out-zone-1. Connected to a Runtime from an earlier release, the Desktop App gives a new zone a generated UUID instead. Collision and planning error messages, and the Alert Sidebar, name a zone by this ID, so you can tell which zone caused a failure.

1. Move: Click and drag the keepout zone to a new position using the arrows on the outside of the interactive marker.
2. Rotate: Use the circular interactive marker that appears on the edges of the keepout zone to adjust its rotation. Click and drag the circular handles to rotate the keepout zone around its axes.
3. Delete: To remove a keepout zone, select it and press the Delete or Backspace key. Alternatively, click the Delete button in the side panel.
4. Clone: To reuse a keepout zone's size, rotation, color, and transparency, select it and click the Clone button in the side panel. The copy appears beside the original with the next keep-out-zone-<N> name, or a generated UUID on a Runtime from an earlier release, and becomes the selected zone, ready to be dragged into place.

In the Planning Scene Editor, you can select and edit a keepout zone from any of the 3D views. The orthographic views make a misaligned zone easy to spot and correct: click the zone in the X-Axis (Side), Y-Axis (Front), or Z-Axis (Top) pane, then drag the arrows or the ring facing you. The selection and interactive marker appear in every open 3D view, the other views follow the zone as you drag, and the side panel picks up the new pose when you release the handle. To pan an orthographic view, drag with the right mouse button, or hold Shift and drag.

Lock keepout zones, under View in the 3D Visualizer pane, takes selection and the interactive marker away from every keepout zone, so none of them can be clicked or dragged by accident. While the lock is on, a zone cannot be selected or renamed. The appearance controls shown when no zone is selected still work, because color and transparency change only how zones look. Creating or cloning a zone switches the lock off, because the new zone arrives selected and ready to place. While teleoperation is active, creating a zone does not switch the lock off.

Naming Keepout Zones

Select a zone, click its name in the sidebar, and type a new one. The zone's tag in the 3D views follows as you type. Press Enter or click away to rename the zone: the name replaces the zone's ID in the planning scene. To hide the tags, clear Show zone names in 3D views below + Keep-Out Zone. The zone keeps its geometry, pose, and color, and it still blocks motion. Renaming requires a Runtime that provides /rename_keepout_zone; on an earlier Runtime, update the Runtime before renaming zones.

A zone's ID is its name, so:

• A zone whose ID is a UUID, such as one in a scene file saved by an earlier release, shows no tag, and any other ID shows one. Every zone the Runtime names therefore has a tag.
• Anything that refers to the zone by ID, such as an Objective, must use the new name.
• The field shows a message, and the zone keeps its current name, if the new name is empty, contains /, is <octomap>, or is already used by another object or a robot link. A name that a frame or an allowed-collision entry in the planning scene already uses is refused too, and a message explains why. The Runtime checks the source and the new name, then renames the current object under one scene lock. If another user has already renamed the source or taken the new name, the request is refused without creating a copy. An object attached to the robot cannot be renamed until it is detached. An object with explicit or default collision rules cannot be renamed until those rules are removed, because renaming would drop them.
• A zone with allowed-collision rules keeps its name, and an error says why: renaming it would drop those rules, so it would collide where it is now allowed to.
• If the connection fails before a rename is confirmed, the Desktop App keeps the latest scene published by the Runtime, cancels waiting edits, and blocks selection of either affected name and further renames. Reconnect to the Runtime, check the zone's name and pose, then retry the edits.

Setting Color and Transparency

Set one zone's look with the color swatch and transparency slider under its name after selecting it. To see how well a zone covers a point cloud, raise its transparency. Live color and transparency updates need Runtime 10.2 or newer; on an earlier Runtime, a saved color can show its previous value until the next scene update.

When no zone is selected, the sidebar shows global Transparency and Color controls under Defaults for all zones. New zones start with these values; transparency defaults to 10%:

• Changing a global control changes no existing zone. It sets only what the next new zone starts with.
• Objects attached to the robot keep the color that marks them as carried. Apply to All does not change them, and you can still select one to edit its appearance.
• The global values are saved locally by the Desktop App, not in the scene. A zone loaded from a scene file with different values keeps them.

Click Apply to All to set every existing zone to the global values in one step. It changes appearance only, and leaves each zone's name, geometry, and pose as they are. The note beside it counts the zones that differ from the global values, and the button is disabled when every zone already matches.

Transparency stops at 80%, so a zone that blocks motion stays visible. Selecting a zone by clicking it in the 3D Visualizer works at any transparency.

Saving and Loading Keepout Zones

After defining your keepout zones, you can save them to a .scene file on your computer:

1. Click the Export Scene button in the Planning Scene Editor sidebar.
2. The installed app asks where to save the file. In the web app, the browser saves it like any download; turn on its option to ask where to save each file if you want to pick the folder and name.

Each zone's name, color, and transparency are saved with it.

To load a previously saved planning scene, including keepout zones:

1. Click the Load Scene button in the Planning Scene Editor sidebar.
2. Choose the .scene file in the file dialog.

Scenes saved by earlier versions of MoveIt Pro are in ~/.local/share/moveit_pro/planning_scenes/ on the Runtime computer. Copy one to the computer running the MoveIt Pro Desktop App, then load it with Load Scene.

Loading replaces the objects in the current planning scene with the ones in the file, so export the current scene first if you want to keep it. If the file is not a valid scene file, MoveIt Pro shows an error and leaves the current scene unchanged.

You cannot load a scene while an Objective is running; stop it first. Loading a scene also removes any allowed collisions an Objective set for the replaced objects, because scene files do not store them. Objects the robot is holding keep theirs. A loaded keepout zone applies to motions planned after the load; a trajectory that is already running is not re-checked against it.