Getting Started

Prerequisites

1. Currently, MGView requires WebGL in Google Chrome. Firefox may work, but it is not officially supported.
   • To install Google Chrome, visit http://www.google.com/chrome.
2. To check that your Chrome installation supports WebGL:
   • Launch Chrome and visit the examples page.
   • Click on the first example, "Classic Particle Pendulum."
   • Ensure that the pendulum model appears, and runs when you click the green timer button on the top bar. Note: If you see a red background in the visualizer and you are sure that you are using Chrome (not Safari, Firefox, or Internet Explorer), then your physical hardware may not support WebGL.

Installation (only needs to be done once)

• Download this zip file from https://github.com/mgview.

• On Mac: (and to some extent, Linux)

  • Double-click on mgview-master.zip. This will create the folder mgview-master in your Downloads folder.
  • Move the mgview-master folder into your MotionGenesis folder and rename it to MGView.
    You can do this in the terminal by running the following command:

    mv ~/Downloads/mgview-master /Applications/MotionGenesis/MGView

• On Windows: (last tested on Windows 7...)

  • Use the "Extract to here..." option in your zip client to unzip the file.
    This will create a folder called mgview-master.
    (Note if you use the wrong zip option you will just end up with everything nested inside two levels of folders called mgview-master; in this case, use the inner folder for the next two steps.)
  • Rename the folder mgview-master to MGView (case-sensitive).
  • Move the MGView folder to your MotionGenesis folder. (The default location is C:\MotionGenesis\.)

Running

• On Mac/Linux:

  1. Use a terminal to navigate to your MGView folder.

     cd /Applications/MotionGenesis/MGView/

  2. Run the http server which allows MGView to work (on Linux, replace "RunMGViewMac" with "RunMGViewLinux").

     ./RunMGViewMac

  3. If the previous step fails by complaining that RunMGViewMac is not a valid executable, enter the following command and repeat the previous step.

     chmod a+x RunMGViewMac

  4. If a tab fails to automatically open in Chrome, manually create a new tab and put localhost:8000/MGView in the address bar.

• On Windows:

  1. Run Chrome as you would normally. The following steps will fail if Chrome isn't already running.
  2. Open your MGView folder, and double-click on RunMGViewWindows.
     Note: This starts MGView in a new Chrome tab, and runs a local HTTP server to support the application.
  3. The application (specifically, the webserver running in node.exe) will request permission to communicate on your local network; you should click "Yes".
  4. If a tab fails to automatically open in Chrome, manually create a new tab and put localhost:8000/MGView in the address bar.

Creating Numerical Pose Data Using MotionGenesis (MG)

Your MG simulations must output animation data (position/orientation vs. time) for each point and frame that you want to visualize.

1. Ensure you have defined the position of each "origin" point in your simulation (No, Bo, etc).
   Note: The   Translate command is sufficient, you do not need a separate   SetPosition call.
2. Ensure the time step set by the MG command
   Input IntegStp = 0.01
   provides a reasonable visual frame-rate without making data files excessively large.
3. Ensure the line   Animate(N, No) appears in your MG command file before the MG command   ODE() myFileName
   In the Animate command:
   • Replace "N" with the name of your NewtonianFrame.
   • Replace "No" with the name of your World Origin.
   • By default it will animate everything. You can optionally specify which
     points and bodies to animate, e.g.   Animate(N, No, A, B, C, Ab, Bc).
4. After running the simulation, you will have a series of data files called "myFileName.1", "myFileName.2", etc.
5. See the samples in in your MotionGenesis/MGView/samples folder if you have trouble.

Creating the JSON file for MGView

Visualizer files use the JSON format.

1. Copy the file default.json into the folder that contains your motion data files.
2. Rename "default.json" to "myFileName.json"
3. Edit "myFileName.json" for your data, as described in the section "JSON File Contents" below.

Loading Simulations

1. Follow the "Running" instructions above to open an MGView window.
   Note: If the HTTP Server is already running and you want to just open a new MGView tab in Chrome,
   you can type:   localhost:8000/MGView/MGView.html in the Chrome address bar.
2. In the text field in the upper-left corner, type the relative path to the json file from the MGView.html file.
• For example, if you have the file: MotionGenesis/myFileName.json
  the relative path from MGView.html to myFileName.json is:   ../myFileName.json
  Note: Each "../" means "go up one level". So "../../" takes you up two levels.
  Note: It is helpful to organize your work into subfolders, in which case your path may be: ../myFolderName/myFileName.json
3. Click the "Load" button.
• If you re-run your simulation (generating new data files) you can reload the results by clicking the "Load" button again.

Hint: If things don't seem to be working, hit Ctrl+Shift+j to open the javascript developer tools window.
Select the "console" tab, which displays status messages. Errors (such as file not found) are displayed in RED.

Adding Visual Geometry Using the MGView GUI

The MGView GUI provides point-and-click functionality to add visual geometry to the points and frames in your simulation.
For the purpose of visualization, we will call these "objects."

After loading your .json file in the MGView tab in Chrome, you can add various kinds of geometry. For all types, the basic procedure is:

1. Click on the name of the object in the "Objects" list on the left side.
2. In the "create new" text box, type a name for the geometry (e.g. "myGeometry") and click the "+" button.
3. In the "Geometry" pull-down box, select the desired type (sphere, cylinder, mesh, etc).
4. Specific dimensions for each geometry type can be controlled using the spinner boxes that appear.

Geometry Types

• Basis
• Box
• Cone
• Cylinder
• Mesh / CAD (.stl, .obj, or .dae)
  1. In the "enter path" text box, type the relative path to the CAD file and click the arrow button at right.
  2. You may change or reload the mesh file at any time by repeating step 1.
• Sphere
• Text
  1. Type the desired text in the input box and click the arrow button at right.
  2. You may change the text at any time by repeating step 1.
• Torus

JSON File Contents Note: JSON file content is case-sensitive.

Certain fields in the JSON file must be edited by hand.
Required fields to edit:

• simulationData - string[i] - An array of strings containing the paths to your simulation data files, relative to the JSON file.
  A colon can be used to indicate a range, e.g. ["my_simulation.1:2"] is the same as ["my_simulation.1", "my_simulation.2"].

Additional fields:

• newtonianFrame - string - Must match the name of the NewtonianFrame used for animation output.
• sceneOrigin - string - Must match the name of the point (fixed in your NewtonianFrame) used for animation output.
• showAxes - bool - true or false (with no quotes). If true, will draw large red, green, and blue axes denoting the basis of your NewtonianFrame.
• workspaceSize - number - Used to automate the placement of some things, should correspond roughly to the diameter of the workspace in your simulation.
• cameraUp - number[3] - The [x,y,z] values, measured in the cameraParentFrame, representing the vector that points "upward".
• cameraEye - number[3] - The [x,y,z] position of the camera, measured in the cameraParentFrame.
• cameraFocus - number[3] - The [x,y,z] position of where the camera is looking, measured in the cameraParentFrame,
• cameraParentFrame - string - The name of the frame that the camera should be attached to.
• speedFactor - number - The initial/default speed of playback for the animation.

Advanced usage:

• An object of type "point" can be told to use the rotation matrix of another frame for the purposes of drawing any attached geometry. Simply add a "rotationFrame" property to the object, as shown in the particle pendulum example on object Q (near the bottom).
• A line between two points can be drawn by adding one or more "span" properties. See the example at the bottom of the fourbar example.
• There are some pre-defined material colors available. They are BLACK, WHITE, SILVER, GRAY, RED, WHITE, BLUE.