eanswer / diffhand

[RSS 2021] An End-to-End Differentiable Framework for Contact-Aware Robot Design

DiffRedMax (previously DiffHand)

This repository contains the simulator developed for the paper An End-to-End Differentiable Framework for Contact-Aware Robot Design (RSS 2021) and Efficient Tactile Simulation with Differentiability for Robotic Manipulation (CoRL 2022).

DiffRedMax is a differentiable simulator with penalty-based contact model and supports implicit time integration. It also supports simulating dense tactile force field of both normal and shear directional tactile forces. It also provides the analytical first-order simulation gradients with respect to all the control input and simulation parameters (including kinemactics and dynamics parameters).

In An End-to-End Differentiable Framework for Contact-Aware Robot Design, we propose a fully differentiable pipeline to jointly optimize the morphology and control of manipulator robots. At the core of the framework is a deformation-based morphology parameterization and a differentiable simulation.

The framework itself is general and not limited to manipulator robots, we select the case study of manipulator robots because of its complexity and contact-rich nature. Welcome to try our code on any other types robots as well.

Installation

We provides two methods for installation of the code. Install on local machine and Install by Docker.

Option 1: Install on Local Machine

Operating System: tested on Ubuntu 16.04 and Ubuntu 18.04

1. Clone the project from github: git clone https://github.com/eanswer/DiffHand.git --recursive .

2. Install CMake >= 3.1.0: official instruction for cmake installation

3. build conda environment and install simulation

   cd DiffHand
   conda env create -f environment.yml
   conda activate diffhand
   cd core
   python setup.py install
   

4. Test the installation

   cd examples
   python test_redmax.py
   

   If you see a simulation rendering with a two-link pendulum as below, you have successfully installed the code base.

   

Option 2: Install by Docker

We provide a docker installation in the docker folder. Follow the readme instruction in docker folder to complete the installation.

Code Structure

There are two main components of the code base:

• Differentiable RedMax: core. The differentiable redmax is based off RedMax and further makes if fully differentiable. It provides the simulation derivatives w.r.t. both simulation parameters (kinematics- and dynamics-related parameter) and control actions. It is implemented in C++ for computing efficiency. We provide a simulation document for mathematical details of our differentiable RedMax.
• Morphology and Control Co-Optimization: examples/DiffHand. The examples in RSS 2021 paper. We build an end-to-end differentiable framework to co-optimize both the morphology and control of manipulators. We use L-BFGS-B as our default gradient-based optimizer and also provides the source code for the gradient-free baseline methods.

Run the Code

It is recommended to try out the scripts in play with redmax simulation first if you would like to get familiar with simulation interface.

Run the examples in the DiffHand paper

We include the four co-design tasks from the paper in the examples/DiffHand folder.

• Finger Reach
• Rotate Cube
• Flip Box
• Assemble

To run the L-BFGS-B optimization with our deformation-based design parameterization, you can enter the corresponding folder and run demo.sh under the folder. For example, to run Finger Reach,

cd examples/DiffHand/rss_finger_reach
bash demo.sh

Run batch experiments of baseline algorithms

We include the gradient-free baselines (except RL) and the control-only baseline in this repository. For the RL baseline, we use the released code from Luck et al with some modifications to our proposed morphology parameterization.

To run the baseline algorithms or our method in a batch mode, enter the corresponding folder and run run_batch_experiments.py. For example, to run Flip Cube with CMA-ES,

cd examples/rss_finger_flip
python run_batch_experiments.py --method CMA --num-seeds 5 --num-processes 5 --save-dir ./results/

Play with redmax simulation

We provide several examples to test the forward simulation and its differentiability.

• examples/test_redmax.py provides the script to show how to run forward simulation and rendering. It can be easily executed by:

  python test_redmax.py --model hand_sphere
  

  You are expected to see the rendered simulation as below:

  

  Here, you can also try other models provided in assets folder (models are described by xml configuration files).

• examples/test_finger_flick_optimize.py provides an example for using the backward gradients of the simulation. In this example, we use gradient-based optimization to optimize the control sequence of a pendulum finger model to flick a cube to a target location. Run it by:

  python test_finger_flick_optimize.py
  

  The initial control sequence is shown first and you can press [Esc] to close the rendering and start the optimization. After successful optimization, you will see a rendering as below:

  

• examples/test_tactile_sim.py provides an example for simulating the dense tactile force field of a rolling ball experiment. Run it by:

  python test_tactile_sim.py --render
  

  It will first show two windows (as shown first row below) showing animated depth map of normal tactile force field (left) and animated tactile force field (right). Then it will show the simulation animation (second row).

  

  

Citation

If you find our papers or code is useful, please consider citing:

@INPROCEEDINGS{Xu-RSS-21, 
    AUTHOR    = {Jie Xu AND Tao Chen AND Lara Zlokapa AND Michael Foshey AND Wojciech Matusik AND Shinjiro Sueda AND Pulkit Agrawal}, 
    TITLE     = {{An End-to-End Differentiable Framework for Contact-Aware Robot Design}}, 
    BOOKTITLE = {Proceedings of Robotics: Science and Systems}, 
    YEAR      = {2021}, 
    ADDRESS   = {Virtual}, 
    MONTH     = {July}, 
    DOI       = {10.15607/RSS.2021.XVII.008} 
} 

@INPROCEEDINGS{xu2022efficient,
    TITLE     = {Efficient Tactile Simulation with Differentiability for Robotic Manipulation},
    AUTHOR    = {Jie Xu and Sangwoon Kim and Tao Chen and Alberto Rodriguez Garcia and Pulkit Agrawal and Wojciech Matusik and Shinjiro Sueda},
    BOOKTITLE = {6th Annual Conference on Robot Learning},
    YEAR      = {2022},
    URL       = {https://openreview.net/forum?id=6BIffCl6gsM}
} 

diffhand's Issues

Using this repository

Hey,

I am interested in using this repo as well as your paper for our research.

Could you maybe provide a quickstart guide on how to run this code with a custom hand-configuration and custom skin-configuration. We would like to run the simulations using Isaac Sim / Gym for RL purposes.

Thanks and best,
Oliver

XML Modeling Documentation

I'm really impressed by this project, but I'm wondering where I can find more information about the XML input to the simulation. Where can I find a description of the different expected XML fields that are supported by the RedMax Simulation object? I can see the code that is parsing the XML data, but I would love some reference material if it is available. How did you know what to put in the XML files that you in your assets folder?

Look up poses of objects

I would like to look up the pose of an object in the simulator. When I attempt this using get_joint_q it does not match up with external validation (Open3D). In the animations below I would expect the red mesh (right visual) to match up with the end location in the redmax replay but this is not the case

Redmax	Open3D (Start location ✔️ End location ❌ )

Questions

1. Is this the correct function to use? I see there are other variants get_joint_q(..., world_frame=True), get_body_E0i. It's not clear which one to use
2. Am I not using the result correctly? I was thinking the result from get_joint_q could be relative to the start location but after applying that it still didn't look right

This example uses an object from this dataset

import numpy as np
import open3d as o3d
import redmax_py as redmax
from scipy.spatial.transform import Rotation

def translation_euler_angles_to_matrix(translation, euler_angles):
    T = np.eye(4)
    T[:3, :3] = Rotation.from_euler("xyz", euler_angles).as_matrix()
    T[:3, -1] = translation

    return T

np.random.seed(12)
translation = np.array([0, 0, 4.0])

euler_angles = np.random.rand(3)
quaternion = Rotation.from_euler("xyz", euler_angles).as_quat()
# Convert from XYZW -> WXYZ
quaternion = np.roll(quaternion, 1)

translation_string = " ".join([str(x) for x in translation])
quaternion_string = " ".join([str(x) for x in quaternion])

xml_string = f"""
<redmax model="assemble">
<option integrator="BDF1" timestep="1e-3" gravity="0. 0. -9.8"/>
<ground pos="0 0 0" normal="0 0 1"/>
<default>
    <ground_contact kn="1e6" kt="1e3" mu="0.8" damping="5e1"/>
    <general_SDF_contact kn="1e5" kt="1e3" mu="0.0" damping="3e1" />
</default>
<robot>
    <link name="part">
        <joint name="part" type="free3d-euler" axis="0. 0. 0." pos="{translation_string}" quat="{quaternion_string}" frame="WORLD" damping="0"/>
        <body name="part" type="SDF" filename="assets/joint_assembly/00000/0.obj" pos="0 0 0" quat="1 0 0 0" scale="1 1 1" transform_type="OBJ_TO_JOINT" density="1" dx="0.1" mu="0"/>
    </link>
</robot>
<contact>
    <ground_contact body="part"/>
</contact>
</redmax>
"""

simulation = redmax.Simulation(xml_string, "")
simulation.reset()
simulation.forward(5000)

# Read translation and euler angles from sim
translation_euler_angles = simulation.get_joint_q("part")
simulation.replay()

# Transform the mesh to the requested start position
start_location_mesh = o3d.io.read_triangle_mesh(object_file)
start_pose = translation_euler_angles_to_matrix(translation, euler_angles)
start_location_mesh.transform(start_pose)

# Transform the mesh to the expected end position
end_location_mesh = o3d.io.read_triangle_mesh(object_file)
end_pose = translation_euler_angles_to_matrix(translation_euler_angles[:3], translation_euler_angles[3:])
end_location_mesh.transform(end_pose)

o3d.visualization.draw_geometries(
    [
        # End mesh is red, start mesh is green
        end_location_mesh.paint_uniform_color((1, 0, 0)),
        start_location_mesh.paint_uniform_color((0, 1, 0)),
        # Ground plane and coordinate frame for reference
        o3d.geometry.TriangleMesh.create_coordinate_frame(),
        o3d.geometry.TriangleMesh.create_box(width=10, height=10, depth=0.0001)
    ]
)

C++ design (hanging pointers)

It is not clear what c++ design is followed for the project.

How do you deal with free hanging pointers? Is the library meant to be used only through the python interface? Does pybind11 take care of the free hanging pointers?

Simulation replay takes forever

Thank you for the great work!

I am trying to get familiar with RedMaxDiff and noticed that rendering simulated trajectories takes forever (<=1 fps for hand-sphere).
Whereas, simulating itself is very fast (471 fps for hand-sphere and 10k+ fps for finger-torque).

Is that normal? Am I doing something wrong?

Best, Mikel

Broken link to collision documentation

Hi, I would like to understand more about the way collisions are handled, and found a comment (in the file BodyCuboid.cpp) that refers to the following document: https://www.overleaf.com/project/5cd0a78e0e41fe0f8632a42a

However, access to the link seems to be restricted. Could you please provide a working link?

Thanks!

Does it support sdf body type?

Could you kindly let me know if it supports sdf bodies? I am trying to implement "Assemble them all" : https://github.com/yunshengtian/Assemble-Them-All and it uses sdf. When I run the code, I run into an error thrown by simulation potentially because of not supporting SDF. I am wondering how to solve this.