Mirage Setup and Usage

Mirage is a simulation environment which can host multiple agents in a virtual world.

Features

Building Mirage From Source

  1. You will need to install the following packages on your machine.
    Please consult with the corresponding projects if you have trouble with their installation.

  2. The Mirage source is distributed as part of Tekkotsu, in the tools/mirage directory. If you haven't already, you can find instructions for downloading Tekkotsu.

  3. Linux Instructions (using make):

    1. If you have not already built any Tekkotsu projects, you will need to build some helper tools first:

      cd TEKKOTSU_ROOT/tools
      make

    2. If you installed Ogre or Bullet to non-standard locations, you will need to set the OGRE_ROOT and/or BULLET_ROOT environment variables, or edit the default values (/usr/local) in TEKKOTSU_ROOT/tools/mirage/Makefile.

    3. Now we can build Mirage itself:

      cd TEKKOTSU_ROOT/tools/mirage
      make

    4. Uncomment the PluginFolder setting in plugins.cfg by removing the # character, and change the value to OGRE_ROOT/lib/OGRE. (where OGRE_ROOT is the location of your installation, e.g. if your OGRE_ROOT is /usr/local, then the plugin directory would be /usr/local/lib/OGRE).

  4. Mac OS X Instructions (using Xcode)

    1. Open TEKKOTSU_ROOT/tools/mirage/Make.xcodeproj
    2. You should have installed Ogre, Bullet, and OIS as framework bundles in /Library/Frameworks. If you didn't, you can change the library locations in the ▸Frameworks▸Linked Frameworks file group in the navigation panel on the left. (delete old references and drag-and-drop from current locations, or right click, "Get Info", "Choose")
    3. Choose "Build" from the "Build" menu to compile.
      • As a command line alternative, try running xcodebuild from within the mirage directory. (You don't need to be running Xcode)
    4. The application will be placed at TEKKOTSU_ROOT/tools/mirage/build/Debug/Mirage.app. You can run it from the Finder, or choose "Run" from within Xcode. (or the open command from the command line…)

  5. The Mirage WorldBuilder tool is included in the Tekkotsu/rools/mirage directory, but it depends on some Ruby packages that are not installed by default. To install these packages, do:

    sudo apt-get install ruby rubygems
    sudo gem install plist treetop

Running Mirage

    • Mac OS X Users: Run Mirage from within Xcode, or double click the application from the Finder.

    • Linux Users: Launch mirage from within the TEKKOTSU_ROOT/tools/mirage directory:

      cd TEKKOTSU_ROOT/tools/mirage
      ./mirage

    You will first see an Ogre configuration window—you will probably want to disable fullscreen mode and reduce the window resolution.

    Afterward, a window should appear, displaying the Mirage 3D environment.

  2. Camera Controls:

    W
    move forward
    S
    move backward
    A
    move left
    D
    move right
    PgUp
    move up
    PgDn
    move down
    ↑
    pitch up
    ↓
    pitch down
    ←
    yaw left
    →
    yaw right
    U
    unfollow the robot (if a tekkotsu robot has connected)
    See Advanced Usage below for more controls

  3. Loading custom environments

    You can load environment files either by passing file names as arguments on the command line:

    ./mirage worlds/tictactoe.mirage

    Mac OS X users can also double-click or drag-and-drop a file on the application to launch with that environment. Mirage can load .kin kinematic files, or its own .mirage environment files. You can load multiple files to combine their effects.

    See the Configuration section below for more information on customizing Mirage's environment, as well as the World Builder tool.

  4. Connecting Tekkotsu

    We will now launch Tekkotsu and tell it to connect to Mirage. If you have not yet built and run a Tekkotsu project, see these instructions for help. Alternatively, see Advanced Usage below for other examples of clients which can connect to Mirage (e.g. mazegen).

    In a new terminal, change to your project directory and run Tekkotsu with the -c mirage.plist arguments.

    cd PROJECT
    ./tekkotsu-TARGET -c mirage.plist

    This will load the hardware abstraction layer settings from the mirage.plist file, so Tekkotsu will talk to Mirage instead of looking for "real" hardware. It is possible to run Mirage in parallel with physical hardware, or on a remote machine, by customizing the HAL settings at the Tekkotsu command prompt.

Advanced Mirage Usage

Robot Locomotion

Mirage supports two forms of robot locomotion: pure physics-based simulation, and “assisted” locomotion. The former is useful if you have an accurate model of your robot's mass distribution and you want to test the stability of different gaits. The latter “assisted” method uses hints from the walk engine to hold support feet immobile so that the resulting locomotion is nearly perfect, without slippage or falling over. The assisted method is also the only way to move a robot when it has incomplete physics information, such as unspecified mass or collision shapes.

Further, robots can be wheeled or legged. The effects of various combinations of wheeled, legged, with or without physics configuration, and with or without locomotion assistance is listed in the following table:

The “Mass” column refers to LinkComponents (and thus derived KinematicJoints) which have non-zero Mass specified. In this column, the value “Partial” means the root KinematicJoint (BaseFrame) of the robot DOES NOT have mass, but all of its sub-links (i.e. moving parts) DO have mass.

The “Shape” column refers to LinkComponents (and thus derived KinematicJoints) which have a CollisionModel specification. The regular Model is used for display only, and is typically too high-resolution to use for physics simulation. You must specify one or more primitive collision shapes which approximate the display model in order to allow physical simulation of object interaction. (hint: the ‘H’ key will switch to displaying collision shapes instead of the usual display models.)

The “Assisted” column refers to whether the MirageDriver's PhysicsWalk or PhysicsWheels is DISABLED. (e.g. Drivers.Mirage.PhysicsWalk=false) If appropriate physics setting is enabled, then only normal physical simulation is applied, allowing ground contacts to slip. If physics interaction is disabled in the driver, then the walk engine's intended foot contacts are sent to Mirage, allowing it to 'assist' the locomotion. As summarized in the table, robots lacking complete physics specification require this assistance in order to move.

Mass Shape Assisted Result Usage CPU
No No No Immobile, no environmental interaction Graphics visualization, vision tests (it’s a “ghost”) Low
No No Yes Ground plane mobility, no environmental interaction Low
No Yes No Immobile, one-way interaction

Simple manipulation tests: poor simulation accuracy (effector has no true momentum, collision contacts are a heuristic)

“One-way interactions” because objects cannot push back, or in other words the robot is infinitely strong.

 Low
No Yes Yes Ground plane mobility, one-way interaction Low
Partial* Yes No Immobile, but can physically interact Fixed robots like HandEye: body is bolted down, but limbs can interact with environment Med
Partial* Yes Yes Obstacle-sensitive mobility, allows environmental interaction except with the body itself Almost-perfect locomotion for wheeled and legged robots: will respect obstacles and ground for joint motion, but body will move without physics; wheeled robots can ride over obstacles without risk of high-centering Med
Yes No Cannot use mass without shape (falls through ground, nothing to hold it up)
Yes Yes No Purely physical locomotion: simulates friction, momentum, support Realistic wheeled robot motion, or when developing new legged locomotion gaits (assuming an accurate mass model of the robot!) Med
Yes Yes Yes Semi-physics based locomotion: feet/wheels will not slip but otherwise move under physics control.

Navigation tests for robots when you wish to minimize locomotion error.

This is very similar to the “partial mass” configuration, but allows more realistic interaction between feet, body, and environment (i.e. slightly less ‘perfect’)

 High

* Partial indicates that the robot has a zero mass body (base frame) but has positive mass listed for its other links.

The assisted locomotion for legged robots can be controlled via the Mirage driver's PhysicsWalk and PhysicsWheels setting (see 'help set Drivers.Mirage.PhysicsWalk' from the Tekkotsu HAL command line). Enabling PhysicsWalk/Wheels will prevent the Tekkotsu executable from sending foot location or wheel speed hints to Mirage.

Environment Configuration

The Mirage environment begins with a cloudy blue sky, a single light, and a ground plane with a reference frame at the origin. You can change many aspects of the configuration listed below, including adding objects, simulation speed, and graphics options.

A Mirage environment file is an XML format based on the Property List used by Apple for its configuration files. For example, to configure the user's camera starting position and orientation:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Observer</key> <dict>
<key>Location</key> <array>
<real>500</real>
<real>0</real>
<real>600</real>
</array>
<key>PointAt</key> <array>
<real>-200</real>
<real>200</real>
<real>0</real>
</array>
</dict>
</dict>
</plist>

Other supported value types include string, integer, true, and false.

The Environment dictionary is the root element of the property list. You should name your property list with the .mirage extension so that the application can be associated with the file. This should allow you to double-click environment files to launch Mirage with that environment.

You do not have to specify all values in a dictionary, unspecified values simply retain their current value. This also allows you to launch with multiple environment files to combine their settings.

Note specialized types: