Virtual Earth 3D team blog : Math

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!

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.