Planning Scene Management

The joint client provides methods for managing saved planning scenes (obstacle layouts) and manipulating collision objects in MoveIt's live planning scene. Saved scenes are stored in the database and can be listed, loaded, saved, updated, and deleted. Live collision objects are added/removed/moved in MoveIt's active planning scene for collision-aware motion planning.

Saved Planning Scenes

Saved planning scenes store obstacle configurations (positions, types, dimensions) in the database. They can be loaded later to restore a known environment layout.

`listPlanningScenes(options)`

Get a list of saved planning scenes for the current user.

Parameters:

options (object, optional):
- limit (number) - Maximum scenes to return (default: 50)
- offset (number) - Pagination offset (default: 0)
- search (string) - Search term to filter by name/description

Returns: Promise<Object> with { scenes, total, limit, offset }

SDK Playground:

const result = await olo.listPlanningScenes();
console.log(`Found ${result.total} scenes`);
for (const scene of result.scenes) {
    console.log(`- ${scene.name} (id: ${scene.id})`);
}

Python:

`getPlanningScene(sceneId, includeData)`

Get a specific planning scene by ID.

Parameters:

sceneId (number) - Scene ID
includeData (boolean) - Whether to include the full scene data (default: false). When false, only metadata (name, description, timestamps) is returned.

Returns: Promise<Object> - Scene information. When includeData is true, includes scene_data (JSON string of serialized obstacles).

SDK Playground:

// Get metadata only
const scene = await olo.getPlanningScene(1);
console.log(`Scene: ${scene.name}`);

// Get with full data
const fullScene = await olo.getPlanningScene(1, true);
const obstacles = JSON.parse(fullScene.scene_data);
console.log(`Scene has ${obstacles.length} obstacles`);

Python:

`savePlanningScene(sceneData)`

Save a new planning scene.

Parameters:

sceneData (object):
- name (string, required) - Scene name
- description (string, optional) - Scene description
- sceneData (string, required) - JSON string of serialized obstacles
- metadata (object, optional) - Scene metadata, e.g. { obstacleCount: 5, types: ['box', 'cylinder'] }

Returns: Promise<Object> - Saved scene information

SDK Playground:

const obstacles = [
    { id: 'box1', type: 'box', position: { x: 0.5, y: 0, z: 0.25 }, dimensions: { width: 0.1, height: 0.5, depth: 0.1 } }
];

const saved = await olo.savePlanningScene({
    name: 'My Scene',
    description: 'Test obstacle layout',
    sceneData: JSON.stringify(obstacles),
    metadata: { obstacleCount: obstacles.length }
});
console.log(`Saved scene ID: ${saved.scene.id}`);

Python:

`updatePlanningScene(sceneId, updateData)`

Update an existing planning scene.

Parameters:

sceneId (number) - Scene ID to update
updateData (object):
- name (string, optional) - New name
- description (string, optional) - New description
- sceneData (string, optional) - New scene data JSON string
- metadata (object, optional) - New metadata

Returns: Promise<Object> - Updated scene information

SDK Playground:

await olo.updatePlanningScene(1, {
    name: 'Updated Scene Name',
    sceneData: JSON.stringify(updatedObstacles)
});

Python:

`deletePlanningScene(sceneId)`

Delete a planning scene.

Parameters:

sceneId (number) - Scene ID to delete

Returns: Promise<Object> - Deletion result

SDK Playground:

await olo.deletePlanningScene(1);

Python:

Live MoveIt Collision Objects

These methods manipulate collision objects in MoveIt's live planning scene. Objects added here are used for collision-aware motion planning when useMotionPlanning: true is set on movement commands. All positions use ROS Z-up coordinates.

Collision Object Format

Each collision object has the following properties:

id (string) - Unique identifier for the object
type (string) - Object type: 'box', 'cylinder', 'sphere', or 'mesh'
position (object) - Position in ROS Z-up coordinates: { x, y, z }
rotation (object) - Orientation as quaternion: { x, y, z, w }
dimensions (object) - Size, depends on type:
- box: { width, height, depth }
- cylinder: { radius, height }
- sphere: { radius }
frame_id (string) - Reference frame (default: 'world')
mesh_vertices (array) - For mesh type: flat array of vertex positions [x, y, z, ...]
mesh_triangles (array) - For mesh type: flat array of triangle indices

`addCollisionObjects(collisionObjects)`

Add collision objects to MoveIt's live planning scene.

Parameters:

collisionObjects (array) - Array of collision objects (see format above)

Returns: Promise<Object> - Result with { success, processed_ids }

SDK Playground:

await olo.addCollisionObjects([
    {
        id: 'table',
        type: 'box',
        position: { x: 0.5, y: 0, z: 0.35 },
        rotation: { x: 0, y: 0, z: 0, w: 1 },
        dimensions: { width: 0.6, height: 0.7, depth: 0.4 },
        frame_id: 'world'
    },
    {
        id: 'cup',
        type: 'cylinder',
        position: { x: 0.5, y: 0.1, z: 0.75 },
        rotation: { x: 0, y: 0, z: 0, w: 1 },
        dimensions: { radius: 0.04, height: 0.12 },
        frame_id: 'world'
    }
]);

Python:

`removeCollisionObjects(objectIds)`

Remove collision objects from MoveIt's live planning scene.

Parameters:

objectIds (array) - Array of object ID strings to remove

Returns: Promise<Object> - Result with { success, processed_ids }

SDK Playground:

await olo.removeCollisionObjects(['table', 'cup']);

Python:

`moveCollisionObjects(collisionObjects)`

Move (reposition) existing collision objects in MoveIt's live planning scene. Only updates position and rotation without re-sending geometry data, making it efficient for moving objects.

Parameters:

collisionObjects (array) - Array of objects to move, each with:
- id (string) - Object ID (must already exist)
- position (object) - New position { x, y, z }
- rotation (object) - New quaternion { x, y, z, w }
- frame_id (string) - Reference frame (default: 'world')

Returns: Promise<Object> - Result with { success, processed_ids }

SDK Playground:

await olo.moveCollisionObjects([
    {
        id: 'cup',
        position: { x: 0.6, y: 0.2, z: 0.75 },
        rotation: { x: 0, y: 0, z: 0, w: 1 }
    }
]);

Python:

`getCollisionObjects()`

Get all collision objects currently in MoveIt's live planning scene.

Returns: Promise<Object> - Result with { success, collision_objects }

SDK Playground:

const result = await olo.getCollisionObjects();
for (const obj of result.collision_objects) {
    console.log(`Object: ${obj.id}, type: ${obj.type}`);
}

Python:

Complete Planning Scene Workflow

This example demonstrates saving a scene, loading it later, and syncing to MoveIt for collision-aware motion planning:

SDK Playground:

// 1. Define obstacles
const obstacles = [
    {
        id: 'workbench',
        type: 'box',
        position: { x: 0.5, y: 0, z: 0.4 },
        rotation: { x: 0, y: 0, z: 0, w: 1 },
        dimensions: { width: 0.8, height: 0.8, depth: 0.6 },
        frame_id: 'world'
    }
];

// 2. Save the scene
const saved = await olo.savePlanningScene({
    name: 'Workbench Setup',
    description: 'Standard workbench configuration',
    sceneData: JSON.stringify(obstacles),
    metadata: { obstacleCount: obstacles.length }
});
console.log(`Saved as scene ${saved.scene.id}`);

// 3. Later, list and load saved scenes
const scenes = await olo.listPlanningScenes();
const scene = await olo.getPlanningScene(scenes.scenes[0].id, true);
const loadedObstacles = JSON.parse(scene.scene_data);

// 4. Add to MoveIt's live planning scene
await olo.addCollisionObjects(loadedObstacles);

// 5. Move with collision avoidance
await olo.moveEndEffectorToPosition(
    { x: 0.4, y: 0.1, z: 0.6 },
    { useMotionPlanning: true }
);

// 6. Clean up when done
const current = await olo.getCollisionObjects();
const ids = current.collision_objects.map(o => o.id);
if (ids.length > 0) {
    await olo.removeCollisionObjects(ids);
}

Python:

On This Page

Getting Started

API Reference

Standalone Client Development