Virtual Earth 3D team blog : Plug-In

Two good questions

NikolaiF — Tue, 08 Dec 2009 18:52:00 GMT

Posting some answers to questions I've gotten recently.

Bug in the samples:

Kind of silly that I hadn't noticed this until now, but there's an error in the sample html for most of the samples. The name of the functions used for plug-in load and activate conflict with an internal name used in the AJAX code. Change "On3DPlugInLoaded" and "On3DPlugInActivated" to any other name, for example "PlugInLoaded" and "PlugInActivated". Remember to change both your function name and the string passed to AttachEvent.

Zoom or Rotate around a point:

There have been several requests about how to allow people to zoom or rotate around a particular point on the screen, rather than the center. The code here isn't as cleaned up as I normally like it, but it illustrates the ideas. You can do the rotate by purely calling built-in VE3D functions via the bindings system, but zoom requires a bit more work. To run the code, replace files in the Multitouch sample with the files in the zip. You will want to call or adapt the calls to GestureEventSource to be in response to your inputs, rather than the worker thread I created.

Remember you can contact me any time via the contact form, or if you prefer via comments. Even if it looks like I haven't posted recently :)

Multitouch in VE3D

NikolaiF — Wed, 04 Mar 2009 21:24:00 GMT

Ever since I got a Touchsmart at home I've been very interested in the desktop touch experience, and so in the last couple days I decided to play with how I could incorporate it into VE3D. The code itself isn't really ready for consumption, but if you'd like to see where I'm at, I've built a very preliminary plug-in that you can install and play with.

Download

This requires Windows 7 and a machine that has multitouch support, such as a Touchsmart or Latitude XT. The package is a self-extracting zip, just run it and accept the defaults. The next time you launch VE3D, the plug-in will load shortly after startup. There's no UI or anything. The gestures will just quietly start working. The plug-in will work on any app that uses GlobeControl (and loads it), but since it calls native code it does require installation.

Currently supported are two-finger zoom and two-finger rotate. I'm using the built-in gesture engine from Win7, which makes things very easy, but in the future I would like to use direct touch input instead. This should eliminate a few artifacts like a momentary delay between when you start input and when the map starts moving. It should also allow support of some more interesting types of inputs, like a two-finger pan, combining rotate and zoom into a single fluid motion, etc. The point is that there's a lot of potential beyond what I've done here.

The touch interface in Win7 relies on Windows Messages and a few native functions. To listen to Windows Messages, use Host.CommunicationManager.AttachToMessage. To interact with the native gesture API, here's something to get you started (this code will work just as well in any managed application). After that it's a matter of redirecting gestures to existing navigation Actions using bindings. To really do it right you'd probably also want to write a few things in your own CameraController.

Here's the gesture documentation on MSDN. Here's the raw touch docs.

Note: there's a bug in the current GlobeControl where the lParam and wParam values are reversed in the handler to AttachToMessage. Whoops! This is fixed in the next version, so be prepared. I will be releasing my code as a sample at that time, and will update the installer as well.

Note 2: I noticed on my Touchsmart that the rotate gesture has some trouble when your fingers are diagonal relative to the screen. I think this is a driver thing, since it doesn't happen on the Latitude XT, which uses a different touch technology and, obviously, different drivers. However, it looks like they are releasing improved drivers on Windows Update, so I hope this is just a bleeding edge thing.

Edit: the "Download" link has been updated to a version that is compatible with the current build on Virtual Earth 3D. Please uninstall the old version first and then install the new one. Functionality is still the same, that is to say, less than ideal. From what I have seen, using WM_TOUCH instead of WM_GESTURE will provide a far superior experience. Stay tuned.

Animation Redux

NikolaiF — Tue, 11 Nov 2008 04:05:00 GMT

This sample was released before, but didn't have a version that could run on the web without an install.

The new version in the samples pack is almost exactly the same, so I won't go over it again in detail. This post is just to show it off interactively.

See it in action!

When the page loads, press "S" after the text appears. You can then grab the green balls with the mouse to deform the surface. Left-click and drag causes it to deform to the new location and then slowly return; right-click and drag causes it to move to the new shape permanently.

Actors and DataSources

NikolaiF — Mon, 27 Oct 2008 23:51:00 GMT

In this sample, we create a DataSource, which is a class that can be used for large-scale data sets. It provides hooks into the system's spatial index, memory cache, and background data threads. Data from the DataSource will only be requested when it is in view, and will be automatically cached according to how often it is used and how much memory it consumes. The DataSource we create is a purely generated one consisting of a large number of animated bunnies spread evenly across the globe, and would be impossibly large to try to deal with all at once.

See it in action!

When the PlugIn is Activated, the ActorDataSource is created and added to the system. When we create the DataSource we set up its Ontology, which is a system for defining the type of data the DataSource contains.

The next time the Camera Query runs, a set of areas in the Spatial Index that are in view are determined, called tiles. Each tile is sent as a lat/long bounding box to the Data Threads, which call all added DataSources, including ours. The entry point here is QueryPrimitivesInternal. In this function we would normally do some sort of query to a backend, such as a SQL database or the network, but for simplicity we simply create a BunnyPrimitive in the center of the query region. A primitive is a piece of data that represents a thing in the world, in the case a Bunny, but is not itself an Actor. When we return the Primitive, it is passed to our ActorBuilder, called BunnyBuilder. This creates actual Actors which can render or react to the data represented by each Primitive. Each Actor also needs an ActorBounds, which represents a spatial area that, when in view, should cause it to render. When this happens each Actor's Update and Render functions are called on the Render Thread just like normal Actors.

Get the code!

Camera Control

NikolaiF — Wed, 22 Oct 2008 20:02:00 GMT

In this sample, we create a plug-in to move the camera to a random location in the world every time a HTML button is pressed. It demonstrates basic plug-in loading, writing and using a CameraController, and communicating between a plug-in and the hosting web page via Events.

See it in action.

Camera controllers are important because it provides a single and consistent way of updating the camera. Consistency is important because the camera needs to be in one position throughout an entire frame -- otherwise one part of the code may think the camera is in one place while another thinks it's elsewhere. This is why you normally read the camera through its Snapshot in the SceneState object, and can only set it via a controller, of which there may only be one active at a time.

Normally you position the camera with two properties, the position and the orientation. Either can be set in terms of global or local coordinates. Global essentially means relative to the center of the earth, while local means relative to your current location on the globe. For position, global coordinates are in terms of Vector3D, local in terms of latitude, longitude, and altitude. For orientation, you would normally set it globally in terms of lookat and lookup, Vector3Ds, and locally in terms of roll, pitch, and yaw. See the Basic Math entry for more.

When this plug-in is Activated, it creates a new JumpController and begins listening to an event from CommunicationManager, but otherwise doesn't do anything. The script on TestPage.htm is then able to raise that event, which causes JumpHandler to be fired. A new random position is generated and given to the JumpController. The JumpController is then set to be the current CameraController. The next time the render thread calls the CameraStep, the JumpController will be called instead of the Default controller. The JumpController's Activate function is called first, and it indicates that HasArrived
is false, which means it still has work to do. The MoveCamera is called, and the JumpController is allowed to modify its Camera property. The CameraStep will use these values to set up the next scene and frame for rendering. In addition, the JumpController sets HasArrived to true, indicating it has
completed its work. This causes the system to automatically swap JumpController's Next controller to be the Current one, in this case simply restoring control to the Default.

If we wanted to animate to the location, we would adjust the current position a little at a time over a series of calls to MoveCamera, and only when we are down would we set HasArrived to true. We could also take over completely, using Bindings to detect user input and making changes to Camera as needed,
and only setting HasArrived when we want to return control to the Default.

Note, at this time we only support one camera and one viewpoint at a time.

Get the code!

Terrain Imagery Overlays

NikolaiF — Sun, 12 Oct 2008 20:15:00 GMT

There are four ways to add custom imagery to VE3D. The first three involve using built-in classes, and you just have to provide information on where to get the data. The fourth involves implementing your own DataSource.

See it in action!

This sample demonstrates how to add common terrain imagery data to the world, and adds a simple tour to display the example data sets. We then use two events, one a built in data load event, and the other a custom event we created using the Step class, to tell the control to FlyTo a series of locations.

When the PlugIn is Activated, we create three datasources using built-in settings. The first uses a SingleImageDataSource, which reads data from a Bitmap object in memory and draws it on the terrain. The second uses a "content manifest", which is an xml file that describes the data, how to display it, and where to get it. An example is here. The last uses a parameter string, and is similar to VETileSourceSpecification. The % replacement variables in tilesource have the same numbers as those listed at the top of the xml manifest. The parameter string is also a good method for adding WMS server data.

It is also possible to create your own datasources.

See it in action!

This sample demonstrates how to add terrain imagery via a custom datasource. This one generates a colored Mandelbrot set.

When the PlugIn is Activated, we create our DataSource and add it to the system. We also save off any existing datasources so we can add them back again later. Once it is added, the data threads query it when we move into a new area, entering at QueryPrimitivesInternal. We use the bounding area of the query to generate an appropriate section of the Mandelbrot set, and return it as a rasterized image. This image is then displayed by the system.

This method is good if you have special request logic, or want to do some of the work client-side (in this case, all the work is client-side). This saves you from having to have a large server dataset of pre-rendered tiles, or execute expensive code on your servers. There are notes in the sample code for how to use this code to get information about the area you are looking at and generate appropriate request URLs, etc.

Get the code!

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

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.

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!

Adding a Virtual Earth 3D Plug-in to your webpage

NikolaiF — Sat, 12 Apr 2008 01:05:00 GMT

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

Want to try custom code for the 3D view of Virtual Earth? This is the place to find out how!

What do I need?

· Virtual Earth 3D installed. Navigate to maps.live.com, click the 3D button, and follow the upgrade/install steps.

· Visual Studio 2005 or higher and some c# coding skills (any .NET language actually, but samples will be in C#).

· This package.

If you do not have Visual Studio installed, you can download a free version of Visual Studio 2008 here. See notes at the end of the post for details.

Extract the samples zip to c:\Samples (or any other directory, but you'll have to fix up some paths in the projects). There's a Readme, but you should be able to just open the sln in Visual Studio, set one of the projects to the Startup project, and hit F5. For this post, we'll just talk about the basics of how the plug-in will be loaded.

Try building and launching the project SimpleObjectPlacement.

By default, you'll get an IE window with a script warning. This only happens because we're loading the html off the local drive, and will not happen if we point to a web server.

You can change startup behavior by modifying the values in the Debug pane of the project.

Once there you should see the globe, and after a moment it will zoom to off the coast of Africa to see a floating cube.

So what happened? First, we have a very simple webpage that loads the JavaScript SDK, and then extracts the 3D control from it to do some special loading. This is an unsupported thing to do (well heck, everything in these samples is unsupported, but that doesn’t mean it won’t work), but we need to get at the Events and LoadPlugInDll methods.

map = new VEMap('myMap');

map.SetDashboardSize(VEDashboardSize.Normal);

map.LoadMap(null, 2, 'a', false, VEMapMode.Mode3D);

control3D = map.vemapcontrol.Get3DControl();

control3D.AttachEvent("OnPlugInLoaded", "On3DPlugInLoaded");

control3D.AttachEvent("OnPlugInActivated", "On3DPlugInActivated");

control3D.AttachEvent("OnPlugInDeactivated", "On3DPlugInDeactivated");

control3D.LoadPlugInDll("C:\\Samples\\SimpleObjectPlacement\\bin\\Debug\\SimpleObjectPlacement.dll");

Events are just callbacks when certain things happen. In this case, when a plug-in is finished loading the SDK will try to call a function called "On3DPlugInLoaded". It has to be this way because the LoadPlugInDll method is asynchronous -- otherwise we'd have to sit and wait for loading to complete, causing a negative user experience. But you don't have to worry much about this, just know that you can listen to events and you'll be called when things happen. You can also fire your own events, which we'll get to later. In this case, if you look at the handler you'll see when we finish loading the plug-in we'll activate it. We could do more, but this is the minimum.

You can specify a plug-in to load in two ways. First is like this, with a local file path. Second is by specifying the fully qualified name. Either method requires that the plug-in be installed in the GAC, which is an unfortunate security limitation that we hope to relax in the future. You can get installed into the GAC by using utilities that come with VS, or by writing an MSI installer. We'll get into more on that later. All the samples here install their output into the GAC as a post-build step to help you get past these details.

When the plug-in is loaded, then we start executing the C# code. If you put breakpoints in SimpleObjectPlugIn.cs, you'll see it gets a call to the constructor, and then one to the Activate function. In a future post we'll walk through the details of what happens next, how the cube gets into the world, and why it changes color when you mouse over it. In the meantime, try playing with the other samples. Let us know what you think, and please enjoy.

Download Samples.zip

Notes on VS 2008 and VS 2008 Express:

If you use either of these, you'll have to run the solution upgrade wizard. It should be painless, but you may encounter some of the following issues:

VS 2008 Full and Express:

If you get errors on build about gacutil and return code 3, you may need to update the path in the project pre- and post-build steps to "$(DevEnvDir)..\..\..\Microsoft SDKs\Windows\v6.0A\bin\gacutil".

VS 2008 Express:

A message about a property not supported. This is related to the last point below, and can be ignored.

A message about Solution Items not supported (VS Express). This is just the readme file and can be ignored (you can still read the readme by just navigating to c:\samples).

Express only builds to the Release bin path, so the html files (TestPage.htm) need to be updated such that the LoadPlugInDll call points to bin\\Release instead of bin\\Debug.

VS Express doesn't support debugging a different process than the one launched. This is tricky because plug-ins run in the browser's process. To run the plug-in samples you'll need to build the project, and then run the html file manually in your favorite browser. However, you can debug a forms app as normal, so you can work around this by debugging your code inside the SimpleForm sample, and then copying to the plug-in. We apologize for this inconvenience, but it was free after all ;)

Update:

The intellisense files in the samples zip have been updated to be more complete.