MorphIt: Flexible Spherical Approximation of Robot Morphology

May 6, 2026 · View on GitHub

MorphIt is a novel algorithm for approximating robot morphology using spherical primitives that balances geometric accuracy with computational efficiency. Unlike existing approaches that rely on either labor-intensive manual specification or inflexible computational methods, MorphIt implements an automatic gradient-based optimization framework with tunable parameters that provides explicit control over the physical fidelity versus computational cost tradeoff.

Key Features

Automatic spherical approximation of any mesh with gradient-based optimization
Flexible configuration for different task requirements
Fast computation - up to 2 orders of magnitude faster than baseline methods
Physical fidelity - better mesh approximation with fewer spheres
Easy integration - generates URDF files compatible with popular robotics simulators

Quick Start

Setup Environment

uv venv venv-morphit --python 3.10
source venv-morphit/bin/activate
uv pip install -r requirements.txt

Compile Helper Module

Compile an efficient helper module used to check whether a point lies inside a mesh:

sudo apt-get install python3.10-dev
cd src
python setup.py build_ext --inplace

This should generate a file such as triangle_hash.cpython-310-x86_64-linux-gnu.so

Run Tests

Test the system to ensure everything is working:

cd src
python test_morphit.py

This runs some tests including imports, configuration, model creation, loss computation, and minimal training to verify the installation.

Run Example

cd src
python main.py

Usage

Basic Usage

from morphit import MorphIt
from config import get_config

# Create configuration
config = get_config("MorphIt-B")  # Balanced configuration
config.model.mesh_path = "path/to/your/mesh.obj"
config.model.num_spheres = 15

# Create and train model
model = MorphIt(config)
tracker = model.train()

# Save results
model.save_results("output.json")

Batch Processing

Process multiple mesh files:

cd src
python morphit_panda.py

Visualization

Visualize sphere packing results:

cd src
python visualize_packing.py results/output/morphit_results.json

Convert to URDF and Visualize the Panda Robot in Drake

Create the sheres, populate the URDF file, then use a simulator like Drake to use your new robot mophology.

cd src
python morphit_panda.py
cd scripts
python create_panda_urdf.py
python run_spherical_panda_drake_example.py

File Overview

Core System

morphit.py - Main MorphIt class implementing the spherical approximation algorithm.
config.py - Configuration management with predefined variants (V, S, B)
losses.py - Loss functions for optimization.
training.py - Training loop and optimization logic
density_control.py - Annealed partial re-packing.

Utilities

inside_mesh.py - Efficient mesh containment checking using Cython
visualization.py - PyVista-based visualization functions
convergence_tracker.py - Training metrics tracking and analysis
logger.py - Evolution logging and rendering thread management

Scripts

main.py - Main example script
test_morphit.py - Comprehensive system tests
morphit_panda.py - Batch processing for Franka Panda robot
visualize_packing.py - Standalone visualization tool
scripts/debug_quick_eval.py - Small evaluation grid (variant × link × sphere count) that re-trains and prints a metrics table; useful for sanity-checking changes against the paper-ordering targets
scripts/ - URDF generation and integration scripts for Drake, CuRobo

Build Files

setup.py - Cython compilation setup
triangle_hash.pyx - Cython implementation for fast mesh queries
triangle_hash.cpp - Generated C++ code

Configuration Variants

MorphIt-V: Volume-focused, conservative approximations for collision avoidance
MorphIt-S: Surface-focused, precise approximations for contact-rich manipulation
MorphIt-B: Balanced approximation for general-purpose applications

Applications

Collision detection and avoidance
Contact-rich manipulation planning
Navigation through cluttered spaces
Whole-body contact planning
Real-time motion generation

Tested on a system with the following requirements

Ubuntu 22.04.5 LTS (recommended)
Python 3.10
CUDA-capable GPU (recommended, for acceleration)

Baselines

Special thanks to

Citation

If you use MorphIt in your research, please cite our paper:

@misc{nechyporenko2025morphit,
      title={MorphIt: Flexible Spherical Approximation of Robot Morphology for Representation-driven Adaptation},
      author={Nataliya Nechyporenko and Yutong Zhang and Sean Campbell and Alessandro Roncone},
      year={2025},
      eprint={2507.14061},
      archivePrefix={arXiv},
      primaryClass={cs.RO},
      url={https://arxiv.org/abs/2507.14061},
}

Acknowledgments

To test our work, we have used several outstanding open-source robotics libraries and tools that have significantly accelerated research and development in robot motion planning, dynamics, and geometry approximation. We gratefully acknowledge the contributions of the following projects:

Motion Planning and Control

cuRobo (NVlabs) – A CUDA-accelerated robotics library providing high-performance motion generation, collision-free trajectory optimization, and inverse kinematics that operates within milliseconds on NVIDIA GPUs.
Drake (Robot Locomotion Group, MIT/Toyota Research Institute) – A comprehensive C++/Python toolbox for model-based design, multibody dynamics simulation, and optimization-based control systems analysis.
IDTO (Toyota Research Institute) – Inverse Dynamics Trajectory Optimization implementation for contact-implicit model predictive control, enabling real-time robotic manipulation and locomotion planning.

Geometric Approximation and Collision Detection

sphere-set-approximation and its parent repository – Algorithms for approximating triangular meshes with minimal-volume sphere sets, useful for efficient collision detection and shape representation.
spheretree (mlund) – A sphere-tree construction toolkit for generating hierarchical sphere representations of polygonal models to accelerate interruptible collision detection.
foam (CoMMA Lab, Purdue University) – A specialized tool for spherical approximation of robot geometry, enabling fast proximity queries and motion planning for complex articulated systems.

License

This project is licensed under the MIT License.