[Joana] Documentation additions

00_sphinx_documentation/documentation/GeneralUsage/3_Tools.rst

@@ -26,7 +26,8 @@ Hand
 
    Hand Tool to move Roboy around.
 
-The hands are useful when interacting with the Roboy model, for example when pushing or pulling Roboy's arm. Roboy parts which are in front of the hand are highlighted and change color when being grabbed. Additional haptic feedback is given.  
+The hands are useful when interacting with the Roboy model, for example when pushing or pulling Roboy's arm. More information can be found under the point *Moving Roboy*. 
+
 
 Watch
 -----

00_sphinx_documentation/documentation/Implementation/7_Coordinate_Systems.rst

@@ -0,0 +1,40 @@
+Coordinate Systems
+==================
+
+General
+-------
+Coordinate systems present an immense hazard when implementing messages from Unity to Gazebo or back. In case these messages contain positions, rotations and directions, it is of **utmost improtance** to transform coordinates into the **expected coordinate spaces**: 
+
+- Unity's coordinate system: 
+
+ - The x coordinate points to the right (right edge of the screen)
+ - The y coordinate points upwards (top of the screen)
+ - The z coordinate points into the scene, away from the user
+
+- Gazebo's coordinate system:
+
+ - The x coordinate points to the right (right edge of the screen)
+ - The y coordinate points into the scene, away from the user
+ - The z coordinate points upwards (top of the screen)
+
+**NOTICE: y and z coordinate are swapped when converting coordinates into the other coordinate system**
+
+**Implementation**
+
+A utility class called *GazeboUtility* provides conversions for both angles and rotations from and to Gazebo coordinates. All defined messages automatically transform the values, depending on if they were parsed from a received message or created using the Unity constructors. 
+
+World and local space
+---------------------
+Another important aspect to consider: Positions and forces can be defined in world space, giving the absolute position / direction, or they can be defined in local space. When values are defined in local space, the local coordinate system always needs to be provided as well. 
+
+**Message examples**
+The *ExternalForceMessage* is an exellent example: A force is **defined locally**, with its relative position and relative direction specified **along with the Roboy part** . The part provides the local coordinate system. 
+Other messages may specify positions locally or in worls space, when in doubt: The message definition *should* provide further information, otherwise check the receiving entity how it handles the values. 
+
+**Simulations in Gazebo**
+In gazebo, every position can be queried in local or world coordinate space, and forces can be applied locally (*AddRelativeForce(...)*) or in world space (*AddWorldForce(...)*). 
+
+**Issues**
+When applying relative forces in Gazebo, the results never matched the given forces and directions. One option, how to solve this issue, would be to convert the local values to world coordinate space. Unfortunately, during the given time, no function was found which transforms the values correctly (The scale of the coordinate systems might be one of the reasons it failed). 
+
+For now, external forces are defined **in World Space** and the respective gazebo simulation applies forces in world space as well. 

00_sphinx_documentation/documentation/MovingRoboy/0_Introduction.rst

@@ -0,0 +1,20 @@
+Introduction
+============
+
+.. figure:: images/grab3.*
+   :align: center
+   :alt: Moving Roboy
+
+   Moving Roboy in VR using the Hand Tool
+
+
+What is it?
+-----------
+
+Roboy can be moved around in the virtual environment. The user can grab him, pull and push Roboy and shove him around. Roboy adapts his position based on a physical simulation of his body and the applied forces. He is glued to the ground to prevent him from crumbling to the ground and flying around in the room.  
+
+
+How does it work?
+-----------------
+
+As soon as a user grabs a body part of Roboy, forces are calculated. The further the user pulls or pushes, the higher is the calculated force. This force is sent to the simulation running in Gazebo, which applies the forces and sends an updated position back to Unity, which adapts Roboy's pose. 

00_sphinx_documentation/documentation/MovingRoboy/1_UsersManual.rst

@@ -0,0 +1,35 @@
+User's Manual
+=============
+
+Starting the Simulation
+-----------------------
+
+On the computer running the Gazebo simulation, set up all required exports and so forth as described in the *Getting started* section. 
+
+Run the launch file, which starts a ROS server and the simulation
+
+.. code:: bash
+
+  roslaunch roboy_simulation roboy_moveable.launch  
+
+Additionally, the applied forces can be visualised in RViz to help with debugging and to gain further insight. Run the following command
+
+.. code:: bash
+
+  rviz
+  
+Make sure to follow the additional steps described in *Getting started* to be able to see Roboy and the applied force. 
+
+Starting Unity
+--------------
+1. Start the unity project and set up the ROS server connection as described in **Getting Started**. 
+2. Start the scene.
+3. After the controller assignment, switch to the HandTool
+4. Point at Roboy and grab him using the trigger
+5. Move Roboy around
+
+.. figure:: images/moving.*
+    :align: center
+    :alt: Roboy being moved
+
+    Roboy being shoved around 

00_sphinx_documentation/documentation/MovingRoboy/2_DeveloperManual.rst

@@ -0,0 +1,35 @@
+Developer's Manual
+==================
+
+Gazebo Simulation
+-----------------
+
+For the gazebo part a launch/ world file automatically loads the world (with all the surrounding objects) that has been specified and the version of Roboy which was chosen. A plugin is in charge of applying the forces and sending the forces to be visualized by RViz. 
+
+The simulation VRRoboy2 also applies the external forces and simulates Roboy, but due to a Gazebo bug, model plugins are not loaded. Using the .launch file is recommended.  
+
+Model Configuration
+-------------------
+A new model roboy_simplified_moveable was derived from an existing model and additional values / changes were applied: 
+
+- Roboy's feet are static, therefore glued to the ground
+- Roboy is not affected by gravity
+- The joints have a high friction: This, together with the strong forces applied, makes the inertia of Roboy's body neglectable / less prominent and he moves immediately 
+
+Unity Scene
+-----------
+The forces which are to be applied are calculated in the HandTool and published over ROS. A position subscriber receives the updated position and applies it to the model. 
+**Issue:** Unity works with around 80 FPS, while the simulation publishes around 300 messages per second. Even though the pose subscriber drops superfluous messges, a back-log of messages cannot be prevented on Unity-side as of now and the visualised model starts to lag behind. 
+
+**Solution for now:** The simulation restricts the number of sent messages
+
+Coordinate Systems
+------------------
+Coordinate systems presented a major issue in this project. Unity and gazebo have different coordinate systems, additionally, local and world coordinate systems add to the complexity. Please see the **Implementation/Coordinate Systems/** section for more information. 
+
+.. figure:: images/coordinate_systems.*
+   :align: center
+   :alt: Wrong coordinate systems
+
+   The result of local and world coordinate system discrepancies
+

00_sphinx_documentation/documentation/index.rst

@@ -55,6 +55,14 @@ Contents:
 
   StateVisualization/*
 
+.. _StateVisualization:
+.. toctree::
+  :maxdepth: 1
+  :glob:
+  :caption: Moving Roboy
+
+  MovingRoboy/*
+
 .. _ModelWorldLoader:
 .. toctree::
   :maxdepth: 1