61 official Panda collision spheres · differentiable URDF kinematics · pose and trajectory repair · no GPU required
Robot SphereShield is a research implementation of the sphere-collision ideas behind cuRobo, rebuilt for ordinary CPU hardware. It positions the official Franka Panda collision spheres through differentiable URDF forward kinematics, measures signed geometric clearance, and repairs colliding poses or trajectories. PyBullet mesh collision queries provide an independent validator.
The repository also retains the earlier learned Robot PoseShield model as a baseline, making the trade-off visible: the deterministic model is safer on the measured holdout, but more conservative and substantially slower.
Caution
This is a research project, not a certified real-robot safety controller. The reported zero false-safe count is empirical on one seeded dataset—not a guarantee.
A neural collision field can be fast and differentiable, but its safety boundary is learned from samples. Sphere geometry gives an analytic signed distance and gradient:
Panda joint state
│
▼
differentiable URDF forward kinematics
│
▼
61 link-local spheres in world coordinates
│
├── self-collision distances (694 checked pairs)
├── plane / sphere / oriented-box distances
└── task-space sphere sweeps between trajectory waypoints
│
▼
SLSQP pose repair or Adam trajectory repair
│
▼
independent dense PyBullet validation
Joint states are still required: they are what place URDF links and their spheres in space. The pivot removes learned collision inference, not robot kinematics.
All numbers below were produced locally on CPU. The classification holdout contains
20,000 uniformly sampled Panda configurations generated with seed 20260713:
17,521 PyBullet-safe poses and 2,479 PyBullet collisions.
| Method | Accuracy | False-safe rate ↓ | False-collision rate ↓ |
|---|---|---|---|
| Deterministic spheres | 94.28% | 0 / 2,479 (0.00%) | 1,144 / 17,521 (6.53%) |
| Legacy neural field | 80.71% | 96 / 2,479 (3.87%) | 3,763 / 17,521 (21.48%) |
On the same 10 colliding holdout poses:
| Method | PyBullet-safe after repair | Mean joint distance | Median CPU time |
|---|---|---|---|
| Deterministic spheres | 10 / 10 | 1.0870 rad | 7.7848 s |
| Legacy neural field | 9 / 10 | 0.6264 rad | 0.0162 s |
The sphere optimizer traded speed and motion size for verified safety. Its mean end-effector position error was 0.1521 m and orientation error was 0.0804 rad on this small sample, so task preservation remains an explicit area for improvement.
Two endpoint-safe trajectories that crossed collision regions were also repaired and then checked at 301 interpolated PyBullet configurations each:
| Case | Colliding samples before | Colliding samples after | CPU repair time |
|---|---|---|---|
| 0 | 192 / 301 | 0 / 301 | 34.40 s |
| 1 | 41 / 301 | 0 / 301 | 34.09 s |
| Before repair | After repair |
|---|---|
 |
 |
- Official 61-sphere Franka Panda geometry from the Apache-2.0 cuRoboV2 config.
- Generic CPU PyTorch URDF tree parser supporting fixed, revolute, continuous, and prismatic joints.
- Differentiable forward kinematics verified against PyBullet.
- Official semantic self-collision exclusions and per-link collision buffers.
- Signed sphere-sphere, sphere-plane, sphere-obstacle, and sphere-OBB clearance.
- cuRobo/CHOMP-style quadratic activation cost near boundaries.
- Conservative 10 mm sphere padding and a 2 mm optimized clearance margin.
- SLSQP single-pose repair with end-effector pose preservation.
- Adam trajectory repair with linear sphere sweeps, speed weighting, and acceleration/jerk regularization.
- Independent PyBullet validation for poses and densely sampled trajectories.
- Seeded dataset generation and a direct deterministic-versus-neural benchmark.
Python 3.10 or 3.11 is recommended. Everything runs in PyBullet DIRECT mode; no display server, CUDA toolkit, or NVIDIA GPU is required.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev,sim]"
python -m pytestGenerate the deterministic holdout and reproduce the benchmark:
python scripts/generate_sphere_dataset.py --samples 20000 --seed 20260713 --sphere-padding 0.01
python scripts/benchmark_spheres.py --config configs/sphere_mvp.yamlRender the model or repair a holdout pose:
python scripts/render_sphere_model.py --index 0
python scripts/correct_sphere_pose.py --index 3Generated datasets, model checkpoints, and full benchmark reports are ignored by Git. The small figures shown above are intentionally versioned so the repository is useful at a glance.
configs/
franka_spheres.yaml official Panda sphere geometry + exclusions
sphere_mvp.yaml CPU pipeline and benchmark settings
src/robot_poseshield/
urdf_kinematics.py differentiable URDF tree
sphere_model.py clearance, costs, and swept spheres
sphere_optimize.py pose and trajectory repair
sphere_dataset.py seeded PyBullet holdout generation
sphere_benchmark.py measured baseline comparison
sphere_visualize.py headless model and correction rendering
scripts/
generate_sphere_dataset.py dataset entry point
benchmark_spheres.py benchmark entry point
correct_sphere_pose.py repair demo
render_sphere_model.py sphere-model renderer
tests/ kinematics, geometry, gradient, and optimizer tests
The legacy learned-field modules remain in place for reproducible baseline comparisons.
The final local verification for this revision:
10 passedwithpytest.- Python source compiled successfully with
compileall. - Maximum observed FK transform disagreement versus PyBullet:
2.446e-7. - Independent 20,000-pose holdout: no false-safe sphere classifications observed.
- Both repaired trajectory cases: zero collisions across 301 dense PyBullet samples.
Exact measured outputs are generated into artifacts/reports/ by the benchmark
script. Results may vary slightly with dependency and CPU differences.
- Sphere geometry can be conservative or omit mesh detail. Padding must be recalibrated for any robot geometry revision, gripper state, or attached tool.
- World support is currently static geometric primitives; live depth/ESDF mapping is not implemented.
- Linear task-space sphere sweeps approximate rather than exactly model revolute-link swept volumes.
- CPU repair takes seconds, not cuRobo's GPU-scale milliseconds.
- Hardware use additionally requires controller-tracking margins, emergency stops, and an independent certified safety system.
- Sundaralingam et al., cuRobo: Parallelized Collision-Free Minimum-Jerk Robot Motion Generation, arXiv:2310.17274v2.
- Official implementation: NVlabs/curobo.
configs/franka_spheres.yamlis adapted from cuRoboV2's Apache-2.0 Franka configuration and retains source-revision and SPDX attribution.- The retained learned baseline was inspired by Li et al., PoseShield: Neural Collision Fields for Human Self-Collision Resolution.
Apache License 2.0. See LICENSE. This project includes an attributed, adapted configuration from cuRoboV2 under the same license.
The SphereShield C++17 analyzer evaluates a fixed 100-example self-collision export, checks every sphere-pair clearance against Python, reports errors against independent PyBullet labels, and groups 16 neural/geometric disagreements. Includes CMake/CTest, a reproducible benchmark, and a checked-in sample report. Read its scope and limitations before interpreting behavior or performance results.