The simulator uses the AGEIA PhysX engine to simulate physical interactions within the virtual environment. It requires version 2.7.0 of the PhysX engine. You can see which version you have installed by selecting the AGEIA item from the Start menu and then selecting ageia PhysX Properties. Make sure that V2.7.0 is displayed as one of the installed versions on the Info tab. You can also run the simple demo on the Demo tab to verify that the engine is working properly.

One of the great features of the AGEIA PhysX engine is that it can be accelerated with specialized hardware. You can find out more about this option on the AGEIA website at www.ageia.com. You can also download the latest AGEIA run-time drivers from www.ageia.com/drivers/drivers.html.

You may find it useful to download the entire AGEIA development SDK to learn more about how the physics engine works. While the PhysX APIs are not directly exposed by the simulator, an understanding of the engine and the objects it supports is very helpful. It is necessary to register before downloading the PhysX SDK from the following website: www.ageia.com/developers/downloads.html.

The Microsoft XNA library is a managed code implementation of the DirectX APIs. The simulator uses the Microsoft XNA Framework, which is a set of APIs that provide access to the underlying DirectX subsystem from managed code.

MRDS version 1.5 requires version 1.0 of the XNA Framework or the version 1.0 refresh, which was made available on April 24, 2007. You can find a link to the download page for the XNA Framework on the XNA Game Studio Express page at http://msdn2.microsoft.com/en-us/xna/aa937795.aspx. Alternatively, you can go to the XNA home page (www.microsoft.com/xna) and search for the framework download.

You may also find it helpful to download the XNA Game Studio Express SDK, which provides documentation on XNA classes and APIs. Some of these are used in the simulation entity sample code provided in the MRDS SDK. A link to the download page for XNA Game Studio Express can be found on the web page referenced above.

DirectX is a set of system APIs that provide access to graphics, sound, and input devices. The simulator in MRDS version 1.5 requires a DirectX runtime at least as recent as April, 2007. You can find the download link for this by loading the following page and searching for "DirectX Redist (April 2007)" on www.microsoft.com/downloads.

You may also find it helpful to download the entire DirectX SDK. This SDK includes a variety of tools that aid in making texture maps and other content for simulator scenes. You can find a download link for this by loading the aforementioned page and searching for "DirectX SDK – (April 2007)."

Shown in Figure 5-7, this is the default rendering mode, and you are already well acquainted with it. In this mode, the world is rendered to look its best—with fully rendered 3D meshes and lighting effects. This is the mode that you will probably use most often.

Figure 5.7. Figure 5-7

In this mode, shown in Figure 5-8, the world is still rendered with 3D meshes and lighting effects, but only the outline of each triangle is drawn. This quickly gives you a good idea whether the 3D meshes you are displaying have the proper resolution. Some meshes are so dense with polygons that they look about the same in wireframe mode as in the visual mode, which means they contain too many polygons and may be loading your graphics card more than necessary. Many modeling programs provide a way to reduce the number of polygons in a model.

Another benefit of wireframe rendering mode is that you can see through the objects in the scene. This is particularly helpful when you have just added a great new robot to your scene but it fails to appear. Switching over to wireframe mode shows that you accidentally embedded it in the couch.

Figure 5.8. Figure 5-8

The physics rendering mode (see Figure 5-9) shows you the physics shapes that make up the scene. This is the view that shows the physics shapes that the physics engine works with. Complex objects can sometimes be represented by very simple physics shapes such as boxes or spheres. The physics rendering mode enables you to see the scene the same way the physics engine sees it. If you notice that objects aren't colliding or moving the way you might expect, then switch to the physics rendering mode to see their underlying physics shapes.

It might be surprising but this mode can tax your graphics card more than the visual rendering mode even though less geometry is being drawn. This is because the shapes are composed of individual lines, which are drawn less efficiently than 3D meshes.

Figure 5.9. Figure 5-9

In Figure 5-9, you can see the three most common physics shapes: the sphere, the box, and the capsule. Spheres are defined by their radius. Boxes are defined by their dimensions along the X, Y, and Z axes. Capsules are cylinders with rounded ends, and they are defined by the radius of the cylinder and their height along the Y axis. Each of these shapes can also have a position offset and a rotation around each axis.

Notice in Figure 5-9 that each shape has coordinate axes drawn at its origin. You can deduce from the display that the origin of a sphere is its center. Although you can't see the color in the book, on the screen the X axis is drawn in red, the Y axis is green, and the Z axis is blue.

The simulation environment is composed of objects called entities, which typically represent a single rigid body such as a robot chassis that may contain multiple shapes. Each entity contains an optional 3D mesh and zero or more physics shapes. The visual representation of the object and the physics representation exist side-by-side. Entities are always positioned and rotated as a single object.

In Figure 5-9, each entity has a cube that represents its center of mass. On the screen, the cube is red if the entity is controlled manually (kinematic), and white if the entity is controlled by the physics simulator. Each of the marbles in the scene is controlled by the physics engine; but the ramp and the mill supports have a red center-of-mass box, indicating that they are controlled by the program and not by the physics engine. All the pegs that the balls fall through are contained by a single entity, and you can see that this entity is kinematic by its red center-of-mass cube.

This mode (see Figure 5-10) combines the visual mode with the physics mode. In some cases, it is easier to see which outlines go with which shapes in this mode. The outlines of the physics shapes are drawn as if the visual rendering were transparent so that you can still see physics shapes that are obscured by other entities. This rendering mode will typically tax your graphics card the most, and you may notice the frame rate drop.

Figure 5.10. Figure 5-10

This is what your graphics scene looks like with the lens cover on the camera. At night. This mode is for those hardy souls who want to use the simulator completely for physics simulation and don't want to waste any time rendering. Turn the status bar on and select this rendering mode to see how many frames are processed per second. You'll learn how to use this mode a little later.

You've already seen how to save and load an entire scene. It is also possible to save and load a subset of a scene. Entities can be

Sometimes it is more convenient to cut or copy and then paste selected entities. This is also done using the Entities menu. You can select one or more entities using the checkboxes in the Entities pane and then select either Cut or Copy from the Entities menu. At this point, the entities are serialized to a file called SimEditor.Paste in the Store directory. If you select Cut, the entities are deleted from the scene. When you click Entities

You can click Entities

Press OK when all of the selections are correct. The simulator will then display a dialog with properties for each parameter in the constructor of the new entity. When there are several constructors for an entity, the constructor defined immediately after the default constructor is selected. Press OK when all of the constructor parameters have been defined, and the entity will be created.

Occasionally, you must set some of the entity properties before you can successfully create the entity. For example, a SingleShapeEntity requires a shape to be defined but it cannot be specified in the constructor that is presented. The entity will appear in the Entities pane but it will have a red exclamation point next to it, indicating that there was an error in its creation. Look at the InitError property of the entity to see whether it provides some information about why the entity could not be initialized. In the case of the SingleShapeEntity, clicking one of the shape properties and defining a valid shape will clear the error, enabling the entity to be initialized.

The simulator supports the idea of child entities, which are entities that are defined relative to a parent entity. If you add a SingleShapeEntity as a child entity of another SingleShapeEntity, the child will be attached to the parent with a fixed joint that effectively glues the two pieces together. The physics engine treats the pair as if they were one entity.

When the simulator is in Edit mode, you can move and rotate the parent entity and the child entity moves with it. When you move or rotate the child entity, it changes the attachment of the child to the parent to accommodate the new position or rotation. This is how you can change the way in which the child is attached to the parent.

You can make one entity a child of another using the following steps:

You can also make an entity a child when you create it using the New Entity dialog described earlier by selecting the parent entity in the appropriate drop-down list.

Graphics assets determine how the entity looks. You can specify a new DefaultTexture, Effect, or Mesh to change the appearance of an entity:

The following entity state properties appear under the Misc heading:

These properties in the entity state define physical characteristics of the entity:

You don't really pay a lot of attention to the sky until there isn't one. The sky provides diffuse scattered light that illuminates objects in the scene. It is also sometimes useful to simulate bright and overcast outdoor conditions. The difference between the Sky entity (see Figure 5-15a) and the SkyDome entity (see Figure 5-15b) is the way they are drawn:

Figure 5.15. Figure 5-15

Both the Sky entity and the SkyDome entity can add to the diffuse lighting of the scene. The color and intensity of light that they cast on the entities in the scene is defined by a special texture map called a cube map. To visualize how a cube map works, imagine yourself on the inside of a giant cube. Each of the six faces of the cube has an image on it so no matter which direction you look, you see a pixel in one of the images. The lighting cube map surrounds the entire scene and defines the color and intensity of the light that shines on the entities from each direction. It is common to define a diffuse light map that lights entities brightly from above and less from the sides. The illumination coming from below is usually a little more than from the sides to simulate light scattering from the ground.

The Sky and SkyDome entities also provide a way to set the fog in the scene. The FogColor property defines the color of the fog. For a night scene, you want to use black fog, and for a day scene, grayish or white fog. Using the FogStart property, you can also specify the distance at which fog begins to appear. The FogEnd property specifies the distance at which entities in the scene are completely fogged. The fog increases linearly between the FogStart distance and the FogEnd distance.

One diffuse sky texture is provided with the MRDS kit. It is called, oddly enough, sky_diff.dds. The .dds format is associated with DirectX, and the extension was originally an abbreviation for Direct Draw Surface. These days, .dds files are most often used as texture maps for Direct3D. You can edit and create .dds texture maps using the DirectX Texture Tool, which is part of the DirectX SDK described previously in this chapter under the section "Software Requirements."

The simulator changes the Y offset of the Sky and Skydome entities to follow the eyepoint of the Main Camera. This prevents the camera from ever going above the sky. Do you remember that episode of Star Trek in which a whole colony of people were living inside a hollowed-out asteroid that was a spaceship, except they didn't know it was a spaceship until an old guy climbed a mountain and touched the sky? You don't have to worry about that in the simulation environment.

If you find yourself occasionally becoming disoriented in the simulation environment, you can literally paint a compass in the sky using the Sky entity. Start the Simulation Editor by pressing F5 and then select the Sky entity. In the VisualTexture property, select Directions.dds. This texture will paint the direction you are facing on the sky (see Figure 5-16). For example, if you are looking along the +Z axis, then you should see +Z ahead of you.

Figure 5.16. Figure 5-16

The HeightFieldEntity is used as a ground plane in many of the simulation tutorials provided with the SDK. It is one of the more important components in the scene because without it, everything falls into an abyss.

A HeightFieldEntity is flat, with an elevation of 0 meters. It may seem infinitely large but it is really just 49,000 square meters, ranging from (−4000, 0, −4000) to (3000, 0, 3000). Columbus would not have fared well in the simulation environment.

A HeightField shape contains a grid of height values. The HeightFieldEntity uses a grid of 8 rows by 8 columns, and it sets the altitude of each height value to 0.

The most remarkable feature of the HeightFieldEntity is the texture that is applied to it. The default texture used in most of the SDK samples is 03RamieSc.dds, which looks a little like industrial carpet. It is a little depressing to look at 49,000 square meters of carpet, so you are encouraged to find another texture for your scenes. The only requirement is that the texture should tile properly without any seams, because it is repeated across the ground many times. The default scaling for the texture on the ground plane is 1 meter by 1 meter. This scale can be changed programmatically but it can't be changed using the Simulation Editor.

The friction and restitution (or bounciness) of the ground can be changed by editing the HeightFieldShape property. This brings up a dialog that enables you to edit its shape properties, among which are StaticFriction, DynamicFriction, and Restitution. These shape properties are described more fully in the upcoming section, which describes SingleShapeEntities.

The TerrainEntity is a much more interesting way to describe the ground than the HeightFieldEntity. The HeightFieldEntity is fine for simulating indoor scenes, but the challenge that many robots face is navigating uneven ground in an outdoor environment. The TerrainEntity provides a way to construct such an environment.

You can take a look at a TerrainEntity by clicking Start

Figure 5.17. Figure 5-17

There aren't many TerrainEntity properties that you can modify in the Simulation Editor, but you can change the image that generates the HeightField and the texture that you apply to it. Start the Simulation Editor by pressing F5 and select the entity named Terrain. Change TerrainFileName to another image filename, such as particle.bmp. Nothing immediately happens because this particular entity does not automatically refresh when a property is changed. With the TerrainEntity still selected, press Ctrl+X and then Ctrl+V to refresh the terrain. You'll notice that the ground level has changed noticeably, and when you leave the Simulation Editor by pressing F5, the physics engine will pop the buried objects out of the ground.

You can change the texture that is applied to the TerrainEntity by changing the DefaultTexture in the EntityState property.

The TerrainLODEntity is identical to the TerrainEntity except that it does some extra tricks to try to reduce the load on the graphics system. It calculates a reduced resolution version of each section of the height field and then uses that version when the section is far away from the eyepoint. This reduces the number of triangles that must be drawn, as shown in Figure 5-18. The left side of the figure (a) shows the TerrainEntity and the right side (b) shows the TerrainEntityLOD. It does not reduce the number of HeightField samples used by the physics engine, so it does not affect physics behavior.

Figure 5.18. Figure 5-18

Unfortunately, the TerrainEntityLOD may not be suitable for many applications because it changes the height values for portions of the terrain in the distance, which may cause some entities to be incorrectly visible or obscured in the distance. In addition, it makes no attempt to seam together the edges of each section, so you may see unattractive cracks between sections. Nonetheless, if your graphics card is struggling to render a scene with terrain, the TerrainEntityLOD is an option for you.

You use a directional light to model a light that is very far away, such as the sun. The position of the light doesn't matter, only its direction. Most of the tutorial and sample scenes provided with the SDK include a directional light named Sun. Put the simulator into Edit mode by pressing F5 and select the Sun entity. Now select its Rotation property and drag the left mouse button while holding the Ctrl key to see how changing the direction of the light affects the lighting in the scene.

When the simulator is in Edit mode, LightEntities are represented by simple meshes, as shown in Figure 5-19 (from left to right, directional lights, omni lights, and spot lights).

Figure 5.19. Figure 5-19

The Color property defines the color of the light for all light types. The SpotUmbra, FalloffEnd, and FalloffStart properties do not affect directional lights.

Omni lights are so named because they send light out in every direction. Consider light bulbs. These lights are usually very close to the objects that they illuminate, so their position is very important; but because they cast light in every direction, their rotation is unimportant.

You can change the Sun to be an omni light by changing its Type property. Try changing its rotation just as you did for the directional light. No effect. Now select its Position property and move the light around. You can see that even small changes in the position of the light change the way entities are lit in the scene.

If you ever need to position a light in the scene but you can't find it, you can use the same trick that works for every other entity. Select it in the Entities pane and then hold the Crtl key and press the up arrow. The eyepoint will be moved to be just above the selected light.

The FalloffStart and FalloffEnd properties affect both omni lights and spot lights. They define the distance at which the light starts to diminish and the distance after which the light has no effect, respectively. Unlike the sun, light bulbs tend to have limited range here on earth.

Finally, a light for which position and rotation are both important. In the real world, many light bulbs have reflectors and shades to direct the light in a particular direction. That is exactly what a spot light does. It projects a cone of light with the apex at its position. The angle swept out by the cone is specified by the SpotUmbra property. These types of lights are good for headlights or emphasis lights.

Light shadows provide cues to our brain regarding the position of objects in the world. They can be a help to robot vision processing algorithms and they can also be an added challenge. The simulator supports casting shadows from one light. Each LightEntity has a CastsShadows property, which, when set to True, causes that light to cast shadows. Switch the Sun back to an omni light and turn on shadows. The first time shadows are turned on, the simulator must generate special shadow meshes for each mesh in the scene. If a mesh was read from a file, the shadow mesh is saved to a file in the storemedia directory with the same name as the mesh file but with a .shadowMesh.bin extension. It may take several seconds to generate shadow meshes for very complex or large models. For example, the LEGO Tribot can take 20–30 seconds on a fast machine. The next time the shadow meshes are needed, they are read from the disk, rather than generated. If the original mesh is changed, its shadow mesh is updated.

Move the omni light around the scene and note how the shadows are updated (Figure 5-20 shows shadows cast from a single omni light). The entities in the scene are self-shadowing, which means that one part of an entity can cast a shadow on another part.

If more than one light has the CastsShadows property set to True, the simulator will cast shadows from the first light encountered as it is drawing the scene. Be aware that drawing shadows is expensive and can slow down the rendering of the scene substantially.

Figure 5.20. Figure 5-20

As the name implies, this entity is wrapped around a single physics shape—either a sphere, a box, or a capsule. This is the easiest way to add a single object to the environment: Decide which shape will best represent the object, specify its dimensions, and add it to the scene. You can even specify a mesh to make it look more like the object you are modeling.

The bluesphere, the goldenscapsule, and the greybox are good examples of SingleShape entities that use the various physics shapes. In the Simulation Editor, you'll notice that SingleShape entities have three properties under the Shape category representing each of the three possible shapes. You can edit the properties for the shape that is defined, or you can click the value of one of the other shape properties to change the entity to use that shape. This is probably a good time to talk about general shape properties because they are used in nearly every entity.

Expand the shape properties associated with the sphere in the bluesphere entity. The properties are divided into the following categories: MassDensity, Material, Misc, and Pose. The Material category is where the friction and restitution properties of the shape are specified. Several shapes may share the same material, and changing the material for one shape will affect the other shapes as well.

Several of the entities in the terrain scene do not specify a 3D mesh, so their visual mesh is built from the shape itself. The StreetCone entity does specify a 3D mesh. Switch to the combined view and look at this entity, and you will see that it is just a single cube for physics purposes but looks like a traffic conevisually.

The MultiShapeEntity is much like the SingleShapeEntity except that it contains—yes, you guessed it—multiple shapes. It only supports boxes and spheres but you can have as many of them as you like. The table_mesh entity in the scene is built from multiple box shapes, but you would never know it until you select the physics view because it also uses a 3D mesh to give it a nicer visual appearance.

The state for a MultiShapeEntity is very similar to the state for a SingleShapeEntity except that the BoxShapes property is a collection of boxes and the SphereShapes property is a collection of spheres.

This entity enjoys the distinction of having the most syllables of any other built-in entity so it must be important. In some cases, it is not sufficient to have a single box represent the physical shape of an object because it just doesn't collide with other objects the right way. The simulator can construct a physics object called a simplified convex mesh from any 3D mesh. A convex mesh is built from the points of a convex hull, which is the smallest polyhedron containing all of the points of the original mesh. You can think of generating a simplified convex mesh as similar to taking an arbitrary mesh and wrapping it with shrink wrap. When you heat the shrink wrap and it pulls tightly around the object, the resulting shape is very close to the convex mesh representation. (Of course, the physics SDK does this using math, not shrink wrap.)

SimplifiedConvexMeshEnvironmentEntities interact with the physics environment just like spheres, boxes, and capsules except that they are more expensive to calculate. The table_phys_m is an example of this type of entity. It is shown in Figure 5-21 (right) along with a TriangleMeshEnvironmentEntity (left).

Figure 5.21. Figure 5-21

The state associated with a SimplifiedConvexMeshEnvironmentEntity is very similar to the other entities except that it must have a 3D mesh specified in the EntityState. This is the mesh that will be used to construct the convex mesh. The maximum number of polygons in the simplified convex mesh is 256.

This entity is very similar to the SimplifiedConvexMeshEnvironmentEntity except that the entire 3D mesh is used for the physics shape instead of constructing a convex mesh. Because the physics shape is identical to the visual shape, the entity will collide and move just like the visual shape.

You may be tempted to use a TriangleMeshEnvironmentEntity for every object in the scene, but you should be aware that this type of entity has some limitations. Collision detection is not as robust as it is for other shapes. If a shape moves fast enough that its center is inside the triangle mesh shape, then a collision may not be registered. In addition, SimplifiedConvexMeshEnvironmentEntities must be static entities, meaning they cannot be moved around in the environment, and they act as if they have infinite mass.

The best way to become familiar with differential drive robots is to drive one around. Click Start

Figure 5.22. Figure 5-22

Follow these steps to connect the dashboard to the differential drive service and drive the iRobot Create in the environment:

The LEGO NXT Tribot is the first robot you build with the LEGO NXT kit. It has two drive wheels and a castor in the back. It also has a number of sensors that you can mount to the robot, but the one in the simulation model is the touch sensor, or bumper. You can run an environment that contains a LEGO NXT Tribot, a Pioneer 3DX robot, and a lovely table by selecting Visual Simulation Environment Multiple Simulated Robots.

When you connect the Dashboard, you'll see three services. You can drive the Tribot by double-clicking the (LEGONXTMotorBase)/simulateddifferentialdrive/ service. This is the service that is used with all three differential drive robots in the simulator. It provides a connection between the DifferentialDriveEntity in the simulator and services outside the simulator. When you examine the ServiceContract property of the LEGO NXT Tribot, you will notice that it references the contract ID for the SimulatedDifferentialDrive service.

Put the simulator into Edit mode by pressing F5. You'll notice that the Physics menu turns red, indicating that the physics engine has been disabled. You'll also notice that you can no longer drive the robot. When you can't drive a robot in the simulation, ensure that the physics engine is enabled.

The LEGONXTMotorBase entity in the Entities pane has a single child entity, LEGONXTBumpers, which is a BumperArrayEntity. This entity has an array of box shapes that define where the bumpers are located. The LEGO NXT Tribot uses only a single box shape. The ServiceContract property of the LEGONXTBumpers entity is set to the contract identifier for the SimulatedBumper service. This service connects with the BumperArrayEntity and provides a way for other services to be notified when the bumpers are in contact with another shape.

The iRobot Create, the LEGO NXT Tribot, and the Pioneer 3DX entities all inherit from the DifferentialDriveEntity. This is what enables the SimulatedDifferentialDrive service to work with all three of them. Most of the properties of the DifferentialDriveEntity can only be set programmatically, but a few are useful in the Simulation Editor:

Not all robots in the simulation environment need to inherit from the DifferentialDriveEntity. It simply serves as a convenient way to provide common services and properties for two-wheeled differential drive robots. You'll learn how to implement more complicated robots in the next chapter.

The Pioneer 3DX Robot is manufactured by Mobile Robots, Inc. It is interesting because it has an onboard laser range finder and an onboard computer, so it is capable of autonomous movement. It also has bumpers, and the version in the simulator has a mounted webcam.

You've already learned about cameras in the scene but this camera is mounted to the robot as a child entity. When an entity is added as a child of another entity, its position and orientation are relative to the position and orientation of the parent. When the parent moves, the child moves with it. Adding a CameraEntity as a child entity of the Pioneer3DX entity causes the camera and its image to follow the robot.

The ServiceContract property of the robocam entity shows that it is associated with the SimulatedWebcam service. This service reads the images generated by the real-time camera and makes them available to other services or to users via a browser window. You can watch updated images from any real-time camera in the scene in a browser window by following these steps:

Figure 5.23. Figure 5-23

A laser range finder is a sophisticated and expensive device for measuring distance. It uses a laser to sweep a horizontal line in front of the robot. The laser measures the distance to objects in front of the robot by shining a low-power laser and then recording the light that is bounced off of objects. As the laser sweeps in a horizontal arc, the number of samples that it takes defines its angular resolution.

The LaserRangeFinderEntity simulates a laser range finder by casting rays into the simulation environment that correspond to laser samples. These rays are intersected with the physics shapes in the environment, and an array of distances is returned. Small, flashing, red circles are drawn in the environment at each intersection point. You may notice that these hit points are sometimes drawn in mid-air where no object is visible. This is usually because the physics shape that represents an entity is different from the visual mesh that represents the entity. This is the case with the table in the scene. Switching to combined rendering mode shows that the box shapes defining the sides of the table are quite different from the visual mesh of the table. The laser always operates on physics shapes.

The Dashboard user interface provides a way to visualize the laser range finder data. Follow these steps to enable this feature: