Introduction¶

What GraspIt! is¶

GraspIt! was created to serve as a tool for grasping research. It is a simulator that can accommodate arbitrary hand and robot designs. It can also load objects and obstacles of arbitrary geometry to populate a complete simulation world. The GraspIt! engine includes a rapid collision detection and contact determination system that allows a user to interactively manipulate a robot or an object and create contacts between them. Once a grasp is created, one of the key features of the simulator is the set of grasp quality metrics. Each grasp is evaluated with numeric quality measures, and visualization methods allow the user to see the weak point of the grasp and create arbitrary 3D projections of the 6D grasp wrench space.

In our experience, we have found that GraspIt! usually serves one of two purposes. First, it can be used as a development tool, to execute and test various robot control algorithms. In this sense, it serves as a replacement for the real world: in simulation, an algorithm can be tested on many hand designs, many objects and obstacle configurations, at no cost and much faster than in the real world. Second, GraspIt! can be used as a computational platform that backs up a robot that does operate in the real world. For example, a real robot can acquire a model of a target object, then use GraspIt! to quickly evaluate multiple grasping or manipulation scenarios. Often, these scenarios are also combined and the same GraspIt! setup used for development of an algorithm can also be used for computations during real life execution.

GraspIt! has many features that help accomplish these roles; all of these features are documented in the second part of this manual. The most commonly used include the contact detection and grasp quality metrics mentioned above, the dynamics engine and the grasp planning capabilities. The dynamics engine within GraspIt! computes the motions of a group of connected robot elements, such as an arm and a hand, under the influence of controlled motor forces, joint constraint forces, contact forces and external forces. This allows a user to dynamically simulate an entire grasping task, as well as test custom robot control algorithms. The grasp planning algorithms rely on the simulated environment to quickly evaluate many hand postures, and find those that lead to stable grasps. There are many possible implementations of this concept; the planners that are included with GraspIt! can usually find multiple stable grasps of an object in less than 1 minute, taking into account obstacles and other constraints.

Overall, GraspIt! is an open-source virtual environment for simulating robotic grasping tasks accompanied by a number of analysis and development tools. It has been developed in C++ using many other open-source libraries, and is cross-platform, tested on both Windows and Ubuntu Linux.

What GraspIt! is NOT¶

GraspIt! is not an off-the-shelf product. It is rather a large codebase that is the result of many years of research and development in the Robotics Lab at Columbia University. The tools included can greatly help in the development and testing of new algorithms and approaches. However, we have often found that most new interesting problems can not be completely addressed by applying these tools exactly as they are. It is very possible that, in the process, you will find yourself needing various changes or additions to the simulator; these might be bigger or smaller depending on your problem. This means that you might have to get your hands dirty and tinker with the code itself, which we encourage you to do. We have done our best to create clean, robust and well-documented code. However, we are not a large team of product development software engineers; rather, we are a small group of robotics researchers. As a result, do not be surprised if you find parts of the code that can be improved.

About this manual¶

This manual is divided into two parts. The first one, containing Chapters 1 through 4, is an introduction to the GraspIt! environment, covering the essential aspects for loading and populating a GraspIt! world and interacting with it. The references to the source code are kept at a minimum. In the second part, containing Chapters 5 through 17, we discuss the GraspIt! advanced features, or the tools that it offers for solving various problems. Here we overlap discussions of the simulator as a final product with discussion of the source code itself. We also introduce a number of features of GraspIt! that are not completely finished yet, and might not be very robust, but have been included in the distribution in the hope you might find them useful. Such features will be marked by the qualifier “Under Development” - only use them if you’re not afraid of delving inside the code to get the most out of them and fix an occasional bug.

Please note that, much like the code itself, this manual is under continuous development. There are many aspects that it does not touch at all, or explains too briefly. If there is a topic that you found particularly confusing, or you would like to see expanded, we would appreciate your feedback.

Troubleshooting and contact¶

GraspIt! includes two main resources: this manual, and a complete code reference. We have put a lot of work into both of them, and we strongly encourage you to try using them to solve your problem before contacting us. If that fails, we will try to provide support via email; write us at graspit@lists.cs.columbia.edu. General comments on the simulator, and any patches or improvements to the code are always appreciated.

Authors and acknowledgements¶

Andrew Miller and Matei Ciocarlie are the main authors of GraspIt!, having designed most of its features and implemented most of the code. GraspIt!’s current main developers and maintainers are Matei Ciocarlie, Jake Varley and Jon Weisz. The GraspIt! simulator was developed in the Robotics Lab, Department of Computer Science, Columbia University, under the guidance of Prof. Peter Allen.

Many people contributed to GraspIt!, either in the form of new ideas, suggestions or guidance, or by implementing new features in code. These include: Prof. Jeff Trinkle, who provided valuable advice on the dynamics system; Danica Kragic who developed the real time vision system allowing GraspIt! to work with real robots; Prof. Henrik Christensen and Steffen Knoop who helped build the automatic grasp planner; Raphael Pelossof, who implemented the first GraspIt! based machine learning approach; Claire Lackner, who helped design and implement the soft finger contact algorithms; Corey Goldfeder, who was the driving force behind the Columbia Grasp Database (CGDB) which is now integrated with GraspIt!; Hao Dang who wrote the GraspIt! - CGDB interface, and made many other valuable contributions to the codebase; Norases Vesdapunt, who wrote the XML interface for data files. Jennifer Buehler converted the build system from qmake to cmake among other valuable contributions to the codebase. We would like to thank all of them for their valuable contributions.

Thanks to Prof. Gerd Hirzinger and Dr. Max Fischer, Prof. Contantinos Mavroidis and Katheryn DeLaurentis, Dr. Myron Diftler, Marco Reichel, the Shadow Robot Company, Marius Stuecheli and Dr. Tamim Asfour for providing us with models of their robotic hands. The M7 Robot geometry was provided courtesy of SRI International. The Schunk Dexterous Hand model was provided courtesy of SCHUNK GmbH Co. The RobotIQ hand model was provided courtesy of the RobotIQ Company.

We would also like to thank Willow Garage for their support towards this new, GPL-licensed release, and for their commitment towards open-source and freely available code.