Merge pull request #411 from BYU-PCCL/develop

Release 0.3.1

.dockerignore

@@ -0,0 +1,21 @@
+*.pyc
+*.xml
+*.xmi
+.idea/
+.vscode/
+.tflogs/
+worlds/
+!docs/worlds
+build/
+env/
+venv/
+docs/_build
+dist/
+holodeck.egg-info/
+.tox
+.pytest_cache
+pip-wheel-metadata
+!tests/worlds
+docker
+.dockerignore
+.github

.github/workflows/dockerimages.yml

@@ -0,0 +1,44 @@
+name: Docker build
+
+on:
+  push:
+    branches: [ docker-improvement ]
+  pull_request:
+    branches: [ docker-improvement ]
+
+jobs:
+
+  build-images:
+    env:
+      IMAGE_NAME: pccl/holodeck
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Login to DockerHub registry
+      run: |
+        echo $DOCKER_PASSWORD | docker login -u $DOCKER_USERNAME --password-stdin
+      env:
+        DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+        DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+
+    - name: Build base image
+      working-directory: ./docker
+      run: |
+        docker build -t ${IMAGE_NAME}:base -f ./Dockerfile ..
+        
+    - name: Build default worlds image
+      working-directory: ./docker
+      run: docker build -t ${IMAGE_NAME}:default-worlds -f ./Dockerfile_default_worlds ..
+
+    - name: Build dexterity image
+      working-directory: ./docker
+      run: docker build -t ${IMAGE_NAME}:dexterity -f ./Dockerfile_dexterity ..
+
+    - name: Push images
+      run: |
+        docker push ${IMAGE_NAME}:base
+        docker push ${IMAGE_NAME}:default-worlds
+        docker push ${IMAGE_NAME}:dexterity

README.md

@@ -20,7 +20,7 @@ Holodeck is a high-fidelity simulator for reinforcement learning built on top of
 ## Installation
 `pip install holodeck`
 
-(requires Python 3)
+(requires >= Python 3.5)
 
 See [Installation](https://holodeck.readthedocs.io/en/latest/usage/installation.html) for complete instructions (including Docker).
 
@@ -66,9 +66,7 @@ If you want to access the data of a specific sensor, import sensors and
 retrieving the correct value from the state dictionary:
 
 ```python
-from holodeck.sensors import Sensors
-
-print(state[Sensors.LOCATION_SENSOR])
+print(state["LocationSensor"])
 ```
 
 ## Multi Agent-Environments
@@ -80,7 +78,10 @@ Calls to [`step`](https://holodeck.readthedocs.io/en/latest/holodeck/environment
 action has been provided, [`tick`](https://holodeck.readthedocs.io/en/latest/holodeck/environments.html#holodeck.environments.HolodeckEnvironment.tick) will advance the simulation forward. The action is persisted until another call to `act` provides a different action.
 
 ```python
-env = holodeck.make('CyberPunkCity-Follow')
+import holodeck
+import numpy as np
+
+env = holodeck.make("CyberPunkCity-Follow")
 env.reset()
 
 # Provide an action for each agent
@@ -89,16 +90,18 @@ env.act('nav0', np.array([0, 0, 0]))
 
 # Advance the simulation
 for i in range(300):
-    # The action provided above is repeated
-    s = env.tick()
+  # The action provided above is repeated
+  states = env.tick()
 ```
 
 You can access the reward, terminal and location for a multi agent environment as follows:
 
-``` python
-s['uav0'][Sensors.REWARD]
-s['uav0'][Sensors.TERMINAL]
-s['uav0'][Sensors.LOCATION_SENSOR]
+```python
+task = states["uav0"]["FollowTask"]
+
+reward = task[0]
+terminal = task[1]
+location = states["uav0"]["LocationSensor"]
 ```
 
 (`uav0` comes from the [scenario configuration file](https://holodeck.readthedocs.io/en/latest/packages/docs/scenarios.html))

docker/Dockerfile

@@ -0,0 +1,26 @@
+FROM nvidia/cudagl:9.2-runtime-ubuntu18.04
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 python3-dev ipython3 module-init-tools curl build-essential python3-pip
+
+# OpenCV's runtime dependencies
+RUN apt-get install -y libglib2.0-0 libsm6 libxrender-dev libxext6
+
+RUN pip3 install -U pip setuptools wheel
+
+RUN pip3 install numpy posix_ipc holodeck pytest opencv-python
+
+RUN adduser --disabled-password --gecos "" holodeckuser
+
+WORKDIR /home/holodeckuser/source/holodeck/
+
+# This should be COPY ../ but docker doesn't allow copying files outside the context
+# To copy the project files either run the build command in this directory with the
+# previous directory as the context: docker build -t pccl/holodeck[:tag] -f ./Dockerfile ..
+# or run it from the parent directory and provide the docekr file location
+# docker build -t pccl/holodeck[:tag] -f ./docker/Dockerfile .
+COPY ./ .
+
+USER holodeckuser
+
+CMD ["/bin/bash"]

docker/Dockerfile_default_worlds

@@ -0,0 +1,5 @@
+FROM pccl/holodeck:base
+
+RUN python3 -c 'import holodeck; holodeck.install("DefaultWorlds")'
+
+CMD ["/bin/bash"]

docker/Dockerfile_dexterity

@@ -0,0 +1,5 @@
+FROM pccl/holodeck:base
+
+RUN python3 -c 'import holodeck; holodeck.install("Dexterity")'
+
+CMD ["/bin/bash"]

docker/build_and_tag.sh

@@ -0,0 +1 @@
+docker build -t pccl/holodeck:base -f ./Dockerfile ..

docs/README.md

@@ -0,0 +1,28 @@
+This folder contains holodeck's user-facing documentation (hosted at
+holodeck.readthedocs.io), and is compiled with [Sphinx](http://www.sphinx-doc.org/en/master/).
+
+The documentation can be built locally to preview changes before pushing to
+GitHub.
+
+### Prerequisites
+
+`pip install sphinx autodocsumm sphinx_rtd_theme doc8`
+
+### Building
+
+From this directory,
+```console
+~/dev/holodeck/docs$ make clean && make html
+```
+
+[This VSCode extension](https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext)
+is useful since it allows you to preview the docs without needing to
+compile them.
+
+### Style Note
+
+Pay careful attention to the warnings when you build the docs. The expectation
+is that we have a clean build. This includes
+
+Make sure to have the VSCode extension and doc8 installed you you get proper
+linting.

docs/agents/android-agent.rst

@@ -17,25 +17,40 @@ Description
 An android agent that can be controlled via torques supplied to its joints.
 See :class:`~holodeck.agents.AndroidAgent` for more details.
 
+Control Schemes
+---------------
+**Android Direct Torques** (``0``)
+  A 94 dimensional vector of continuous values representing torques to be
+  applied at each joint. See :ref:`android-joints` below for a description of
+  the joint indicies.
+
+**Android Max Scaled Torques** (``1``)
+  A 94 dimensional vector of continuous values between [-1, 1] representing the
+  scaled torques to be applied at each joint. See :ref:`android-joints` below
+  for a description of the joint indicies.
+
+  1 represents the maximum forward torque and -1 the maximum torque in the
+  opposite direction.
+
 .. _`android-joints`:
 
 Android Joints
 --------------
 The control scheme for the android and the
-:class:`~holodeck.sensors.JointRotationSensor` use a 94 length vector refer 
-to 48 joints. 
+:class:`~holodeck.sensors.JointRotationSensor` use a 94 length vector refer to
+48 joints.
 
-To gain insight into these joints, refer to the table below, or use the 
-:meth:`~holodeck.agents.AndroidAgent.joint_ind` helper method to convert a
-name (eg ``spine_02``) to and index (``6``).
+To gain insight into these joints, refer to the table below, or use the
+:meth:`~holodeck.agents.AndroidAgent.joint_ind` helper method to convert a name
+(eg ``spine_02``) to and index (``6``).
 
 .. note::
     Note that the index given is the start index for the joint, see the section
     header for how many values after this index each joint has.
 
-    Example: ``neck_01`` starts at index 3, and has ``[swing1, swing2, twist]``, so index
-    3 in the 94 length vector corresponds to ``swing1``, 4 corresponds to ``swing2``, and
-    5 corresponds to ``twist`` for ``neck_01``
+    Example: ``neck_01`` starts at index 3, and has ``[swing1, swing2, twist]``
+    , so index 3 in the 94 length vector corresponds to ``swing1``, 4
+    corresponds to ``swing2``, and 5 corresponds to ``twist`` for ``neck_01``.
 
 Returned in the following order:
 
@@ -161,8 +176,8 @@ Returned in the following order:
 
 AndroidAgent Bones
 ------------------
-The :class:`~holodeck.sensors.RelativeSkeletalPositionSensor` returns an 
-array with four entries for each bone listed below.
+The :class:`~holodeck.sensors.RelativeSkeletalPositionSensor` returns an array
+with four entries for each bone listed below.
 
 ========= =======================
   Index          Bone Name
@@ -229,20 +244,11 @@ array with four entries for each bone listed below.
 ``236``   ``thigh_twist_01_r``
 ========= =======================
 
-
-Control Schemes
----------------
-
-- Android Torques
-
-See :class:`~holodeck.agents.AndroidAgent` for details on how this control scheme works.
-
 .. TODO: Example code
 
 Sockets
 ---------------
 
 - ``CameraSocket`` located in the middle of the android's face
 - ``Viewport`` located behind the agent
-- All of the joints may be used as sockets. See 
-  :ref:`android-joints`
+- All of the joints may be used as sockets. See :ref:`android-joints`.

docs/agents/hand-agent.rst

@@ -18,39 +18,42 @@ Control Schemes
 ---------------
 
 - **Raw Joint Torques** (``0``)
-  
+
   23 length vector of raw torques to pass into the joints, in the order listed
   beow in :ref:`hand-joints`
 
 - **Scaled Joint Torques** (``1``)
-  
+
   23 length vector of scaled torques, between ``-1`` and ``1``. The strength
   finger each joint is scaled depending on the weight of the bone and if it is
   a finger or not. ``1`` represents the maximum power in the forward direction
 
 
 - **Scaled Joint Torques + Floating** (``2``)
-  
+
   Same as above, but the vector is of length 26, with the last three values
   representing the amount of movement in the ``[x, y, z]`` directions (see
   :ref:`coordinate-system`), with a maximum of ``0.5`` meters of freedom.
 
+  The last coordinates allow the HandAgent to float around.
+
+
 .. _`hand-joints`:
 
 HandAgent Joints
 ----------------
 The control scheme for the HandAgent and the
-:class:`~holodeck.sensors.JointRotationSensor` use a 94 length vector refer 
-to 48 joints. 
+:class:`~holodeck.sensors.JointRotationSensor` use a 94 length vector refer
+to 48 joints.
 
 To gain insight into these joints, refer to the table below.
 
 .. note::
     Note that the index given is the start index for the joint, see the section
     header for how many values after this index each joint has.
 
-    Example: ``hand_r`` starts at index 0, and has ``[swing1, swing2, twist]``, 
-    so index 0 in the vector corresponds to ``swing1``, 1 corresponds to 
+    Example: ``hand_r`` starts at index 0, and has ``[swing1, swing2, twist]``,
+    so index 0 in the vector corresponds to ``swing1``, 1 corresponds to
     ``swing2``, and 2 corresponds to ``twist`` for ``hand_r``
 
 Returned in the following order:
@@ -110,7 +113,7 @@ Returned in the following order:
 
 HandAgent Bones
 ---------------
-The :class:`~holodeck.sensors.RelativeSkeletalPositionSensor` returns an 
+The :class:`~holodeck.sensors.RelativeSkeletalPositionSensor` returns an
 array with four entries for each of the 17 bones listed below.
 
 ========= ===============
@@ -141,5 +144,5 @@ Sockets
 
 - ``CameraSocket`` located behind and above the wrist
 - ``Viewport`` located looking at the agent from the side
-- All of the joints may be used as sockets. See 
+- All of the joints may be used as sockets. See
   :ref:`hand-joints`

docs/agents/nav-agent.rst

@@ -19,8 +19,10 @@ attempt to intelligently navigate towards those coordinates.
 
 Control Schemes
 ---------------
+**Nav Target Location (``0``)**
+ A 3-length floating point vector used to specify the x, y and z
+ coordinates for the agent to navigate to.
 
-See :class:`holodeck.agents.NavAgent` for specific details on the control scheme.
 
 Sockets
 -------

docs/agents/sphere-agent.rst

@@ -21,13 +21,14 @@ See :class:`~holodeck.agents.SphereAgent` for more details.
 Control Schemes
 ---------------
 
-- Discrete
-- Continuous Control Scheme
+**Sphere discrete** (``0``)
+  A single-length integer vector that accepts 1 of four
+  possible numbers; 0: move forward, 1: move backward, 
+  2: turn right, 3: turn left
 
-See :class:`~holodeck.agents.SphereAgent` for details on how to use 
-the control schemes.
-
-.. TODO: Example code?
+**Sphere continuous** (``1``)
+  A 2-length floating point vector used to specify 
+  the agent's forward speed (index 0) and rotation speed (index 1).
 
 Sockets
 ---------------
@@ -36,4 +37,4 @@ Sockets
 - ``Viewport`` located behind the agent
 
 .. image:: images/sphere-sockets.png
-   :scale: 30%
+   :scale: 30%

docs/agents/turtle-agent.rst

@@ -17,6 +17,13 @@ TurtleAgent is subject to gravity and can climb ramps and slopes.
 
 See :class:`~holodeck.agents.TurtleAgent` for more details.
 
+Control Schemes
+---------------
+
+**Sphere continuous** (``1``)
+  A 2-length floating point vector used to specify
+  the agent's forward force (index 0) and rotation force (index 1).
+
 Sockets
 -------