1. The 3D view is engine independant and uses Flash 10 3D maths and "drawTriangles" method if available
2. The API provides everything one needs to integrate 3D graphics as an overlay using the library of its choice
3. It works just the same as the good old 2D Google Maps API

The first point is very important. It ensures the library is lightweight and does not include any third party software you wouldn't want to use.

The second is what makes the magic possible: the API exposes the viewport and camera data and provides methods to convert latitude/longitude into 3D world coordinates. With a little math and a few hours of debugging it is then easy to wrap it with the 3D engine of your choice.

The Experiment

You can use CTRL + mouse drag or SHIFT + mouse drag to look around.

The Code

You might want to read the official Google Maps Flash API documentation first, including the dedicated 3D maps section.

The Viewport

The Google Maps API provides the viewport width and height and the focal length. I use the field-of-view instead of the focal length but there is a simple formula to convert from one to the other:

var fieldOfView : Number = 2. * Math.atan(viewportWidth / (2. * focalLength));

Another issue is to find proper values for the near and far clipping planes. I chose 0.000001 for the near plane and 0.2 for the far plane. Those values are extremely low and might cause floating point inconsistencies. The best thing to do would be to scale the whole scene to be able to use reasonable clipping values. Maybe for a later version! This problem does not seem to affect the experiment though...
The following function presents how to get the relevant viewport values from the Google Maps API:

public function buildViewport(myMap : Map3D) : void
{
	var g : TransformationGeometry = myMap.camera.getTransformationGeometry();
	var width : Number = g.viewportSize.x;
	var height : Number = g.viewportSize.y;
	var fieldOfView : Number = 2. * Math.atan(g.viewportSize.y / (2. * g.focalLength));
 
	// build viewport...
}

The Camera

The following function retrieves the camera position and look-at vectors from the Google Maps API:

public function buildCamera(myMap : Map3D) : void
{
	var cam : ICamera = myMap.camera;
	var mapCenter : Point = cam.latLngToWorld(cam.center);
	var g : TransformationGeometry = cam.getTransformationGeometry();
	var pos : Point3D = g.cameraPosition;
	var zAxis : Point3D = g.cameraZAxis;
	var yaw : Number = cam.attitude.yaw * (Math.PI / 180.);
	var lookAt : Vector3D = new Vector3D();
	var eye : Vector3D = new Vector3D();
 
	eye.x = pos.x - 128;
	eye.y = pos.z;
	eye.z = 128 - pos.y;
 
	if (!zAxis.x && !zAxis.y)
	{
		lookAt.x = eye.x + EPSILON * Math.sin(yaw);
		lookAt.z = eye.z + EPSILON * Math.cos(yaw);
	}
	else
	{
		lookAt.x = eye.x - zAxis.x;
		lookAt.z = eye.z + zAxis.y;
	}
 
	lookAt.y = eye.y - zAxis.z;
 
	// build camera using eye position, look-at and Vector3D.Y_AXIS as the up vector
}

I prefer computing the eye position and look-at vectors and using them to create the transform matrix rather than just creating the matrix directly. This way, you can expose the actual camera parameters (even if in read-only) and still use the transform matrix to do the math.

The Scene

The last step is to make it possible to position 3D objects on the map. What you actually want to do is to be able to add objects specifying their latitude/longitude instead of their actual (x, y, z) coordinates. Then again, the Google Maps API does it just fine:

public function computePosition(myLatitude : Number, myLongitude : Number) : Vector3D
{
	var pos : Point = _map.camera.latLngToWorld(new LatLng(myLatitude, myLongitude));
 
	return new Vector3D(pos.x - 128., 0., 128. - pos.y);
}

Know Issues

As said previously, the extremely low far and near clipping plane values might introduce float point inconsistencies. Therefore, some clipping glitches might appear and frustum culling is performed only on the far clipping plane.

Credits

Credits goes to Marc Fahmi for the low-polygon 3D model of the Eiffel Tower.

Optimization is always important. But when it comes to 3D for the Flash Platform, it's an everyday battle. The first ideas that come to mind are to avoid:

1. redrawing the same regions : each pixel value must be set once and only once
2. rendering invisible objects : objects that are out of sight still take a lot of CPU horsepower

While Flash takes care of the first one in its very renderer, the second one is not handled. But that is something we can easily address!

The Technic

The method is called "frustum culling". The big picture is that every mesh is approximated using a bounding volume (typically a sphere or a box). If the bounding volume is visible, the corresponding mesh is rendered. The two following pictures show the frustum culling caught in action:

The mesh is visible: TPS counter indicates 18900 triangles per seconds

The mesh is out of sight: frustum culling is acting and TPS counter indicates 0!

1. The frustum

First things first: before performing frustum culling, you need to build the frustum! The frustum is the 3D shape that contains everything the camera can see. It's made of 6 planes and looks like a truncated pyramid:

The view frustum

Each plane is defined by a plane equation: ax + by + cz + d, where (a, b, c) is the normal of the plane and d the distance on that normal. The 6 planes must be extracted from one of the Matrix3D object used to define the transform from one space to another (world to camera for example). Here are the 6 plane equations:

• left: (a = m14 + m11, b = m24 + m21, c = m34 + m31, d = m44 + m41)
• right: (a = m14 − m11, b = m24 − m21, c = m34 − m31, d = m44 − m41)
• bottom: (a = m14 + m12, b = m24 + m22, c = m34 + m32, d = m44 + m42)
• top: (a = m14 − m12, b = m24 − m22, c = m34 − m32, d = m44 − m42)
• near: (a = m13, b = m23, c = m33, d = m43)
• far: (a = m13, b = m23, c = m33, d = m43)

The source matrix you chose defines the coordinates systems of the extracted planes:

• the projection matrix provides planes in view (or camera) space
• the view * projection matrix provides planes in world space
• the world * view * projection matrix provides planes in object (or local) space

2. Bounding volumes

Testing every polygon against the frustum is a very expensive task. In order to speed things up, we will rather test a primitive shape that bounds the mesh: a "bounding volume". Common bounding volumes are spheres or boxes. I'll focus on the first one in the rest of the article.

A bounding sphere is pretty simple to implement: you just need to store the center of the sphere and it's radius. That being said, a BoundingSphere class would just contain the center as a Vector3D and the radius as a Number. When you have all the vertices of a mesh, building the bounding sphere is easy :

public function computeBoundingSphere(myVertices : Vector.<Number>) : BoundingSphere
{
	var min : Vector3D = new Vector3D(Number.MAX_VALUE, Number.MAX_VALUE, Number.MAX_VALUE);
	var max : Vector3D = new Vector3D(Number.MIN_VALUE, Number.MIN_VALUE, Number.MIN_VALUE);
	var length : int = myVertices.length;
	var center : Vector3D = null;
	var radius : Number = null;
 
	for (var i : uint = 0; i < length; i += 3)
	{
		min.x = myVertices [i] < min.x ? myVertices[i] : min.x;
		min.y = myVertices [uint(i + 1)] < min.y ? myVertices[int(i + 1)] : min.y;
		min.z = myVertices [uint(i + 2)] < min.z ? myVertices[int(i + 2)] : min.z;
 
 		max.x = myVertices [i] > max.x ? myVertices [i] : max.x;
		max.y = myVertices [uint(i + 1)] > max.y ? myVertices[int(i + 1)] : max.y;
		max.z = myVertices [uint(i + 2)] > max.z ? myVertices[int(i + 2)] : max.z;
	}
 
	center = new Vector3D((myMax.x + myMin.x) / 2.0, (myMax.y + myMin.y) / 2.0, (myMax.z + myMin.z) / 2.0);
        radius = Math.max(myMax.x - center.x, myMax.y - center.y, myMax.z - center.z,
		          center.x - myMin.x, center.y - myMin.y, center.z - myMin.z);	
 
	return new BoundingSphere(center, radius);
}

3. Point to plane distance

The plane equation (ax + by + cz + d) can be stored as a Vector3D object. Indeed, the Vector3D implements x, y and z but also a w Number attribute. This last one is supposed to store the homogenous coordinate. Nonetheless, we can use those 4 Number attributes to store the (a, b, c, d) values that defines our plane equation.

In order to test whether a bounding volume is inside or outside the frustum, we must be able to compute the distance of this object to the plane. To do so, we use the dot product of the point with the plane normal (which must be normalized first) :

public function planeToPointDistance(myPlane : Vector3D, myPoint : Vector3D) : Number
{
	return myPlane.x * myPoint.x + myPlane.y * myPoint.y + myPlane.z * myPoint.z + myPlane.w;
}

4. The test function

Now that our frustum and our bounding volumes are ready, we can add this little test function that checks whether an object is visible or not:

public function testBoundingSphere(myPlanes      : Vector.,
                                   mySphere      : BoundingSphere) : Boolean
{
	var length : int = myPlanes.length;
 
	for (var i : uint = 0; i < length; ++i)
	{
		var d 	: Number = planeToPointDistance(myPlanes[i]);
 
		// bouding sphere is out of the frustum
		if (d + mySphere.radius < 0.0)
			return false;
		// bounding sphere is spanning
		else if (d - mySphere.radius <= 0.0)
			return true;
	}
 
	// bounding sphere is inside the frustum
	return true;
}

The Experiment

The following experiment demonstrates frustum culling in action (click on the picture to open the application) :

Frustum culling experiment (use the arrow keys to move)

Use the arrow keys to move the robot across the scene. You can notice the TPS counter drops down to zero whenever the character is out of sight (on the near left or near right side of the screen). When the TPS indicates 0, no triangles are rendered and CPU usage drops down to 0%. It actually means that the rest of the rendering process has a minimal overhead!

And it's even more awesome...

This experiment also introduce my brand new mini-debugger inspired of Mr. Doob's work. I replaced the maximum memory footprint counter with a per-second rendered triangles counter (or TPS counter). CPU usage or framerate alone are not absolute measurements but the TPS counter reflects the true performance of the application the old fashioned way: the more polygons per second the better. I also updated the timer to display the processing time and the overall rendering time.

You can compare this experiment to the "old" one I made up a few weeks ago: the displayed 3D model features 30% more polygons but the CPU usage is the same.

The rendering process is done in such a way that absolutely no computation occurs on invisible objects, not even the slightest animation or z-sorting operation.

I enabled dynamic bounding volumes for animated meshes: if you place the mesh on the edges of the viewing space, you might notice that the TPS counter sometimes goes down to zero to raise up again to a few hundreds/thousands of triangles per second. The explanation is simple: the visibility test is done dynamically and follows the mesh animations. If the animation drives the mesh out of the viewing frustum, culling operates and it is not renderered.

I recently needed to change the xmlns attribute of a lot of XML/XSL files and doing it file by file would have been a real mess. So I wrote this little piece of script shell:

#! /bin/sh
 
NAMESPACE_NAME=$1
NAMESPACE_URI=$(echo $2 | sed -e 's/\//\\\//g')
FILE=$3
 
if [ x${NAMESPACE_NAME} = 'x' -o x${NAMESPACE_URI} = 'x' -o ! -f ${FILE} ]; then
    echo 'Usage:' ${0} 'NAMESPACE_NAME NAMESPACE_URI FILE'
    exit 42
fi
 
cat $FILE | sed -e s/xmlns:${NAMESPACE_NAME}=\".*\"/xmlns:${NAMESPACE_NAME}'="'${NAMESPACE_URI}\"/g > $FILE

You can run the script with the following command line:

./change_namespace.sh myns http://my.namespace.uri my_file.xml

Where :

• myns is the namespace name (html, xsl, xhtml, etc...)
• http://my.namespace.uri is the URI of the namespace
• my_file.xml is the file to edit