The `pdk-scene` Command-Line Tool

pdk-scene inspects and modifies the scene on a running server from a terminal, without writing code. It uses the same gRPC interface as every binding, so it is useful whatever language your application is written in. It is installed with the Python package; see Install for Python.

Use it for one-off scene setup, inspection and debugging. It builds the protobuf messages and checks status codes for you. Use the SDK for anything with real logic.

Global options

pdk-scene [--target HOST:PORT] <group> <command> [options]

--target

Server address. Default localhost:50052. It goes before the group:

pdk-scene --target 192.168.1.50:50052 workcell list

--help

Works at every level: pdk-scene --help, pdk-scene object --help, pdk-scene object create --help.

--json

Read commands can print JSON: workcell list, every list and get, system joints get and license status.

On error, pdk-scene prints Error: gRPC <CODE>: <details> for transport errors or Error: <action> failed: <message> (code N) for application errors, and exits with a non-zero code.

Important

Every command except workcell, license, log and version needs an active workcell.

Command reference

pdk-scene
├── workcell
│   ├── create NAME [--description TEXT] [--load/--no-load]
│   ├── load NAME
│   └── list [--json]
├── object
│   ├── create NAME [--parent world] [--pos X Y Z] [--quat X Y Z W]
│   │               [--box LX LY LZ | --mesh PATH] [--color R G B A]
│   ├── move NAME [--pos X Y Z] [--quat X Y Z W]
│   ├── list [--json]
│   ├── get NAME [--json]
│   └── remove NAME
├── camera
│   ├── create NAME [--parent world] [--pos] [--quat] [--camera-id 0]
│   │               [--far-width 1.0] [--far-height 1.0]
│   │               [--far-distance 2.0] [--near-distance 0.1]
│   └── list | get | remove
├── coordinate
│   ├── create NAME [--parent world] [--pos] [--quat] [--scale X Y Z]
│   └── list | get | remove
├── surface-path
│   ├── create NAME --parent OBJECT [--from X Y Z] [--to X Y Z]
│   │               [--points N] [--quat X Y Z W]
│   └── list | get | remove
├── system-pose
│   ├── create NAME [--parent world] [--pos] [--quat] [--joints "j1,j2,..."]
│   └── list | get | remove
├── system
│   └── joints
│       ├── get NAME [--group system] [--json]
│       └── set NAME P1 P2 ... [--group system]
├── watch
├── license
│   ├── status [--json]
│   ├── identifier [-o FILE]
│   └── install -f FILE.lic [--file-name NAME]
├── log [--level debug] [--count 50] [--follow]
└── version

Defaults: --pos 0 0 0, --quat 0 0 0 1 (x y z w), --parent world.

workcell

pdk-scene workcell create demo          # creates AND loads "demo" (use --no-load to skip)
pdk-scene workcell load demo
pdk-scene workcell list                 # the active workcell is marked with '*'

object

# A 10 cm box at (0.3, 0, 0.2) in the world frame
pdk-scene object create widget --box 0.1 0.1 0.1 --pos 0.3 0 0.2
# The same box in red: --color R G B A, each from 0 to 1
pdk-scene object create marker --box 0.1 0.1 0.1 --color 1 0 0 1
# A mesh parented to another object (the path must be readable by the server)
pdk-scene object create bracket --mesh /server/path/bracket.stl --parent widget

pdk-scene object list
pdk-scene object get widget
pdk-scene object get widget --json
pdk-scene object move widget --pos 0.5 0.1 0.3   # persisted; emits CHANGE_UPDATED
pdk-scene object remove bracket

--box and --mesh are mutually exclusive, and --color needs one of them. object move sets the whole pose in the parent frame: a --pos or --quat you leave out is reset to its default, not kept.

camera, coordinate, system-pose

pdk-scene camera create cam0 --parent widget --camera-id 0 \
    --far-width 1.2 --far-height 0.9 --far-distance 2.0 --near-distance 0.1

pdk-scene coordinate create fixture --pos 0.4 0 0.1

# A full robot state: a Cartesian pose plus the joints that realize it
pdk-scene system-pose create home --pos 0.4 0 0.3 \
    --joints "0, 0.5, -0.3, 1.2, 0, 0.8, 0"

pdk-scene camera list
pdk-scene coordinate get fixture
pdk-scene system-pose remove home

The server refuses to overwrite an existing system pose; remove it first.

surface-path

Creates a straight-line manual path on an object, interpolated with --points waypoints (at least 2):

# 2 waypoints, 10 cm along +X from the object's origin
pdk-scene surface-path create weld --parent widget --from 0 0 0 --to 0.1 0 0
# 5 waypoints along a diagonal
pdk-scene surface-path create scan --parent widget --from 0 0 0 --to 0.15 0 0.05 --points 5
pdk-scene surface-path get weld

system

Moves a system in the scene, to try joint positions before planning or to check for collisions. It does not move a real or simulated robot, and it is not saved: a system starts at the home position in its config. Positions are in rad or m.

pdk-scene system joints get system_1                   # every actuated joint
pdk-scene system joints get system_1 --group arm --json
pdk-scene system joints set system_1 0 -0.7 0 1.57 0 0.7 0 --group arm

--group is one of system, arm, external-robot-axis and external-workpiece-axis.

watch

Streams scene events until interrupted; useful for debugging another client:

$ pdk-scene watch
Watching scene events (Ctrl-C to stop)...
change=1 origin=1 entity=4:'widget' frames=['widget']

Values are the enum numbers: change 1–5 are ADDED, UPDATED, REMOVED, RENAMED, REFRESHED; origin 1 is CONFIG and 2 is FRAME; the entity type is a ConfigType (4 is OBJECT). See Watching Scene Events.

license

Does not need a workcell. See Activate Licenses.

pdk-scene license status                    # table of services and license state
pdk-scene license identifier                # writes license_identifier.txt to email to Flexiv
pdk-scene license install -f NEB-1234.lic   # takes effect at once, no restart

log and version

Neither needs a workcell. When a command fails, the server’s log usually says why:

pdk-scene log                       # the newest 50 entries
pdk-scene log --level warning       # only warnings and errors
pdk-scene log --follow              # keep printing new entries until Ctrl-C
pdk-scene version                   # client and server versions

--count 0 prints every entry the server kept. version fails when the client and server major or minor versions differ.

The pdk-scene Command-Line Tool