Merge pull request #5 from Improbable-AI/qa

Initial release to master

.gitignore

@@ -6,8 +6,12 @@ __pycache__/
 # C extensions
 *.so
 
+docker/requirements.txt
+
+docs/build/*
 # Distribution / packaging
 .Python
+examples/**/*.png
 build/
 develop-eggs/
 dist/
@@ -21,6 +25,7 @@ sdist/
 var/
 wheels/
 *.egg-info/
+.idea/
 .installed.cfg
 *.egg
 MANIFEST
@@ -31,6 +36,9 @@ MANIFEST
 *.manifest
 *.spec
 
+*.patch
+*.pth
+
 # Installer logs
 pip-log.txt
 pip-delete-this-directory.txt
@@ -102,3 +110,6 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# local cudnn resources (large deb file)
+docker/cudnn    

README.md

@@ -1 +1,109 @@
-# airobot
+# AIRobot
+
+AIRobot is a python library to interface with robots. It follows a similar architecture from [PyRobot](https://pyrobot.org).
+- [Citation](#citation)
+- [Installation](#installation)
+- [Supported Robots](#supported-robots)
+- [Getting Started](#getting-started)
+- [Credits](#credits)
+- [Build API Docs](#build-api-docs)
+- [Run Tests](#run-tests)
+- [License](#license)
+- [Coding Style](#coding-style)
+
+## Citation
+
+If you use AIRobot in your research, please use the following BibTeX entry.
+```
+@misc{airobot2019,
+  author =       {Tao Chen and Anthony Simeonov and Pulkit Agrawal},
+  title =        {{AIRobot}},
+  howpublished = {\url{https://github.com/Improbable-AI/airobot}},
+  year =         {2019}
+}
+```
+
+## Installation
+
+### Pre-installation steps for ROS (only required if you want to use the real robot)
+
+#### Option 1:
+If you want to use ROS to interface with robots, please install [ROS Kinetic](http://wiki.ros.org/kinetic/Installation/Ubuntu) first.
+
+If you want to use ROS for UR5e robots, please install [ur5e driver](https://github.com/Improbable-AI/ur5e_robotiq_2f140). 
+
+If you are using RealSense cameras, please follow the instructions [here](https://github.com/IntelRealSense/realsense-ros#installation-instructions) or [here](https://github.com/Improbable-AI/camera_calibration/tree/qa).
+
+#### Option 2:
+Use the dockerfile provided in this library. Checkout the [instructions](https://github.com/Improbable-AI/airobot/blob/master/docker) for docker usage. **Docker is not needed if you just want to use the pybullet simulation environment.**
+
+### Install AIRobot
+
+You might want to install it in a virtual environment. 
+
+If you are using ROS, you can use [virtualenv](https://virtualenv.pypa.io/en/latest/installation/). Note that Anaconda doesn't work well with ROS. And only Python 2.7 is recommended for ROS at this point.
+
+If you only want to use the robots in the PyBullet simulation environment, then you can use Python 2.7 or Python 3.7. And you can use either [virtualenv for Python 2.7](https://virtualenv.pypa.io/en/latest/installation/), [venv for Python 3.7](https://docs.python.org/3.7/tutorial/venv.html) or [Anaconda](https://docs.anaconda.com/anaconda/install/linux/).
+
+```bash
+git clone https://github.com/Improbable-AI/airobot.git
+cd airobot
+pip install -e .
+```
+
+## Supported Robots
+* [UR5e](https://www.universal-robots.com/products/ur5-robot/) with ROS
+* [UR5e](https://www.universal-robots.com/products/ur5-robot/) in PyBullet
+* [ABB YuMi](https://new.abb.com/products/robotics/industrial-robots/irb-14000-yumi) in PyBullet
+
+If you want to use [Sawyer](https://www.rethinkrobotics.com/sawyer) or [LoCoBot](https://locobot-website.netlify.com/), you can use [PyRobot](https://pyrobot.org).
+
+## Getting Started
+A sample script is shown below. You can find more examples [here](https://github.com/Improbable-AI/airobot/examples)
+
+```python
+from airobot import Robot
+# create a UR5e robot in pybullet
+robot = Robot('ur5e',
+              pb=True,
+              pb_cfg={'gui': True})
+robot.arm.go_home()
+robot.arm.move_ee_xyz([0.1, 0.1, 0.1])
+```
+
+## Credits
+**AIRobot** is maintained by the Improbable AI team at MIT. It follows a similar architecture in [PyRobot](https://pyrobot.org). Contributors include:
+* [Tao Chen](https://taochenshh.github.io/)
+* [Anthony Simeonov](https://anthonysimeonov.github.io/)
+* [Pulkit Agrawal](http://people.csail.mit.edu/pulkitag/)
+
+
+## Build API Docs
+
+Run the following commands to build the API webpage.
+
+```bash
+cd docs
+./make_api.sh
+```
+
+Then you can use any web browser to open the API doc (**`docs/build/html/index.html`**)
+
+## Run tests
+
+[pytest](https://docs.pytest.org/en/latest/) is used for unit tests. TODO: more test cases need to be added.
+```bash
+cd airobot/tests
+./run_pytest.sh
+```
+
+## License
+MIT license
+
+## Coding Style
+
+AIRobot uses [Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for formatting docstrings. We use [Flake8](https://pypi.org/project/flake8/) to perform additional formatting and semantic checking of code.
+
+
+
+

docker/README.md

@@ -0,0 +1,139 @@
+# AIRobot Docker Instructions
+
+- [Dependency Installation](#dependencies)
+- [Pull the Pre-Built Image](#pulling-the-pre-built-images)
+- [Usage](#usage)
+- [Build the Image Locally](#build-the-image-locally)
+
+### Dependencies
+System dependencies:
+- Linux OS (tested on Ubuntu 16.04 and 18.04)
+- Nvidia GPU
+- Nvidia driver version >= 418.39
+
+#### Local Docker engine setup
+Install [Docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/) (you may want to configure your user permissions so you don't have to use sudo with every docker command -- see [here](https://docs.docker.com/install/linux/linux-postinstall/))
+```
+sudo apt-get remove docker docker-engine docker.io containerd runc
+sudo apt-get update
+sudo apt-get install \
+    apt-transport-https \
+    ca-certificates \
+    curl \
+    gnupg-agent \
+    software-properties-common
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
+sudo add-apt-repository \
+   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
+   $(lsb_release -cs) \
+   stable"
+sudo apt-get update
+sudo apt-get install docker-ce docker-ce-cli containerd.io
+```
+
+Install [nvidia-container-runtime](https://github.com/nvidia/nvidia-container-runtime#docker-engine-setup) (main instructions from the link shown below)
+
+```
+curl -s -L https://nvidia.github.io/nvidia-container-runtime/gpgkey | \
+  sudo apt-key add -
+distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
+curl -s -L https://nvidia.github.io/nvidia-container-runtime/$distribution/nvidia-container-runtime.list | \
+  sudo tee /etc/apt/sources.list.d/nvidia-container-runtime.list
+sudo apt-get update
+sudo apt-get install nvidia-container-runtime
+```
+Follow the steps for creating a drop in file to register the runtime with docker
+
+```
+sudo mkdir -p /etc/systemd/system/docker.service.d
+sudo tee /etc/systemd/system/docker.service.d/override.conf <<EOF
+[Service]
+ExecStart=
+ExecStart=/usr/bin/dockerd --host=fd:// --add-runtime=nvidia=/usr/bin/nvidia-container-runtime
+EOF
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+```
+
+## Pulling the Pre-Built Images
+The image is set up with CUDA 10.1, cuDNN 7.6, and PyTorch 1.3 installed (```airobot-cuda-dev```)
+```
+docker pull anthonysimeonov/airobot-cuda-dev:latest
+```
+
+
+## Usage
+### Running the container
+Open two terminals
+
+#### Terminal 1
+In the first terminal, from within this directory (```/path/to/airobot/docker/```), run the ```run_image.bash``` script to launch the container. You will enter a terminal session from within the container after launching.
+```
+./run_image.bash
+```
+
+then setup ```airobot``` from within the container
+```
+cd /home/improbable/airobot/
+pip install -e .
+```
+
+#### Termainal 2
+From the second terminal, run the following bash script to allow the container access to your local X server for visualization (there are better ways to do this, but we keep this relatively secure by only providing access to xhost to the specific system we want)
+
+```
+./visualize_access.bash
+```
+
+You can now run programs from within the container that are GUI-based, and have the GUI appear
+on your host screen (i.e. Gazebo, RViz, PyBullet)
+
+First, enter the container by starting a new interactive terminal session (```$CONTAINER_ID``` can usually be found by tab completing the below command, or viewing the information about the running containers by running ```docker ps```) and source the catkin workspace that has been built with the following commands
+```
+docker exec -it $CONTAINER_ID bash
+```
+(now inside of the container)
+```
+cd /root/catkin_ws/
+source devel/setup.bash
+```
+
+### Run the simulated UR robot in Gazebo
+
+Then, for instance, you can launch a simulated UR5e in Gazebo, and start MoveIt! with it, with the following command
+
+```
+roslaunch ur5e_bringup ur5e_start.launch sim:=true
+```
+
+Or you can launch a simulated UR5e in PyBullet with ```airobot``` with the following commands
+```
+cd /home/improbable/airobot/examples/ur5e/sim/
+python joint_position_control.py
+```
+
+### Run the real UR robot
+
+You can also connect to the real robot and control it via the ```airobot``` API functions (```<robot_ip>``` can be viewed from the PolyScope interface on the real robot's teach pendant. First bringup the connection to the robot with the following command, after connecting to the local network via ethernet cable (more instructions avaiable [here](https://github.com/Improbable-AI/ur5e)).
+
+```
+roslaunch ur5e_bringup ur5e_start.launch robot_ip:=<robot_ip>
+```
+Then run the following command to run the ```joint_position_control``` example (from a new terminal, either using ```tmux``` or by entering the container from a new local terminal with the same ```docker exec``` command above)
+```
+cd /home/improbable/airobot/examples/ur5e/real/
+python joint_position_control.py
+```
+
+## Build the Image Locally
+From within this directory (```/path/to/airobot/docker/```), run the following command to build the image. This will take quite a bit of time if you have not done it locally before. Please see the ```docker_build.py``` script for additional arguments that can be passed to the build command (i.e. image name, which file to use, dry run, etc.)
+```
+python docker_build.py
+```
+
+If you want to use a different dockerfile than the specified default, run
+```
+python docker_build.py -f /path/to/dockerfile.dockerfile
+```
+
+(if you are building the image locally you will need to set up your machine with public keys linked to your github account for cloning private repositories required during building)

docker/docker_build.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+
+from __future__ import print_function
+
+import argparse
+import os
+import shutil
+
+
+def execute_build(args):
+    """
+    Create docker build command based on user input arguments
+    and execute the command
+
+    Args:
+        args (argparse.Namespace): Build arguments
+    """
+    if not os.path.exists(args.docker_file):
+        print('Dockerfile %s not found! Exiting' % args.docker_file)
+        return
+
+    # copy requirements file from parent into docker folder
+    cwd = os.getcwd()
+    shutil.copy(cwd + '/../requirements.txt', cwd)
+
+    cmd = 'DOCKER_BUILDKIT=1 docker build '
+    cmd += '--ssh default '
+    cmd += '--network=host '
+    if args.no_cache:
+        cmd += '--no-cache '
+    cmd += '-t %s -f %s .' % (args.image, args.docker_file)
+
+    print('command = \n\n', cmd)
+
+    if not args.dry_run:
+        os.system(cmd)
+
+    # removing copied requirements file from docker/ directory
+    os.remove('requirements.txt')
+
+
+if __name__ == '__main__':
+    default_image_name = "airobot-cuda-dev"
+
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument('-i', '--image', type=str,
+                        default=default_image_name,
+                        help='name for new docker image')
+
+    parser.add_argument('--no_cache', action='store_true',
+                        help='0 if should build without using cache')
+
+    parser.add_argument('-f', '--docker_file', type=str,
+                        default='ur5e_2f140_cuda.dockerfile',
+                        help='which Dockerfile to build from')
+
+    parser.add_argument('-d', '--dry_run', action='store_true',
+                        help='1 if we should only print the build command '
+                             'without executing')
+
+    args = parser.parse_args()
+    execute_build(args)

docker/entrypoint.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -e
+
+# setup ros environment
+source "/root/catkin_ws/devel/setup.bash"
+
+eval "bash"
+
+exec "$@"