Docs final effort (#282)

* Fix Android joints The list in sensors.py was incorrect, and I tried to consolidate the list. * Improve control scheme documentation * Update docs for MazeWorld * Fix docstring formatting * More changelog updates * Resolve some TODOs * Improve package installation location documentation * Document performance enhancement techniques Finishes #109 * Document custom scenario methods * Update changelog * fixed typo
BYU-PCCL · Jun 20, 2019 · 4b8d43f · 4b8d43f
1 parent 47ac0ab
commit 4b8d43f
Show file tree

Hide file tree

Showing 21 changed files with 492 additions and 244 deletions.
diff --git a/docs/agents/android-agent.rst b/docs/agents/android-agent.rst
@@ -15,15 +15,154 @@ Images
 Description
 -----------
 An android agent that can be controlled via torques supplied to its joints.
-See :class:`holodeck.agents.AndroidAgent` for more details.
+See :class:`~holodeck.agents.AndroidAgent` for more details.
+
+.. _`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. 
+
+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``
+
+Returned in the following order:
+
++-------------------------------------+-----------------------+
+| **Head, Spine, and Arm joints**                             |
+|                                                             |
+| Each has ``[swing1, swing2, twist]``                        |
++-------------------------------------+-----------------------+
+| ``0``                               | ``head``              |
++-------------------------------------+-----------------------+
+| ``3``                               | ``neck_01``           |
++-------------------------------------+-----------------------+
+| ``6``                               | ``spine_02``          |
++-------------------------------------+-----------------------+
+| ``9``                               | ``spine_01``          |
++-------------------------------------+-----------------------+
+| ``12``                              | ``upperarm_l``        |
++-------------------------------------+-----------------------+
+| ``15``                              | ``lowerarm_l``        |
++-------------------------------------+-----------------------+
+| ``18``                              | ``hand_l``            |
++-------------------------------------+-----------------------+
+| ``21``                              | ``upperarm_r``        |
++-------------------------------------+-----------------------+
+| ``24``                              | ``lowerarm_r``        |
++-------------------------------------+-----------------------+
+| ``27``                              | ``hand_r``            |
++-------------------------------------+-----------------------+
+| **Leg Joints**                                              |
+|                                                             |
+| Each has ``[swing1, swing2, twist]``                        |
++-------------------------------------+-----------------------+
+| ``30``                              | ``thigh_l``           |
++-------------------------------------+-----------------------+
+| ``33``                              | ``calf_l``            |
++-------------------------------------+-----------------------+
+| ``36``                              | ``foot_l``            |
++-------------------------------------+-----------------------+
+| ``39``                              | ``ball_l``            |
++-------------------------------------+-----------------------+
+| ``42``                              | ``thigh_r``           |
++-------------------------------------+-----------------------+
+| ``45``                              | ``calf_r``            |
++-------------------------------------+-----------------------+
+| ``48``                              | ``foot_r``            |
++-------------------------------------+-----------------------+
+| ``51``                              | ``ball_r``            |
++-------------------------------------+-----------------------+
+| **First joint of each finger**                              |
+|                                                             |
+| Has only ``[swing1, swing2]``                               |
++-------------------------------------+-----------------------+
+| ``54``                              | ``thumb_01_l``        |
++-------------------------------------+-----------------------+
+| ``56``                              | ``index_01_l``        |
++-------------------------------------+-----------------------+
+| ``58``                              | ``middle_01_l``       |
++-------------------------------------+-----------------------+
+| ``60``                              | ``ring_01_l``         |
++-------------------------------------+-----------------------+
+| ``62``                              | ``pinky_01_l``        |
++-------------------------------------+-----------------------+
+| ``64``                              | ``thumb_01_r``        |
++-------------------------------------+-----------------------+
+| ``66``                              | ``index_01_r``        |
++-------------------------------------+-----------------------+
+| ``68``                              | ``middle_01_r``       |
++-------------------------------------+-----------------------+
+| ``70``                              | ``ring_01_r``         |
++-------------------------------------+-----------------------+
+| ``72``                              | ``pinky_01_r``        |
++-------------------------------------+-----------------------+
+| **Second joint of each finger**                             |
+|                                                             |
+| Has only ``[swing1]``                                       |
++-------------------------------------+-----------------------+
+| ``74``                              | ``thumb_02_l``        |
++-------------------------------------+-----------------------+
+| ``75``                              | ``index_02_l``        |
++-------------------------------------+-----------------------+
+| ``76``                              | ``middle_02_l``       |
++-------------------------------------+-----------------------+
+| ``77``                              | ``ring_02_l``         |
++-------------------------------------+-----------------------+
+| ``78``                              | ``pinky_02_l``        |
++-------------------------------------+-----------------------+
+| ``79``                              | ``thumb_02_r``        |
++-------------------------------------+-----------------------+
+| ``80``                              | ``index_02_r``        |
++-------------------------------------+-----------------------+
+| ``81``                              | ``middle_02_r``       |
++-------------------------------------+-----------------------+
+| ``82``                              | ``ring_02_r``         |
++-------------------------------------+-----------------------+
+| ``83``                              | ``pinky_02_r``        |
++-------------------------------------+-----------------------+
+| **Third joint of each finger**                              |
+|                                                             |
+| Has only ``[swing1]``                                       |
++-------------------------------------+-----------------------+
+| ``84``                              | ``thumb_03_l``        |
++-------------------------------------+-----------------------+
+| ``85``                              | ``index_03_l``        |
++-------------------------------------+-----------------------+
+| ``86``                              | ``middle_03_l``       |
++-------------------------------------+-----------------------+
+| ``87``                              | ``ring_03_l``         |
++-------------------------------------+-----------------------+
+| ``88``                              | ``pinky_03_l``        |
++-------------------------------------+-----------------------+
+| ``89``                              | ``thumb_03_r``        |
++-------------------------------------+-----------------------+
+| ``90``                              | ``index_03_r``        |
++-------------------------------------+-----------------------+
+| ``91``                              | ``middle_03_r``       |
++-------------------------------------+-----------------------+
+| ``92``                              | ``ring_03_r``         |
++-------------------------------------+-----------------------+
+| ``93``                              | ``pinky_03_r``        |
++-------------------------------------+-----------------------+
 
 Control Schemes
 ---------------
-.. TODO: Link to Control Scheme page
 
 - Android Torques
 
-.. TODO: Don't punt on the joint layout
+See :class:`~holodeck.agents.AndroidAgent` for details on how this control scheme works.
 
 .. TODO: Example code
 

diff --git a/docs/agents/nav-agent.rst b/docs/agents/nav-agent.rst
@@ -13,14 +13,16 @@ See :class:`holodeck.agents.NavAgent` for more details.
 
 Description
 -----------
-The NavAgent is not meant for training, instead it is more like target that agents can interact 
-with.
+The NavAgent is not meant for training, it is meant to be used as an objective
+in tasks. Given world coordinates, it will use use Unreal's AI system to 
+attempt to intelligently navigate towards those coordinates.
 
-It uses Unreal's AI system to attempt to intelligently navigate towards a particular location.
+Control Schemes
+---------------
 
-See :class:`holodeck.agents.NavAgent` for more details.
+See :class:`holodeck.agents.NavAgent` for specific details on the control scheme.
 
 Sockets
----------------
+-------
 
 None.
diff --git a/docs/agents/sphere-agent.rst b/docs/agents/sphere-agent.rst
@@ -13,19 +13,20 @@ Description
 -----------
 
 A basic sphere robot that moves along a plane. The SphereAgent does not have 
-physics - it simply computes its next location and teleports there, as compared
-to the :ref:`turtle-agent` which has mass and momentum.
+physics - it simply computes its next location and teleports there, as 
+compared to the :ref:`turtle-agent` which has mass and momentum.
 
-See :class:`holodeck.agents.SphereAgent` for more details.
+See :class:`~holodeck.agents.SphereAgent` for more details.
 
 Control Schemes
 ---------------
 
-.. TODO: Add documentation entries for these
-
-- Action Space
+- Discrete
 - Continuous Control Scheme
 
+See :class:`~holodeck.agents.SphereAgent` for details on how to use 
+the control schemes.
+
 .. TODO: Example code?
 
 Sockets

diff --git a/docs/agents/turtle-agent.rst b/docs/agents/turtle-agent.rst
@@ -8,17 +8,17 @@ TurtleAgent
 
 Description
 -----------
-A simple turtle-bot agent. The turtle agent moves when forces are applied to it 
-- so it has momentum and mass, compared to the :ref:`sphere-agent` which teleports
-around.
+A simple turtle-bot agent. The turtle agent moves when forces are applied 
+to it - so it has momentum and mass, compared to the :ref:`sphere-agent` 
+which teleports around.
 
-See :class:`holodeck.agents.TurtleAgent` for more details.
+See :class:`~holodeck.agents.TurtleAgent` for more details.
 
 Sockets
----------------
+-------
 
 - ``CameraSocket`` located at the front of the body
 - ``Viewport`` located behind the agent
 
 .. image:: images/turtle-sockets.png
-   :scale: 30%
+   :scale: 30%
diff --git a/docs/agents/uav-agent.rst b/docs/agents/uav-agent.rst
@@ -19,18 +19,21 @@ Description
 -----------
 A quadcopter UAV agent. 
 
-See the :class:`holodeck.agents.UavAgent` class. 
+See the :class:`~holodeck.agents.UavAgent` class. 
 
-Action Spaces
--------------
+Control Schemes
+---------------
 - UAV Torques
 - UAV Roll / Pitch / Yaw targets
 
+See :class:`~holodeck.agents.UavAgent` for more details on how the control
+schemes work.
+
 Sockets
----------------
+-------
 
 - ``CameraSocket`` located underneath the uav body
 - ``Viewport`` located behind the agent
 
 .. image:: images/uav-sockets.png
-   :scale: 30%
+   :scale: 30%
diff --git a/docs/changelog/changelog.rst b/docs/changelog/changelog.rst
@@ -3,18 +3,26 @@ Changelog
 
 Holodeck 0.2.2
 --------------
-*06/10/2019*
+*06/17/2019*
 
-This is a maintainance release focused on cleaning up bugs that were 
+This is mostly a maintainance release focused on cleaning up bugs that were 
 unresolved in ``0.2.1``
 
 
 New Features
 ~~~~~~~~~~~~
-- When freecamming around, :ref:`pressing shift <moving-viewport>` makes the camera move faster
+- When freecamming around, :ref:`pressing shift <moving-viewport>` moves the 
+  camera faster.
   (`#99 <https://github.com/BYU-PCCL/holodeck/issues/99>`_)
 - Agents can have a rotation specified in the scenario config files
   (`#209 <https://github.com/BYU-PCCL/holodeck/issues/209>`_)
+- Custom scenarios can be made with dictionaries as well as ``json`` files. 
+  See :ref:`custom-scenarios`
+  (`#275 <https://github.com/BYU-PCCL/holodeck/issues/275>`_)
+- Documented how to improve Holodeck performance. 
+  See :ref:`improving-performance`
+  (`#109 <https://github.com/BYU-PCCL/holodeck/issues/109>`_)
+
 
 Bug Fixes
 ~~~~~~~~~
@@ -31,6 +39,11 @@ Bug Fixes
   (`#271 <https://github.com/BYU-PCCL/holodeck/issues/271>`_)
 - Fixed ``EXCEPTION_ACCESS_VIOLATION`` on Windows after creating an environment
   (`#270 <https://github.com/BYU-PCCL/holodeck/issues/270>`_)
+- Fixed :ref:`MazeWorld-FinishMazeSphere` task not going terminal when task
+  was finished.
+
+  - Added a post with a golden ball on top to the end of the maze, 
+    this is now the tasks's target
 
 Holodeck 0.2.1
 --------------
@@ -43,7 +56,8 @@ This summer we are planning on adding much more content (worlds, agents, etc).
 
 Highlights
 ~~~~~~~~~~
-- Added :ref:`Scenarios <scenarios>` to allow worlds to be more flexible and customizable
+- Added :ref:`Scenarios <scenarios>` to allow worlds to be more flexible and 
+  customizable
 - Documentation has been greatly expanded
 
 New Features

diff --git a/docs/packages/DefaultWorlds/MazeWorld/MazeWorld-FinishMazeSphere.rst b/docs/packages/DefaultWorlds/MazeWorld/MazeWorld-FinishMazeSphere.rst
@@ -1,8 +1,10 @@
+.. _`MazeWorld-FinishMazeSphere`:
+
 MazeWorld-FinishMazeSphere
 ==========================
 
 The goal of this task is for the sphere agent to finish the maze and get as 
-close as possible to the building on the other end.
+close as possible to post with a golden ball on the other end.
 
 Agents
 ------

diff --git a/docs/packages/docs/installation.rst b/docs/packages/docs/installation.rst
@@ -0,0 +1,35 @@
+.. _`package-locations`:
+
+=============================
+Package Installation Location
+=============================
+
+Holodeck packages are by default saved in the current user profile, depending
+on the platform.
+
+========== ==================================================================
+ Platform   Location
+========== ==================================================================
+Linux      ``~/.local/share/holodeck/{holodeck_version}/worlds/``
+Windows    ``%USERPROFILE%\AppData\Local\holodeck\{holodeck_version}\worlds``
+========== ==================================================================
+
+Note that the packages are saved in different subfolders based on the version
+of Holodeck. This allows multiple versions of Holodeck to coexist, without
+causing version incompatibility conflicts.
+
+This is the path returned by :func:`holodeck.util.get_holodeck_path`
+
+Each folder inside the worlds folder is considered a seperate package, so it 
+must match the format of the archive described in :ref:`package-contents`.
+
+Overriding Location
+-------------------
+
+The environment variable ``HOLODECKPATH`` can be set to override the default
+location given above.
+
+.. caution::
+   If ``HOLODECKPATH`` is used, it will override
+   this version partitioning, so ensure that ``HOLODECKPATH`` only points to 
+   packages that are compatible with your version of Holodeck.
diff --git a/docs/packages/docs/package-structure.rst b/docs/packages/docs/package-structure.rst
@@ -1,14 +1,14 @@
 Package Structure
 =================
 
-A holodeck package is a ``.zip`` file containing a build of `holodeck-engine`_ that
-contains worlds and :ref:`scenarios` for those worlds.
+A holodeck package is a ``.zip`` file containing a build of `holodeck-engine`_
+that contains worlds and :ref:`scenarios` for those worlds.
 
 .. _`holodeck-engine`: https://github.com/BYU-PCCL/holodeck-engine
 
 A package file is platform specific, since it contains a compiled binary of Holodeck.
 
-.. _package-contents:
+.. _`package-contents`:
 
 Package Contents
 ----------------

diff --git a/docs/packages/docs/scenarios.rst b/docs/packages/docs/scenarios.rst
@@ -79,11 +79,9 @@ Agent objects
       "rotation": [1.0, 2.0, 3.0]
    }
 
-.. TODO: Figure out the coordinate system
 
 .. note::
-   The ``locations`` coordinates are {left | right} handed and the ``rotation``
-   coordinates are {left handed | right handed | roll - pitch - yaw }
+   Holodeck coordinates are **left handed** in meters. See :ref:`coordinate-system`
 
 Here are the values that should be placed in ``agent_type``: