Virtual Earth 3D team blog : Virtual Earth 3D

Bing Maps 3D

NikolaiF — Sun, 14 Jun 2009 21:07:00 GMT

As you may be aware, the website changed names to Bing Maps: http://www.bing.com/maps/. The 3D view on the site is now called "Bing Maps 3D".

As a developer it doesn't change much for you, and in terms of the engine/SDK it's still valid to refer to it as "Virtual Earth 3D". The only technical issue I can think of is to repeat that it's a good idea to use fwlinks for the urls for our base layer data, as explained at the end of the post here.

Thanks!

Manual Rendering

NikolaiF — Sun, 19 Apr 2009 23:25:00 GMT

Folks have really reacted to my mention of manual rendering, so I've made a sample for it. Good thing, too, because to be frank there are a few warts. On the upside, however, it is possible to work around all of them and the code required is not too scary.

Get the code!

In this sample, I host a GlobeControl on a form like normal, but instead of using the built-in render thread I render on the UI thread using the manual render API. If you are content to let WinForms present to the screen for you, you're done at this point.

But it is common in these situations to want to get the rendered surface to make a movie, present in some other context like WPF, etc. I include an example of the most basic way to do this, which is the only official way to currently do it (WorldEngine.CaptureScreenShot). If this isn't good enough, and you're a bit more daring, it is possible to get our rendering surface and do more clever things with it. That's what the good folks at Infostrat did for their WPF code, and for the time being I actually recommend using their wrapper if you want to use WPF.

I've labelled all the warts and their workarounds with the tag "WORKAROUND" in the code so you can look more closely if you like, but you should also just be able to copy and paste the sample and get your code to work as it should. Also, this is not actually an an official part of the sample pack, but something similar to it will be.

Anisotropic Filtering

NikolaiF — Sun, 19 Apr 2009 20:11:00 GMT

Anisotropic has been a bit of a frustration for us because while it is very easy to do (it's really just a flag to DirectX), the compatibility issue I mentioned before made it a pain to actually get it in to the control. It's a shame we couldn't turn it on by default, but at least it's there. The effect of it is really quite dramatic, as you can see below. I took these images at this location, near the 405 and 90 interchange in Bellevue.

With anisotropic filtering enabled:

Without:

To turn it on in the website, click "options" in the upper right corner, then "3D settings", and finally check "Use anisotropic filtering". To turn it on in code:

plugIn.Host.RenderEngine.Graphics.Settings.UseAnisotropicFiltering = true;

These settings are remembered in the user.config file for future runs of the control. The perf penalty for this on cards that are even remotely modern is almost zero, so go turn it on now!

Data Format Revision

NikolaiF — Mon, 06 Apr 2009 20:17:00 GMT

As part of our version update, we are also updating the file format of our 3D buildings. The upside is that the new data format is significantly smaller, for faster download. The downside is that old versions of the code cannot understand the new data. However, in the short term this should not affect you. There will be a period where old data will still be served to clients that are using the Javascript API and the Managed API. This represents a bit of a compromise, because even clients that have updated to the new version will get the old data for this period, but we felt that this was better than releasing new code and breaking old (and existing) code on the same day.

To see the new data after the version update, simply navigate to maps.live.com and click 3D. The new data will be live on the site.

Once this period is over, clients that have updated will automatically begin receiving the new data without any required changes or interruptions. You will probably hardly notice, except that buildings of course will load faster. Clients that have not updated will break! You've been warned! The only issue really will be that buildings will not appear, and only if your code is directly adding model data sources.

The exact length of this period is TBD, but probably about a month. Our hope is that most everyone will update by then anyway, because the new version really is better. I will blog a reminder when the date is decided and approaching. As always, let me know if you will need any help during the transition.

In addition, in several samples I directly linked to the manifest files for some resources, like imagery, dem, and models. These are the urls used when creating DataSourceLayerData objects. I encourage you to instead use fwlinks, which are just redirects to the same resources. This will help us update data while minimizing impact to clients.

Road:  http://go.microsoft.com/fwlink/?LinkID=98770
Aerial:  http://go.microsoft.com/fwlink/?LinkID=98771
Hybrid:  http://go.microsoft.com/fwlink/?LinkID=98772
DEM:  http://go.microsoft.com/fwlink/?LinkID=98774
Models:  http://go.microsoft.com/fwlink/?LinkID=98775

Edit: took down the traffic link. If you are interested in traffic data, please see here: http://msdn.microsoft.com/en-us/library/bb877877.aspx

Logging

NikolaiF — Mon, 06 Apr 2009 00:21:00 GMT

At times it can be useful to know when and if errors are occurring in VE3D. When instructed, VE3D produces a log file that can be helpful for diagnosis. This requires editing the user.config file and adding an entry:

The user.config file is located at:

(Vista) C:\Users\{username}\AppData\LocalLow\Microsoft\Virtual Earth 3D

(XP) C:\Documents and Settings\{username}\Application Data\Microsoft\Virtual Earth 3D

Log files are generated at:

(Vista) C:\Users\{username}\AppData\LocalLow\Microsoft\Virtual Earth 3D

(XP) C:\Documents and Settings\{username}\Local Settings\Application Data\Microsoft\Virtual Earth 3D

To increase the verbosity of logs, add another entry to user.config:

The values are like so:

0: Critical errors only. These errors may affect users.
1: Warnings only. These are errors that are handled internally and should not affect users.
2: Informational. These are not errors, but can be useful in some cases for debugging.

Controlling Time

NikolaiF — Sun, 05 Oct 2008 22:11:00 GMT

Today we show a little of the "Time" sample. It demonstrates how to use the concepts of rendering time and world time.

In any rendering or simulation engine it is important to understand the system's concepts of time. VE3D uses two time concepts. The first is "rendering time", which is a time value specified at the beginning of each frame that should be used for all animation that frame. This value enables synchronization of all animation in the system, and accounts for things like changes in frame rate. The second is "world time", which is the time of day that is used in the system. Using this value enables everything that depends on time of day to be synchronized.

Both values can also be overridden. Rendering time can be overridden by replacing the "TimeStep" with a custom step. This is useful when, for example, recording a movie of an expensive animation. Smooth animation and framerate can be achieved despite the fact that the animation itself may be too expensive to render in realtime. Demonstrated in this sample is overriding world time to affect the sun and stars.

Click here to see it in action.

There are two modes to this sample page. The first simply speeds up time. The second rapidly changes the day, but not the time of day, so, you will see the position of the sun at 9 am as the seasons change. Fun things to notice: the stars move (the constellations are correct, too), the sun moves, shadows move, clouds change color, and there are pretty sunsets and sunrises. All this goodness is built in to the new version, but you can only get them if you play with time through the managed control.

Get the code

Current Samples

NikolaiF — Thu, 25 Sep 2008 20:28:00 GMT

Here's the newest, most whiz-bang sample set we've got right at the moment.

Download The Samples!

See The Samples!

For the future, whenever we update the sample set we will update this post, to save you (and us) from having to slog through out-of-date links.

Updated April 9, 2009.

Current Control Version: 4.0

New Version of VE3D

NikolaiF — Thu, 25 Sep 2008 20:03:00 GMT

You may have noticed that we have not blogged recently, and that’s because we’ve been hard at work on the next version of Virtual Earth 3D. The new version features some rendering improvements for the general user, but the most exciting part is for devs (well, that's what we think, but we ARE devs). We have enabled partial trust plug-ins, which means you can put your plug-in on the web, create a page that references it, and users can go see it without having to install anything more than the basic VE3D control.

Behind the scenes, we load your plug-in’s dll to the client and execute it with a limited set of permissions. For example, the plug-in cannot access the file system on its own, but you can still do custom rendering and control like you could before. We’ve updated all the samples you’ve seen so far to run like this, except for the x file loader and the shortcut key (which was an example of how to install one, and is still a valid scenario in some cases). We’ve also added a few new samples to show some new functionality and demonstrate some stuff that’s been there for awhile but we hadn’t gotten a chance to show yet.

Existing code built against VE3D will need to be recompiled, and in some cases we’ve moved a few properties around. The samples should cover most of these changes, but please comment or send us feedback on items that you have trouble with.

Get the new version!

Get the new samples!

Animation

NikolaiF — Wed, 09 Jul 2008 00:26:00 GMT

Note: this entry references code for an older version of VE3D. The newest code samples are here.

Smoothly animated objects make for a more compelling 3D world, and in this entry we'll learn about using them. In the X File entry, the model that we loaded could be rotated around a point. This is pretty easy, but is limited. You can move the model around, rotate it, make it bigger or smaller, but can't change its basic shape and appearance. For complex animations like that, you may need to change the actual vertices or indices used to draw the model. To support that, we have the concept of dynamic buffers. These are buffers that are expected to be frequently recalculated, and are internally handled to make that more efficient. The attached sample shows how to use this in SurfaceActor, but it's pretty much the same as using static buffers. The only difference is that we Set the values in the buffer in every call to Update rather than just Add them once.

Get The Code.

Video: Bezier Surface in Virtual Earth 3D

When the code is normally running it does not draw a new frame as frequently as it could. This is to conserve CPU and other resources on the client machine when nothing is really happening. But when animating, this presents a problem because the aniamtion can look stuttery and inconsistent. The solution is to tell the system it needs to draw more frequently by calling

Host.NeedUpdate();

This can be called as many times per frame as you like, and simply sets a flag telling the system to render the next frame as soon as possible. It's a good idea to only call this when you have an animation actively running. In this case, it is called only when a ControlPoint is actually changing.

This sample also has some code demonstrating more usage of bindings to control user input in a custom fashion, similar to the Geometry sample but a little more complex.

New Intellisense Files

NikolaiF — Wed, 09 Jul 2008 00:18:00 GMT

Note: this entry references code for an older version of VE3D. The newest code samples are here.

Some entries were missing or incomplete from the xml intellisense files in the samples zip in the first post of this blog. I've posted a zip of the new xml files, and updated the samples zip itself. Just unzip the file and drop the new xml files in Program Files/Virtual Earth 3D. You'll need to restart Visual Studio to see them.

Loading a model into VE3D

NikolaiF — Tue, 27 May 2008 22:54:00 GMT

Note: this entry references code for an older version of VE3D. The newest code samples are here.

Commonly the models seen in any 3D product are created using specialized software packages, exported to a file, and then loaded into the end product. Unfortunately this version of Virtual Earth 3D does not yet have full support for this process, but by being a little more adventurous (than you already are), you can do it.

Although in theory the mechanisms in place in VE3D for specifying vertex buffers, index buffers, materials, etc, could be used to import most file formats by writing the converter yourself, most people don’t want to do that, especially given how complex the formats can be. Until such mechanisms are solidly in place, we will use DirectX’s ability to read X files, as exposed by one of our internal classes. We’ll convert that using relatively simple code into a MeshGraphicsObject (the same as used in SimpleObjectPlacement), wrap it in an Actor, and add it to our world.

The code shows how to do simple intersection tests against the mesh and animate it. We also demonstrate one way to do labeling of objects.

Get Sample Code

Will it break?

There’s an important point to be made here: the whole API here is officially “unsupported”, which mostly means that we are happy to help you here on the blog, but we don’t, for example, have official documentation on MSDN. One reason we’re not calling it official is that we’re still working on refining the code, and we do expect to make changes. We’d prefer not to break anyone, but if we need to change things in order to make it easier to not break you later – once that word changes to “supported” -- we’ll do it.

Only part of the code is going to be supported even after we flip that switch, specifically the assemblies that have been referenced in the samples we’ve released so far. In this sample, we reference Graphics3D, which is considered an internal assembly. You can still reference things there, and they’ll work, but they’ll be harder to use, the documentation will be thinner, and the chances of breaking changes happening across versions will be higher.

In short, everything now is “use at your own risk”, but some things are riskier than others, and this sample is in that category. When we do break things we will release information on this blog about how to fix them, and update our samples as well.

Basic Math

Heptazane — Tue, 06 May 2008 19:23:00 GMT

When working with things that exist on the globe, there is a fair bit of basic math that complicates your life. Let's start of with a mesh that you want to add to the Earth. We recommend that you orient your mesh so that it is facing along the Y axis, Z is up, and X is to the right, as shown with this car. While you can do your own thing, this will simplify using RollPitchYaw later, which is the most common way that we orient things locally.

Now the object needs to be placed on the Earth which involves transforming it from it's local space, onto the globe. The globe is a WGS84 ellipsoid that is laid out as shown in this image. Note that the Z axis points up through the North Pole, and the X axis points out through latitude\longitude 0,0 (just south of Ghana in the Atlantic).

So if your object is placed on this globe and it has a local yaw of 0, it will be facing North. If it has a local pitch of 0, it will be looking horizontally... approximately at the horizon. If your local orientation remains the same, but the position of the object changes on the surface of the globe, the global orientation of the object will change. To assist in the manipulation of position, local orientation, and global orientation, we provide the Microsoft.MapPoint.Rendering3D.Cameras.GeodeticViewpoint class. This class automatically handles the conversions, for example:

// Set up the viewpoint with a position and local orientation.
GeodeticViewpoint viewpoint = new GeodeticViewpoint();
viewpoint.Position.Location = new LatLonAlt.CreateUsingDegrees(33, -97, 10000); // Someplace over Dallas
viewpoint.LocalOrientation.RollPitchYaw = new RollPitchYaw(0, 0, 90.0 * Constants.RadiansPerDegree);

// Ask for the global orientation.
LookAtLookUp globalOrientation = viewpoint.Orientation.LookAtLookUp;

Note that the local yaw is set to 90 degrees which will face West. The reason is that RollPitchYaw represents a rotation around the Y, X, and Z axes respectively. So a Yaw rotation is the left most diagram below. This diagram holds for any use of Matrix4x4D.RotationX, Y, or Z, and can be useful in mentally visualizing how you're rotating in our coordinate space.

The GeodeticViewpoint class has a bunch of helper properties on it, for example you can adjust just the altitude on the viewpoint, and anything that depends on that change will cascade out:

viewpoint.Position.Altitude = 500;

Also, one of the things that using the viewpoint also saves you is that calculating the exact X,Y,Z coordinate from the latitude/longitude/altitude that you provided which is quite tricky since we use WGS84. However GeodeticViewpoint makes that easy:

Vector3D coordinate = viewpoint.Position.Vector;

I've shown a lot of random tidbits above, and included diagrams from bits of "cheat sheet" that I made up for developers here. If there are parts that don't make sense, feel free to comment.

Installing Plug-Ins

NikolaiF — Thu, 01 May 2008 20:08:00 GMT

Note: this entry references code for an older version of VE3D. The newest code samples are here.

Some types of plug-ins feature special data or rendering, and are intended to be used with a particular website. Others are intended to enhance the experience of all websites, and run every time a user runs VE3D. Most of the samples given so far have been about the former, where the test html page references the plug-in you wish to load. Today we’ll talk about the latter.

In addition, there is currently a limitation that plug-ins must be installed in the GAC in order to run. This is true regardless of what category the plug-in falls under. End users of a plug-in will need a way of installing the plug-in. Fortunately writing an installer is easy with Visual Studio.

The first link contains the source code for the plug-in itself and the deployment project. The plug-in is set up to run in a test page just like the others, but the intended way to use this solution is to build PlugInSetup. That project will take the output of the plug-in project, add it to an MSI along with some appropriate verbiage, and a setup.exe bootstrapper to run the MSI. Once those are built, the setup.exe and MSI combination can be distributed to end users. In my case, I created a self-extracting zip archive – the output is the second link. Visual Studio won’t do this directly, so use your favorite tool to create a nice single package for users. This method doesn’t necessarily create the most elegant installer, and any installer package that has the same features could be used, but this one works and is easy to use.

The important parts of the PlugInSetup projects are the files to include and the various text messages to display. Right click on the project name, and select View -> File System. The file locations we’d like to install to are shown. In order to run an automatically-running plug-in, we must install to a special location under VE3D’s install path, as seen here. A plug-in that loads on demand, as from a custom website, would install to its own Program Files directory. For this plug-in, there are no user-specific resources so all users will be able to use the plug-in when they run VE3D.

We also must add our plug-in to the Global Assembly Cache. This can be seen below.

New files may be added to both by right clicking in the right-hand side of the main view, and new locations may be added by right-clicking in the left-hand side.

We may also modify various items like author name and contact info by clicking on the PlugInSetup project and looking at the properties page.

The plug-in itself is a simple project to remember camera viewpoints and fly back to them when the user presses a key. It has no UI elements except for notifications on error, which is desirable for a plug-in that will always be run. Ideally, some form of instruction for the user would appear on startup or during the install but for now we are keeping it simple. To save a viewpoint, hold shift and then press a number key from 1 to 4. To return to that viewpoint, even after restarting the app, press the same number key again, this time without holding shift. To reset all the views, press 0.

The project uses the bindings system with a config file, meaning that end users may change the keys used by editing the ShortcutBindings.xml file (see the code for comments on the location of this file). It also uses IsolatedStorage for safe persistence of data, unique to the plug-in and user (so different users may have different saved views). The code has comments that hopefully explain what's going on, but some of it, bindings especially, will be a topic for a future post.

Enjoy!

Creating the most basic Windows Form

Heptazane — Sat, 19 Apr 2008 22:13:00 GMT

Note: this entry references code for an older version of VE3D. The newest code samples are here.

The samples that can be downloaded below demonstrate creating a basic Windows Application with a VE3D control on it (SimpleForm), however, I wanted to go over the most basic steps. The sample does not use the Toolbox, but I will.

Step 1: Make sure the VE3D control is installed by visiting http://maps.live.com and switching to 3D.

Step 2: Select Tools->Choose Toolbox Items...

Step 3: Make sure GlobeControl is checked in .NET Framework Components tab. The version should be 2.0.711.13001. GlobeControl should now show up in your Toolbox under the General section with a gear icon next to it.

Step 4: Create a new C# Windows Application in Visual Studio 2005.

Step 5: Select GlobeControl from your Toolbox and drop it onto your form. It should show up with just a big, grey dot in the middle and "GlobeControl" written across it. This is just the designer view. If you run the application at this point, you'll see the globe in 3D, but only with the outer most model and if you zoom in you'll just get fuzzy green. The reason is that we haven't set up any data sources yet, so...

Step 6: Make sure your form is selected (not the GlobeControl) and add a Load event (select the lightening bolt for events in the Properties pane, find Load and double click on it). Make sure it looks like this:

private void Form1_Load(object sender, EventArgs e)
{
    this.globeControl1.Host.DataSources.Add(new DataSourceLayerData("Elevation", "Elevation", @"http://maps.live.com//Manifests/HD.xml", DataSourceUsage.ElevationMap));
    this.globeControl1.Host.DataSources.Add(new DataSourceLayerData("Texture", "Texture", @"http://maps.live.com//Manifests/HT.xml", DataSourceUsage.TextureMap));
    this.globeControl1.Host.DataSources.Add(new DataSourceLayerData("Models", "Models", @"http://maps.live.com//Manifests/MO.xml", DataSourceUsage.Model));
}

Step 7: To use the DataSource classes, you'll need to right-click on your project's references and select Add Reference..., select the Browse tab and browse to "C:\Program Files\Virtual Earth 3D". Select "Microsoft.MapPoint.Data" and "Microsoft.MapPoint.Rendering3D.Utility" and hit OK.

Step 8: Run your application and enjoy!

Definitely look at the samples for more goodness, but these are the basic steps to get started.

Geometry

NikolaiF — Sat, 19 Apr 2008 03:05:00 GMT

The first thing that most people want to do when playing with the 3D control is add some stuff to the world. The most straightforward way to do this is via the Geometry Manager, accessible from Host.Geometry. You can modify any of the samples to contain this code, most easily in the Activate function of a plug-in or OnLoad for SimpleForm.

Host.Geometry.AddGeometry(new PushpinGeometry(

"My Layer", "My Id",

LatLonAlt.CreateUsingDegrees(-47.6435, 112.1422, 100.0),

PushpinInfo.Default));

This creates a default pin on top of Microsoft Building 116 in Redmond, WA, just in case you were wondering where that is. The first two parameters are just identifiers. You can use Layers to group items together, but it's not required. The two strings together just have to be unique. The third parameter is the position of the pin in Latitude, Longitude, Altitude. Here we’re using degrees in WGS84, and meters for the altitude.

Let me digress on units for a moment. Notice that latitude, which is the “Y” component of the coordinate, comes first. This is a long-standing convention when specifying geographic coordinates, but for our purposes is somewhat arbitrary. In other contexts, for example when we use a Coordinate2D struct, which is a more general-use structure not tied to a specific coordinate system, we’ll follow the mathematical convention of “X” first. Also, values of latitude and longitude are technically angles (from the equator and around the polar axis, respectively). When dealing with angles in computers it is convenient to store them as radians, which is how most trigonometric functions deal with them. However, degrees are usually easier to think about. So here we create the structure explicitly in degrees to reduce confusion. If you ever have trouble with your pushpin not appearing, the first thing to check is the order of your values and their units. We use meters for distances and altitudes, but the exact meaning of altitude can change depending on what AltitudeMode you are associating with the geometry.

Back to the pushpin, next we’ll want to change how it appears. If you pull the PushpinInfo.Default object into a local variable, you can then modify the various provided values, leaving others as they are.

PushpinInfo info = PushpinInfo.Default;

info.Resource = http://kristoffer.members.winisp.net/VE3D/jewel.png;

info.OrientationMode = PushpinOrientationMode.UseProvided;

info.Orientation = new Orientation(new RollPitchYaw(

0.0,

20 * Constants.RadiansPerDegree,

45 * Constants.RadiansPerDegree));

Host.Geometry.AddGeometry(new PushpinGeometry(

"My Layer", "My Id",

LatLonAlt.CreateUsingDegrees(47.6435, -122.1422, 10.0),

info));

In this case we’ve added a pretty logo over the same building rather than using the default orange pin, and told it to use a specific orientation instead of always facing the camera. Roll/Pitch/Yaw (RPY) is in degrees, but we can convert using some constants. Think of the image as a face, with the nose pointing straight out of the middle of it. If you supply a RPY of (0, 0, 0) the face will point north, toward the horizon, with the head level. Rolling will be like tilting the head sideways towards the shoulders, pitch is like looking up and down, and yaw is looking side to side. In this case, we are looking slightly up and to the northwest. You can combine the values with values from the camera to get interesting effects by setting OrientationMode. AltitudeMode is set here, to control the exact meaning of the altitude component of its position.

The two other basic types of geometry are PolylineGeometry and PolygonGeometry. Their setup is similar, except that you will provide arrays of LatLonAlt values. There are also two distinct categories of each, those that are drawn on the ground and those drawn in the air.

Host.Geometry.AddGeometry(new PolygonGeometry(

"My Layer", "My Poly",

null,

new LatLonAlt[] {

LatLonAlt.CreateUsingDegrees(47.6435, -122.1422, 0.0),

LatLonAlt.CreateUsingDegrees(47.645, -122.1422, 0.0),

LatLonAlt.CreateUsingDegrees(47.645, -122.1412, 0.0),

LatLonAlt.CreateUsingDegrees(47.6435, -122.1412, 0.0) },

PolygonGeometry.PolygonFormat.Polygon2D,

PolyInfo.DefaultPolyline));

The Format parameter specifies what type they should be, and altitude values will be ignored for 2D versions (note: LineList2D is currently not supported, but the rest all have their uses). The third parameter here is a “tag”, which is something that can be used when your user is interacting with your objects via the mouse. In the Geometry sample you can see some of these ideas (and a few other things) in play.