VSE Release Notes
This section contains Release Notes specifically about the Visual Simulation Environment. The first section is related to RDS 2008 R3. The other sections are from previous releases (RDS 2008 R2 and RDS 2008) and are included for reference. Please ignore references to different Editions in the subsequent sections because RDS 2008 R3 contains all features.
VSE 2008 R3
With the release of RDS 2008 R3 there are no longer separate Editions. Therefore the features of the Simulator that were previously missing from the Express Edition are now available to all users. This includes Edit mode, Context Menu, the Floorplan Editor and Collada import.
Two new simulation environments have been added in RDS 2008 R3. They were created by SimplySim, a Microsoft Robotics partner, and are licensed for release with RDS.
- Modern House
These are large environments with a lot of detail. Therefore they take a while to load. Typically it should only be 10 to 30 seconds, but on some computers this might be as much as 5 minutes. Please be patient.
The old Simulation Tutorials 1 to 6 (removed in RDS 2008 R2) are now available from CodePlex and are not included in the RDS package. Note that the Articulated Arm tutorial in 2008 R3 is a duplicate of one of the old tutorials.
Modern House Environment
The Modern House is a two-level house with an outdoor swimming pool and landscaping.
The Modern House contains many different rooms and the doors have been designed so that they can be opened or closed. To change the position of a door, do the following:
- Find the door you want to change.
- Select Edit mode in the simulator.
- Right-click on the door with the mouse to select it (the entity will be shown in the Properties panel). To confirm that you have selected the correct door, you can press the Ctrl key and it will be highlighted.
- Change the value of the rotation about the Y axis. Depending on which door it is, the usual values are 0, -90, 90 or 180 degrees.
- Save the scene with your new door position(s).
If you started the simulator using a manifest, either save the scene with the same name as the existing simulation state file or edit the manifest to use the new state file that you just created.
The Factory environment is a large compound containing several buildings and other items. Two of the buildings have detailed interiors as shown in the diagrams below.
None of the items you see in the Factory environment are functional, i.e. you cannot run the conveyor belts or drive the forklift.
In Windows 7 you can change the size of fonts on your screen. If you increase the font size then dialog boxes displayed by the Simulator might be too small for the text they contain. The main effect is that the OK and Cancel buttons might be cut off at the bottom of the dialogs.
Previous Release Notes
The following sections contain release notes from previous versions of VSE.
VSE 2008 R2
This section lists the new and changed features of the Visual Simulation Environment. Because 2008 R2 is a minor release, the original notes from the 2008 release are also included at the end.
The Collada Update that was released in January 2009 has been incorporated into the 2008 R2 release. It is not available in RDS Express Edition.
When you run the Collada Scene from the Start Menu, there an error message appears in the Command Prompt window during startup of the service. This can be ignored.
A range of new sensors has been added to the Simulator. These include:
- Light (Brightness)
- Infrared Range
These sensors are intended as samples and not necessarily as exact representations of real sensors. For instance, the GPS sensor does not return Latitude and Longitude, so if you need the data in this format you will have to transform it from coordinate values in meters. Full source code is provided and you will find these sample sensors useful for writing your own sensor services. Several of these sensors are demonstrated in the new Simulation Tutorials.
The Simulation Tutorials have been completely restructured. The old tutorials have been removed. If you still want the old tutorials, please obtain them from the 2008 release.
The tutorials are now broken into three categories: Beginner, Intermediate and Advanced. New users should undertake the tutorials in this order.
New Feature Descriptions
Record and Playback Capability
The simulator now has the ability to record the position and orientation of each entity and to save that information to a file. The file can later be replayed.
The Playback Toolbar can be displayed by selecting Playback Bar option from the View menu. The record button is the button with the red circle on the left. Pressing this button will cause the simulator to save the current simulation state and immediately begin recording the position and orientation of each entity in the scene each frame. The stop button contains a blue square. Clicking this button while the simulator is recording causes the recording to stop. The simulator will prompt for a filename with a default .plb extension. The recorded data is saved to the file in a gzip compressed XML format.
The play button contains a blue triangle pointing to the right. Clicking this button while no playback is currently in progress causes the simulator to prompt for a filename to load playback data. The data is loaded from the specified file and a trackbar is displayed to show the playback progress. The simulator replaces its current state with the state in the playback file. This means that the entities in the simulator before playback are deleted and replaced with the entities in the playback file. The simulator plays back the recorded position and orientation information for each entity. The data is interpolated so that the motion of the entities is smooth even if the frame-rate during playback is different than when the file was recorded. Since only position and orientation data is recorded, changes such as adding new entities to the scene or changing other attributes of entities such as color or texture will not be recorded.
The Pause button contains two vertical bars. Pressing this button during playback will pause the playback. Dragging the trackbar to the left or right quickly scans through the playback file. Clicking Play again will resume the playback. When the playback reaches the end, it is paused and clicking Play will cause the playback to resume from the beginning. At any time during playback, clicking the Stop button will stop playback and unload the data from memory.
While a playback is in progress, the cameras in the scene are controlled by the playback data. However, left-clicking on the render window will disengage the current camera from playback so that the scene can be observed from a different vantage point from where it was recorded. The next time the playback is started from the beginning, the camera will again be bound to the playback data.
Recording and playback can also be started and finished by sending a message to the Simulation Engine service.
Embedded Media Resources
Media resources such as texture maps, bitmaps, and mesh files are usually files that reside in the store\media directory. In some cases it is desirable to embed these resources in a service rather than leaving them in discrete files.
The steps to add a file to a service as an embedded resource are outlined in Service Tutorial 6. In a nutshell, you add the file to your service project and in its properties, you set the Build Action to embedded resource. When the service is started, the embedded resources are made available to other DSS services such as the Simulation Engine Service.
The next time the simulation engine needs to load a media resource, it will first attempt to find the media file in store\media. If it cannot be found there, the simulator will attempt to load it as an embedded resource. The first time an embedded resource load is attempted, the simulator waits for the resource to become available for a period of time specified as a number of milliseconds in the EmbeddedResourceLoadTimeoutMS item in the SimulationEngine.config.xml file in the config directory. This allows the embedded resource service to be started in a manifest along with the Simulation Engine service and avoids race conditions as the services start up.
The simulator can help you define a service that contains embedded media resources. Select Create Embedded Resources from the File menu. The simulator prompts for a directory and project name for the service to be created and then creates a service that contains every media resource currently in use by the simulator as an embedded resource. This service can then be built and included in a DssDeploy package with other services and the individual media files will not need to be included in the package.
While most objects in the simulation environment are three-dimensional, it is sometimes useful to have two-dimensional labels or billboards. The new SpriteEntity can be used for this purpose. A SpriteEntity is a two-dimensional texture-mapped rectangle that can be positioned and oriented in the simulation environment like any other entity. Because it does not have a physics shape associated with it, it does not collide with other entities in the environment.
A sprite entity can be fixed in space or it can pivot to face the active camera. If it pivots, it can be set to pivot about its center point or to pivot around its Y axis.
The texture map associated with a sprite entity can be easily modified. The GetBitmap method returns a bitmap with the proper dimensions and pixel format to match the texture on the sprite. After the bitmap has been drawn on, it is passed back to the sprite entity using the SetBitmap method and it is copied to the sprite texture map and appears on the screen.
The SpriteEntity source code appears in entities.cs so it is easy to create specialized sprites that inherit the SpriteEntity functionality. Two such sprite entities have already been provided. The CameraSpriteEntity is designed to be a child entity of a CameraEntity. It displays the image currently seen by the camera. The EntityNameSprite is designed to be a child entity of any other entity and it displays the name of that entity. Source code for these two entities is also provided in entities.cs.
|This feature is not available in the following Edition(s): Express|
Several commonly used simulation editor commands are now available on a context menu. When the right mouse button is clicked in the rendering window, the entity under the mouse click is selected and the context menu is displayed. If no entity is under the mouse click, none of the entities in the scene are selected. The context menu has the following options:
|Cut||Remove the currently selected entity and put it in the Simulation Editor paste buffer|
|Copy||Put the currently selected entity in the Simulation Editor paste buffer|
|Paste||Copy the entity currently in the simulation editor paste buffer into the simulation scene|
|MoveXZ||Constrain the movement of the selected object to be in the XZ plane (horizontal)|
|MoveX||Constrain the movement of the selected object to be in the X direction|
|MoveY||Constrain the movement of the selected object to be in the Y direction (vertical)|
|MoveZ||Constrain the movement of the selected object to be in the Z direction|
|MoveXYZ||Allow the selected object to move in any direction|
|RotateX||Constrain the rotation of the selected object to be around the X axis|
|RotateY||Constrain the rotation of the selected object to be around the Y axis|
|RotateZ||Constrain the rotation of the selected object to be around the Z axis|
|RotateXYZ||Allow the selected object to rotate freely around all axes|
|New Entity||Display the New Entity dialog box|
Every entity can have a custom mesh that represents it visually. Some entities such as the SimplifiedConvexMeshEnvironmentEntity and the TriangleMeshEnvironmentEntity build their physics shapes from their visual mesh. A new Mesh entity has been defined to generalize this idea. A mesh entity must have a custom mesh .obj or .bos file specified in its State.Assets.Mesh field. When it is initialized, it will create an entity with specified visual mesh and also a physics shape based on one of the following values in its MeshEntityType field:
|Box||The physics shape is a box the same size as the bounding box of the custom mesh.|
|Sphere||The physics shape is a sphere the same size as the bounding sphere of the custom mesh.|
|Convex||The physics shape is a convex mesh built from the custom mesh.|
|Triangle||The physics shape is a triangle mesh which is exactly the same as the custom mesh.|
|This feature is not available in the following Edition(s): Express|
Creating complicated structures and interior simulation scenes has been difficult in the past. In this release, the FloorplanEntity and a new 2D editing tool have been provided to make this easier. The FloorplanEntity holds a collection of wall items, door items, and window items that that can be combined to represent the interior of a room, house, or other building.
To begin defining a new floorplan start the simulation editor by selecting Edit from the Mode Menu. Create a new FloorplanEntity by selecting New... from the Entity menu and then selecting the FloorplanEntity, giving it a name, and pressing OK. Select an initial position for the floorplan and press OK to create it. The new entity should appear with a check in the upper-right entities pane. Press the Edit Entity button to edit the floorplan entity. A 2D representation of the world appears in the render window and several buttons that represent floorplan items appear in the entities pane. Press the Wall button to create a new wall item. It appears in the render window with a red and green handle on each end. It is white on the interior to indicate that it is currently selected. Drag the left mouse button outside of the item to move the 2D map around. Drag the right mouse button to scale the map larger or smaller. Click inside any floorplan item to select it. Click and drag the interior of an item to drag it to a new location. Click and drag the red handle to grow or shrink that end of the item and likewise with the green handle. Press the left control key and the square handles change to circles indicating that the angle of the item can now be changed. Now drag the handles to change the size and angle of the entity. The position of each handle and the angle of the item are displayed at the top of the rendering window for the selected item. Pressing ctrl-C while an item is selected causes it to be duplicated. Pressing delete while an item is selected causes it to be deleted.
The FloorplanEntity properties define the default width and height for the floorplan items. A snap grid can be defined to help the walls to fit together properly. The spacing of the snap grid should be set to one half or one fourth the width of the wall. Individual floorplan items have properties associated with them that allow their height, width, window bottom, and window top to be customized.
Often, you will want to construct a floorplan based on a 2D floorplan image or CAD drawing. The floorplan entity allows an underlay image to be specified. Any image format such as .bmp, .jpg, or .tiff that is supported by GDI can be loaded. Also specify a scale for the image to determine how big it will appear in the 2D map. Select the desired wall thickness and create a wall item and then scale the underlay image so that the walls displayed in the image match the size of the wall item.
When you press the OK button, the FloorplanEntity is refreshed and physics objects and meshes are constructed to reflect the FloorplanEntity items. The Floorplan entity can be rotated or moved just like any other entity. Additional functionality will be provided in the future to specify floor tiles and texture maps for the walls. A sample floorplan scene can be loaded by selecting House Floorplan from the Start Menu under the Visual Simulation Environment menu.
Change in Shape LocalPose orientation
A bug in the Visual Simulation Environment in versions 1.0 and 1.5 caused the orientation quaternion in the LocalPose field of each shape to be interpreted incorrectly. The inverse of the rotation was used. If you are porting entities from MSRS 1.0 or 1.5 to the 2008 release of MRDS, and you have used the LocalPose orientation field to rotate a shape within an entity, you will need to negate the W component of the quaternion or use the negative of the angle in an AxisAngle definition. If you fail to do this, shapes with a non-zero LocalPose rotation will be rotated incorrectly.
Change in the PhysicsEntity ApplyLocalForce Method
The methods used to apply forces to an entity have changed as follows:
ApplyForce(Vector3 force) has changed to ApplyForce(Vector3 force, bool forceIsLocal)
The boolean forceIsLocal parameter indicates that the coordinates of the force vector are relative to the local coordinate frame of the entity if it is true. Otherwise the coordinates are relative to the world frame.
ApplyTorque(Vector3 torque) has changed to ApplyTorque(Vector3 force, bool torqueIsLocal)
The torqueIsLocal parameter has the same meaning as in the ApplyForce method.
ApplyForceAtLocalPosition(Vector3 force, Vector3 position) has changed to ApplyForceAtPosition(Vector3 force, Vector3 position, bool forceIsLocal, bool positionIsLocal)
The two boolean parameters indicate whether the force and position are in the entity local coordinate frame or in the world coordinate frame.
These methods specify a force or torque that is applied to the entity for the duration of the coming frame. This method must be called each frame in the Update method if a constant force or torque is desired. The ApplyForce method applies a force at all points on the entity and therefore generates no torque. The ApplyForceAtLocalPosition method applies the force at a specific position and can therefore generate torque on the entity.
Samples and Tutorials
- Embedded Simulation Environment: The EmbeddedSim sample shows how to embed the Visual Simulation Environment in a custom Windows Forms user interface.
- Simulated Pursuit Camera: The PursuitCamera sample shows how to implement a camera entity that follows behind a target and avoids obstacles.
- Simulated 4x4-drive: The SimulatedFourByFourDrive sample shows how to implement an entity that behaves like a 4x4 off-road vehicle.
Robotics Introduction: What's New?
© 2010 Microsoft Corporation. All Rights Reserved.