OrigamiTentacles

Paper: Stochastic Entanglement of Deterministic Origami Tentacles for Robust Robotic Grasping

Simulation and modeling of origami tentacle grippers. The repository contains two complementary models:

1. Kinematic (range-of-motion) model — a geometric folding model that predicts the 3D shape and centerline curvature of a tentacle from its origami fold pattern and how far its actuation string is pulled. Entry point: tentacle_ROM_simulator_3D.py, backed by the folding-angle solver solve_folding_angle.py.

2. Dynamic Cosserat-rod simulation — a physics simulation (built on PyElastica) of an array of soft rods that fold toward the target curvatures produced by the kinematic model, optionally grasping a rigid object. Entry point: run_multi_joint_simulation.py.

The dynamic model reuses the kinematic model's geometry (build_tentacle) to generate its target curvature field, so the two parts are connected end to end.

Repository layout

File	Role
tentacle_ROM_simulator_3D.py	Kinematic main — interactive 3D folding GUI
solve_folding_angle.py	Folding-angle solver (kinematic backend)
run_multi_joint_simulation.py	Dynamic main — Cosserat-rod simulation + animation
Tentacle_env.py	PyElastica simulator class + callbacks
elastica_ext.py	Custom PyElastica extensions used for curvature-following and topology routines
helix_shape.py	Helical target-curvature generators
utils.py	Geometry helpers, data I/O, visualization dict builder
qt_visualizer.py	Interactive 3D animation (vispy + PyQt5)
archive/	Older / experimental scripts and alternate viewers, kept for reference

The project uses the stock pyelastica package and keeps project-specific additions in elastica_ext.py, so no custom elastica fork is required.

Setup

Tested with Python 3.11 in a conda environment named python311.

conda create -n python311 python=3.11
conda activate python311
pip install -r requirements.txt

Quick start

1. Kinematic model (interactive folding GUI)

python tentacle_ROM_simulator_3D.py

Opens a Matplotlib 3D window with sliders for the fold angles (Phi1, Phi2), tentacle Width, Percent Folded, actuation-hole position, and Taper ratio. Dragging the sliders re-solves the fold and redraws the tentacle shape in real time.

2. Dynamic Cosserat-rod simulation

python run_multi_joint_simulation.py

Runs the physics simulation of an 8-rod tentacle folding toward the kinematic target curvature, then opens a vispy/PyQt5 animation window.

Useful flags:

Flag	Default	Description
--phi1, --phi2	90, 80	Fold angles feeding the kinematic target
--taper	0.5	Rod taper ratio
--object	0	Grasped-object configuration (0–5)
--plot_video	True	Open the 3D animation when finished
--save_data	True	Pickle the simulation to <filename>.dat
--compute_topology	True	Compute link/twist/writhe (slow; post-processing)
--gravity	False	Enable gravity
--progress_bar	True	Show the integration progress bar
--random_seed	42	Random seed for per-rod actuation timing

Example — quick run without the GUI or topology cost:

python run_multi_joint_simulation.py --plot_video False --compute_topology False

Citation

If you use this repository or its models in your work, please cite:

Boron, A., Zheng, B., Zhou, Z., Naughton, N., & Li, S. (2025). Stochastic Entanglement of Deterministic Origami Tentacles for Robust Robotic Grasping. Advanced Science. https://doi.org/10.1002/advs.76810

License

See LICENSE.