v2.0 of IntPrim

Author: joe-campbell

README.md

@@ -1,44 +1,73 @@
-# intprim
-The Interaction Primitives Python library from the Interactive Robotics Lab at Arizona State University.
+# IntPrim
+The IntPrim library is a Python implementation of Interaction Primitives from the Interactive Robotics Lab at Arizona State University.
+Interaction Primitives are a human-robot interaction (HRI) framework based on imitation learning.
+The objective of this framework is to extract the dynamics of an interaction from a set of example demonstrations, then use the dynamics to infer the future states of both the human and the robot.
+The primary purpose of this library is to enable training and inference using Bayesian Interaction Primitives, however, it also supports Probabilistic Movement Primitives and Particle Filters as a baseline for comparison.
 
-This library implements the Bayesian Interaction Primitives algorithm.
+![](docs/notebooks/media/examples_new.png?raw=true)
 
-## Installation
-To install this library, download the package and in the root directory run:
+This library has been successfully deployed in real-world HRI scenarios involving cooperative object manipulation, shaking hands, hugging, grasping, and more!
+A list of peer-reviewed publications that have utilized this library can be found below.
 
-python setup.py build_ext install --user
+## Features
 
-By default, this will make use of the included cythonized .c files. The .pyx files are included so that the files can be changed and re-compiled, and a vanilla Python implementation is included as well.
+* Train a BIP model from demonstrations
+* Perform recursive inference with an Interaction Primitives model and generate future states
+* Support for inference with Ensemble Bayesian Interaction Primitives, Bayesian Interaction Primitives, Probabilistic Movement Primitives with DTW, and Particle Filter
+* Automatic basis space selection with support for Gaussian, Sigmoidal, and Polynomial functions
+* Automatic computation of the observation noise
+* Comprehensive interactive analysis tools
 
-## Usage
-To run the included examples, in a Python environment run:
+![](docs/notebooks/media/analysis_example.gif?raw=true)
 
-```python
-import intprim as ip
-import intprim.examples
+## Tutorials and Documentation
 
-ip.examples.minimal()
-ip.examples.spatial_robustness()
-ip.examples.temporal_robustness()
-```
+A set of tutorials and documentation about IntPrim has been provided in the following Jupyter Notebooks:
+
+1. [Introduction](docs/notebooks/1_introduction.ipynb)
+2. [Quickstart](docs/notebooks/2_quickstart.ipynb)
+3. [In-depth Tutorial](docs/notebooks/3_indepth_tutorial.ipynb)
+4. [Mathematical Details](docs/notebooks/4_mathematical_details.ipynb)
+
+Additionally, the API and associated documentation can be found here:
 
-The source code for the examples can be viewed under intprim/examples.
+https://ir-lab.github.io/intprim/
 
-Note that in general, spatial noise and temporal noise are at odds with each other in conditioning.
-If you have a lot of spatial noise it will be more difficult to accurately locate the correct phase, and vice versa.
-So applications with lots of spatial noise AND lots of temporal noise may be challenging.
+## Prerequisites
+
+This library has been built and tested on Python 2.7.
+
+The following Python libraries must be installed before IntPrim can be used:
+
+* Numpy
+* Scipy
+* Matplotlib
+* Sklearn
+
+## Installation
+To install this library, download the package and in the root directory run:
+
+python setup.py build_ext install --user
 
 This project is licensed under the MIT license, included in this directory.
 
 ## Feedback
-Questions or comments may be directed to Joseph Campbell at <[email protected]> or Simon Stepputtis at <[email protected]>.
+Questions or comments may be directed to Joseph Campbell at <[email protected]>, Simon Stepputtis at <sstepput@asu.edu>, or Heni Ben Amor <hbenamor@asu.edu>.
 
 http://interactive-robotics.engineering.asu.edu/interaction-primitives/
 
 ## Citation
-If you use this library, please use this citation:
+If you use this library, please cite one of the following papers:
+```
+@InProceedings{campbell2019probabilistic,
+  title={Probabilistic Multimodal Modeling for Human-Robot Interaction Tasks},
+  author={Campbell, Joseph and Stepputtis, Simon and Ben Amor, Heni},
+  booktitle={Robotics: Science and Systems},
+  year={2019}
+}
+```
 ```
-@InProceedings{campbell17a,
+@InProceedings{campbell19bayesian,
   title = {Bayesian Interaction Primitives: A SLAM Approach to Human-Robot Interaction},
   author = {Joseph Campbell and Heni Ben Amor},
   booktitle = {Proceedings of the 1st Annual Conference on Robot Learning},
@@ -54,3 +83,15 @@ If you use this library, please use this citation:
   url = {http://proceedings.mlr.press/v78/campbell17a.html}
 }
 ```
+
+## Used By
+
+This library has been developed by Joseph Campbell at Arizona State University and has been utilized in the following works:
+
+[1] J. Campbell, S. Stepputtis, and H. Ben Amor. Probabilistic Multimodal Modeling for Human-Robot Interaction Tasks. Robotics: Science and Systems (RSS) 2019.
+
+[2] J. Campbell and H. Ben Amor. Bayesian Interaction Primitives: A SLAM Approach to Human-Robot Interaction. Conference on Robot Learning (CoRL) 2017.
+
+[3] J. Campbell, A. Hitzmann, S. Stepputtis, S. Ikemoto, K. Hosoda, and H. Ben Amor. Learning Interactive Behaviors for Musculoskeletal Robots Using Bayesian Interaction Primitives. International Conference on Intelligent Robots and Systems (IROS) 2019.
+
+[4] K. Bagewadi, J. Campbell, and H. Ben Amor. Multimodal Dataset of Human-Robot Hugging Interaction. AAAI Fall Symposium on Artificial Intelligence for Human-Robot Interaction (AI-HRI), November 2019.