Displaying the Model
The Neuromechanic GUI (Graphical User Interface) has 4 primary functions:
- It displays 3 dimensional representations of the models.
- It facilitates running forward dynamic simulations of the models.
- We are trying to make it a useful and intuitive tool for changing the parameters of the model and observing the effects of those changes.
- It facilitates fast scripting of neural controllers.
You can download a model from the model repository if you want to get started right away and play with somethin as we go through some of the basic GUI functions
In addition to the menus at the top of the GUI there are 6 major elements. Starting at the top right and going counter clockwise they are:
- The viewing windows / source editor / script editor (tabbed)
- The simulation toolbar
- The model tree
- Log window
- Command Line
- Open: Load a model (nmcb) or output (nmco) file into Neuromechanic
- Save: Save the model
- Save As: Save the model to a specified directory
- Close: close the current model
- Exit: quit Neuromechanic.
- Preferences: (On mac this is under the program menu) Set the font size and color for log window as well as script and source view editors. Also control 3d viewing preferences
- Undo: -- for Source and Script editors
- Redo: -- for Source and Script editors
- Find & Replace: -- for Source and Script editors
- Copy: -- for Source and Script editors
- Paste: -- for Source and Script editors
- Cut: -- for Source and Script editors
- Add Point: -- currently not available --
- Editor: -- currently not available --
- Duplicate: -- currently not available --
- Degrees of Freedom:
- Editor: Control the joint positions and locking, save and load postures.
- Match Pose: -- currently not available --
- Equilibrate: Set neural activation patterns to equilibrate the model
- Simulate: Run a forward dynamic simulation
- Feasible Forces: Calculate feasible forces at points specified in <FeasibleForces>
- Satisfy Constraints: For models with position constraints this ensures that those constraints are satisfied.
- Compress Polygons: The <Polygon> elements in the <Resources> section can take a lot of memory and be referenced from other files. This function Compresses the polygons to a compact 18bit representation for self-contained (and possibly smaller) nmcb files.
- Reset Python Modules: Essentially runs: imp.reload(...) on all modules loaded in the <Resources> section.
- Run Script: -- for Script editor
- New: -- for Script editor
- Open: -- for Script editor
- Save: -- for Script editor
- Save as: -- for Script editor
- Cascade Scripts: -- for Script editor
- Tile Scripts: -- for Script editor
- Tab window: toggles between the viewing windows, source view (XML editor), and script view (Python editor)
- Snapshot: Save a bitmap or gif of what is in the current viewing windows.
- Reset View: Resets the cameras to default positions
- XY View: Sets the camera in the current viewing window to an orthographic view of the XY plane
- XZ View: Sets the camera in the current viewing window to an orthographic view of the XZ plane
- YZ View: Sets the camera in the current viewing window to an orthographic view of the YZ plane
- Perspective: Sets the camera in the current viewing window to a perspective view
- About: To learn (a little, not much) more.
The viewing windows
There are up to four viewing windows. The borders can be resized if you would like to see fewer. To manipulate the model in a viewing window.
- First click somewhere in the viewing window that you want to manipulate.
- Two-dimensional "ortho" projections in the global xy, yz, and xz planes can be selected by pressing the two desired keys. For example, to view the global xy plane with x as the horizontal axis and y as the vertical axis, press the "x" key and hold it while also pressing the "y" key. To view the zx plane with z as horizontal and x as vertical press "z" and hold while pressing "x". To swap the direction of an axis, press that key again. For example if the "ortho" xy plane is being viewed with positive x to the right and positive y up you can press "x" which will change the positive x axis to the left without affecting the y-axis. (Ortho projections can also be selected from the View menu)
- Three-dimensional "perspective" views can be selected by pressing "x", "y" and "z" together. (Perspective projection can also be selected from the View menu)
- Pan - left mouse click and drag
- Zoom - middle mouse click and drag or scroll. shift-drag or shift-scroll to zoom faster.
- Rotate - ("perspective" view only) right mouse click and drag
File->Preferences (Windows) or Neuromechanic->Preferences (Max OSX) (ctrl-,[?-,]) opens a window that lets you change the way the model is rendered. There are two tabs in the window, make sure Rendering is selected.
- Change Environment->ReferenceAxesVisible to true.
- Change Model->Bodies->BodyFrameVisible to true.
- Select the checkbox next to Model->Bodies->BodyColor.
- Save changes and close the window by clicking OK
Above the viewing windows are three tabs: Model, Source and Script. When you first open Neuromechanic you are in Model view. You can click the Source tab (or Ctrl-Tab) to change to source view. If a model is loaded you will see the XML definition of the current model. If you edit the XML file and save (ctrl-s) the file will be saved and Neuromechanic will attempt to reload the file. If successful, you can switch back to the Model view and see the 3d representation of the new model. If unsuccessful you will see an error message printed in the log window that will (hopefully) let you know what happened.
Python scripts can be written in the Script view/editor. These scripts are imported into the Neuromechanic python environment by pressing "ctrl+i". To see this in action switch to the script editor create a new python module by pressing the icon with paper and green +. Now type:
print('hey der bub')
Save (ctrl+s) the module (e.g. as junk.py) and then import it (ctrl+i or click the icon with the blue arrow).
You should see "hey der bub" printed in the log window below the script editor indicating that the module was imported. For more about Python scripting read this.
The simulation toolbar is at the top of the GUI under the menus. When a body file (*.nmcb) is loaded a simulation can be run by pressing the "Simulate" button and paused thereafter with the "Pause" button. When a simulation is complete or paused the state of the model can be reset to the condition before the start of the simulation by pressing "Reset". The parameters for the logistics of that simulation are set in the <Parameters> section of the *.nmcb file and can also be set in the gui using the simulation editor described below.
When an output file (*.nmco) is loaded the stored simulation can be replayed both to obtain more information or just to view the simulation.
Model Tree and Editors
To the left of the viewing windows is the model tree. If a model is loaded into Neuromechanic the model tree will be populated with items it recognizes from the <NeuromechanicFile>. Double clicking an entity in the model tree will take you to the definition of the item in the source view.
Editors can be loaded by single clicking certain items in the Model Tree.
- The degree of freedom editor (obtained by clicking on "Bodies" in the model tree) allows the user to configure the kinematic degrees of freedom from the GUI. The name of the degree of freedom and the body to which it belongs is listed with a checkbox, slider, and entry boxes. The checkboxes can be selected/deselected to control whether or not the degree of freedom is locked. The sliders and entry boxes are used to control the position of the state. Specific postures may be defined and retrieved
- Muscle editor (obtained by clicking a muscle in the expanded "Muscles" section) allows muscle parameters to be modified
- Neuron editor (obtained by clicking a neuron in the expanded "Neurons" section) allows neuron parameters to be modified
- Simulation editor (obtained by clicking on "Parameters") is useful for editing parameters that control forward dynamic simulations including start and end time, tolerances, reporting interval, and output values.
- Equilibration editor (obtained by clicking "EquilibrationType" under "Parameters") is for editing the equilibration parameters.
- Body editor (obtained by clicking a body in the expanded "Bodies" section) is for editing rigid body parameters.
The log window
If something unexpected happens. The first place to look for answers is the log window. All the information in the log window is printed to a file "neuromechaniclog.txt" which is stored in the Local app data folder $LOCALAPPDATA$\Neuromechanic in Windows and on OSX inside the bundled application under the folder $NEUROMECHANIC_INSTALL_DIR$/Resources. This is useful if something unexpected and nasty happens so that Neuromechanic crashes and the log window is not available.
When you load a file it prints a summary of what the model is. For example:
===============Loaded Model Summary================= Number of rigid bodies 2 Number of muscles 0 Number of kinematic Degrees of Freedom 7 Number of Constrained degrees of freedom 0 Number of locked degrees of freedom 6 ____________________________________________________ Number of RigidBodyStates 14 + Number of MuscleStates 0 + Number of EnvironmentStates 0 + Number of NeuronStates 0 = Total Number of States 14 ____________________________________________________ Total Number of control states 0 ==============Loaded Model Summary================== TOTAL MASS = 0.17178 =================Muscle Summary===================== -INDEX- -MUSCLE NAME- -MTL- -LF- -LF/LF0- MUSCLE MASS = 0.00000 =================Muscle Summary=====================
The command line
Finally, directly below the log window is the command line. You can type python commands here e.g.
print('hey der bub')
You can also type "cls" to clear the log window and press the up or down arrow to retrieve previous commands.