add YAML model builder tutorial

doc/source/contribute-tutorials.rst

@@ -1,24 +1,24 @@
 Contribute to Tutorials 
-===================
+=======================
 
 This section contains details on contributing to NTRT's tutorials.
 
 Install Sphinx
----------------
+--------------
 
 NTRT's tutorials are written using Sphinx. So first you'll need to ensure you have Sphinx installed. You can learn more here:
 
 http://sphinx-doc.org/latest/install.html
 
 Getting Started with Sphinx
-----------------------------
+---------------------------
 
 You can find details on Sphinx's markup on Sphinx's website: 
 
 http://sphinx-doc.org/tutorial.html
 
 Modifying NTRT's Tutorials 
-----------------------
+--------------------------
 
 NTRTSim's tutorials can be found in the docs/source directory.
 

doc/source/index.rst

@@ -16,7 +16,8 @@ Contents
    :maxdepth: 2
 
    setup.rst
-   contribute-tutorials.rst
-   third-party-libraries.rst
+   yaml-model-builder.rst
    learning-library-walkthrough.rst
    motors-and-cables.rst
+   third-party-libraries.rst
+   contribute-tutorials.rst

doc/source/setup.rst

@@ -1,14 +1,14 @@
 Setup/Installation
-===================
+==================
 
 Installing NTRT Without a Virtual Machine
----
+-----------------------------------------
 See this page for more information:
 
 https://raw.githubusercontent.com/NASA-Tensegrity-Robotics-Toolkit/NTRTsim/master/INSTALL
 
 Installing NTRT in a Virtual Machine
-----
+------------------------------------
 
 Currently the NTRT OS X build does not work, and Windows is not supported. If you use either operating system you will need to run NTRT in VirtualBox (or some other virtualization software) in the meantime. Here's how you do that:
 
@@ -19,9 +19,9 @@ For now, here is how to install it and get it going...
 3) Open Virtualbox. "File -> Import Appliance" and select the .ova file.
 4) Adjust the number of processors, RAM, and video memory you'd like to allocate to the guest. I'd suggest 2 processors, 4GB of RAM, and max out the video memory. If your computer is a bit slower, you might be able to get away with one one processor and down to 2 or 3GB of RAM.
 5) Once it's done importing, click on "Settings" to confirm things are OK. If you see an error in the bottom of the Settings window that says "Invalid Settings Detected," change your settings according to the error's recommendation.
-5.1) Check the "Enable 3D Acceleration" box under "Display." This makes the simulation visualization run at a reasonable speed.
-6) Run the virtual machine, and enjoy! You should be able to run the SUPERball demo by opening up a Terminal window and typing the commands:
-7) Once your virtual machine boots up, you'll be prompted for a password the "tensegribuntu" user. The password is tensegrity.
+6) Check the "Enable 3D Acceleration" box under "Display." This makes the simulation visualization run at a reasonable speed.
+7) Run the virtual machine, and enjoy! You should be able to run the SUPERball demo by opening up a Terminal window and typing the commands:
+8) Once your virtual machine boots up, you'll be prompted for a password the "tensegribuntu" user. The password is tensegrity.
 
 Once the virtual machine is online, you can test it by opening a terminal and running the following:
 
@@ -37,6 +37,6 @@ Known Issues:
 Once you have NTRT installed and running, open your web browser and it will open three NTRT related pages in separate tabs: tutorials, doxygen and NTRT's github page. The tutorials are a good place to start in gaining familiarity with the sytstem, or in order to learn how to contribute changes you make into the NTRT master branch.
 
 General Linux Help
-----
+------------------
 
 In case it helps, here is a brief list of commands you can run in the terminal: http://www.pixelbeat.org/cmdline.html (Links to an external site.). I know Linux is not intuitive at first, but I'm here to help!

doc/source/yaml-model-builder.rst

@@ -0,0 +1,223 @@
+.. highlight:: yaml
+
+YAML Model Builder
+=========================================
+
+The YAML model builder was built to allow users to easily create, modify and run tensegrity structures using NTRT’s simulator. Contrary to building structures in C++, using the YAML model builder does not require any programming knowledge, it does not require any knowledge of NTRT’s libraries and does not require a compilation step each time a modification to a structure is made. Structures defined in YAML are also considerably shorter and simpler to create than their C++ equivalents. YAML is a human-readable data serialization format. It was chosen because of its simplicity and clean syntax.
+
+Building Simple Structures
+-----------------------------------------
+
+Shown below is a 3-Prism structure defined in YAML. It is important to note that spacing and indentation are important in YAML and inconsistent spacing will cause errors when parsing the file. Using a text editor such as Notepad++ or Sublime Text is recommended when defining structures. The site http://codebeautify.org/yaml-validator can be used to make sure the structure you have defined is valid YAML before running it in the simulator.
+::
+
+  nodes:
+    bottom1: [-5, 0, 0]
+    bottom2: [5, 0, 0]
+    bottom3: [0, 0, 8.66]
+
+    top1: [-5, 5, 0]
+    top2: [5, 5, 0]
+    top3: [0, 5, 8.66]
+
+  pair_groups:
+    rod:
+      - [bottom1, top2]
+      - [bottom2, top3]
+      - [bottom3, top1]
+
+    string:
+      - [bottom1, bottom2]
+      - [bottom2, bottom3]
+      - [bottom1, bottom3]
+
+      - [top1, top2]
+      - [top2, top3]
+      - [top1, top3]
+
+      - [bottom1, top1]
+      - [bottom2, top2]
+      - [bottom3, top3]
+
+Running Structures in the Simulator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before running a structure in the simulator, make sure you have completed all the setup/installation steps for NTRT. The YAML model builder is run by running the BuildModel executable (located in the yamlbuilder directory) and providing it with the path to a YAML structure as a command line argument. To run the structure above in the simulator go to the root NTRT directory and type in:
+::
+
+  build/yamlbuilder/BuildModel resources/YAMLStructures/BaseStructures/3Prism.yaml
+
+Adding Nodes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tensegrity structures are made up of rods and strings. The vertices of the rods and strings are defined using the keyword “nodes”. Each node is defined by a key-value pair where the key is a unique name and the value is a 3-element array with coordinates of the node. Names should not contain spaces, periods, or slash characters. The x and z coordinate axes are horizontal and run parallel to the ground (with the z axis representing depth). The y coordinate axis is vertical and perpendicular to the ground.
+::
+
+  nodes:
+    bottom1: [-5, 0, 0]
+
+Adding Pairs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rods and strings are defined using the “pair_groups” keyword and are grouped by tags. Tags determine how each pair is built in the simulator. There are different types of rods and strings that can be used to build any given pair. These are defined using builders which will be discussed in more detail in the next section. Default builders, that define a default rod and string, are added automatically to match the tags “rod” and “string” so that a tensegrity structure can be defined without having to worry about builders. Each tag holds a list of one or more pairs, where each pair is defined by the two nodes it connects. If a tag has a space such as “prism string” it is treated as two different tags that are assigned to a given pair. Tags should not use any period or slash characters.
+::
+
+  pair_groups:
+    rod:
+      - [bottom1, top2]
+
+Adding Builders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Shown below is an example of builders that can be used to modify how rods and strings are built in the simulator.
+::
+
+  builders:
+    rod:
+      class: tgRodInfo
+      parameters:
+        density: 0.688
+        radius: 0.31
+    string:
+      class: tgBasicActuatorInfo
+      parameters:
+        stiffness: 1000
+        damping: 10
+        pretension: 1000
+
+The “builders” keyword is used to define one or more builders. Builders work through tag matching. For example, the builder “rod” will match any pairs with the tag “rod”. The builder “rod” will also match any pairs with the tag “prism rod” since “prism rod” is treated as two different tags and the “rod” builder is looking for any pairs that include the tag “rod”. As was mentioned earlier, the YAML model builder automatically adds a default “rod” and “string” builder to make building structures even faster. If a “rod ”or “string” builder is defined by the user, it will override the default “rod” and “string” builder. Builders defined inside one file should never overlap (eg. using a “muscle” and “leg muscle” builder in the same file).
+
+Each builder tag needs to be given a class using the “class” keyword. The class determines the properties of the rod or string. The basic rod and string classes are tgRodInfo and tgBasicActuatorInfo. More information about different string/cable classes can be found in the `motors and cables`_ section. Each builder takes a number of parameters which are specified using the “parameters” keyword. All parameters are optional (if they are not specified they will take on default values). Some of the most common parameters for tgRodInfo and tgBasicActuatorInfo are shown in the example above. More information about the parameters used by tgRodInfo_ or tgBasicActuatorInfo_ can be found in their respective classes.
+
+Combining Structures
+-----------------------------------------
+
+Shown below is an example of a spine-like structure, made by combining six Tetrahedrons.
+::
+
+  substructures:
+    t1/t2/t3/t4/t5/t6:
+      path: ../BaseStructures/Tetrahedron.yaml
+      offset: [0, 0 , -12]
+
+  bond_groups:
+    string:
+      t1/t2/t3/t4/t5/t6/node_node:
+        - [front, front]
+        - [right, right]
+        - [back, back]
+        - [left, left]
+        - [right, front]
+        - [right, left]
+        - [back, front]
+        - [back, left]
+
+Multiple substructures can be combined in a superstructure using the “substructures” keyword. Superstructures inherit builders defined in substructures. If there is an overlap between builders in a superstructure and a substructure, the builder in the superstructure will override the builder in the substructure.
+
+Child Structure Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each substructure is defined by a name and one or more attributes. If multiple structures share the same attribute value, an abbreviated syntax (as shown above) using the slash character can be used.
+
+Path
+'''''''''''''''''''''''''''''''''''''''''
+
+Every child structure must be provided with a file path. The path can be absolute or relative to the parent structure.
+
+Rotation
+'''''''''''''''''''''''''''''''''''''''''
+
+Rotation attributes are always applied first regardless of the order in which they are defined. Rotation attributes are defined as shown below using an axis, angle and an optional reference point. The axis (a vector array) refers to the axis of rotation, the angle (in degrees) refers to the angle that the structure is rotated by and the reference point (a coordinate array) refers to the point around which the structure is rotated. If no reference point is specified the center of the structure is used as a reference point.
+::
+
+  example_structure:
+    rotation:
+      axis: [1, 0, 0]
+      angle: 90
+      reference: [0, 0, 0]
+
+Scale
+'''''''''''''''''''''''''''''''''''''''''
+
+The scale attribute scales the child structure by a specified amount. This value must be a decimal number, not a fraction. Structures are scaled around their center.
+::
+
+  example_structure:
+    scale: 0.5
+
+Translation
+'''''''''''''''''''''''''''''''''''''''''
+
+The translation attribute moves the structure by the specified vector array.
+::
+
+  example_structure:
+    translation: [0, 20, 0]
+
+Offset
+'''''''''''''''''''''''''''''''''''''''''
+
+The offset attribute is useful for spine-like structures where multiple structures are added in a row and individual structures need to be offset from one another. Each structure is offset from its preceding structure by the specified offset vector.
+::
+
+  t1/t2/t3/t4/t5/t6:
+    offset: [0, 0 , -12]
+
+Connections Between Structures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Connections between structures can be defined using the “bond_groups” keyword. Similar to “pair_groups”, “bond_groups” are grouped by tags. Bonds are defined by the name of the structures that are being connected and the bond type used to connect those structures. In the example below the “top” node from the foot is connected to the “bottom” node of the leg using a node-to-node connection.
+::
+
+  bond_groups:
+    string:
+      foot/leg/node_node:
+        - [top, bottom]
+
+
+If the “leg” structure is itself a superstructure with multiple substructures (such as a “knee” substructure) then the child node can be specified using the dot notation shown below. The dot character is used to denote a child structure. Multiple dot characters can be used if necessary (eg. “parent.child.grandchild.node”). Using this notation is only necessary if the node name is not unique among a structure’s children.
+::
+
+  bond_groups:
+    string:
+      foot/leg/node_node:
+        - [top, knee.bottom]
+
+Spine Structures
+'''''''''''''''''''''''''''''''''''''''''
+
+Spines structures can be easily defined using the syntax below. The syntax makes it possible to define a set of pairs that is used to connect more than two structures.
+::
+
+  bond_groups:
+    string:
+      t1/t2/t3/node_node:
+        - [front, front]
+
+Node-to-Node Connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Node-to-node connections simply add a string between two specified nodes (similar to how “pair_groups” work). For superstructures it is recommended to use the bond_groups syntax rather than the “pair_groups” syntax because it makes it clear which structures are being connected (without having to use the dot notation to repeat which structure the nodes for each pair belong to).
+
+Node-to-Edge Connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The structure below shows six 3-Prisms combined using node-to-edge connections.
+::
+
+  substructures:
+    3prism1/3prism2/3prism3/3prism4/3prism5/3prism6:
+      path: ../BaseStructures/3Prism.yaml
+
+  bond_groups:
+    horizontal_string:
+      3prism1/3prism2/3prism3/3prism4/3prism5/3prism6/node_edge:
+        - [top1, bottom1/bottom2]
+        - [top2, bottom2/bottom3]
+        - [top3, bottom3/bottom1]
+
+Node-to-edge connections are defined using three or more pairs, where each pair consists of a node and an edge. Nodes can be connected to edges and vice versa. There can even be a mix of node-to-edges and edges-to-nodes within a single “node_edge” connection. An edge is defined by two nodes separated by the slash character. Node-to-edge connections work by attaching a node directly to the middle of a string. For node-to-edge connections, rotations and translation attributes for child structures are done automatically by the YAML model builder and do not need to be specified.
+
+.. _motors and cables: motors-and-cables.html
+.. _tgRodInfo: http://ntrt.perryb.ca/doxygen/classtg_rod_info.html
+.. _tgBasicActuatorInfo: http://ntrt.perryb.ca/doxygen/classtg_basic_actuator_info.html

resources/YamlStructures/Centipede.yaml

@@ -0,0 +1,23 @@
+substructures:
+  p1/p2/p3/p4:
+    path: BigPuppy.yaml
+    offset: [-95, 0 , 0]
+
+bond_groups:
+  p1/p2/p3/p4/node_node:
+    low_tension_string:
+      - [vertebra1.front1, vertebra7.back2]
+      - [vertebra1.front2, vertebra7.back1]
+      - [vertebra2.front1, vertebra6.back2]
+      - [vertebra2.front2, vertebra6.back1]
+
+builders:
+  low_tension_string:
+    class: tgBasicActuatorInfo
+    parameters:
+      stiffness: 1000.0
+      damping: 10.0
+      pretension: 0.0
+      history: 1
+      max_tension: 7000.0
+      target_velocity: 12.0

resources/YamlStructures/Spines/OctahedralSpine.yaml → resources/YamlStructures/Spines/TetrahedralSpine.yaml

@@ -1,11 +1,11 @@
 substructures:
-  o1/o2/o3/o4/o5/o6:
-    path: ../BaseStructures/Octahedron.yaml
+  t1/t2/t3/t4/t5/t6:
+    path: ../BaseStructures/Tetrahedron.yaml
     offset: [0, 0 , -12]
 
 bond_groups:
-  o1/o2/o3/o4/o5/o6/node_node:
-    string:
+  string:
+    t1/t2/t3/t4/t5/t6/node_node:
       - [front, front]
       - [right, right]
       - [back, back]