Basic Math

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.

    Recommended local coordinates.

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).

      Structure of the globe

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.