As I worked on HYDEsim, I discovered some interesting things about the Google Maps API. Well, let’s call them what they are: limitations.
(And let me say right up front that if I missed ways to get around these limitations, then I’ll happily be corrected. Either way, these are the impressions of someone whose first project in the API took about two days, and was in the end basically a success, which speaks volumes to the quality of the API.)
The first and most important limitation was that the Google Maps API permits the creation of two types of objects. The first type is icons, the most obvious example of which are those little push-pin symbols in Google Maps that mark locations. The second is polylines, which are how Google Maps draws the “get from here to there” routes on the maps. You get both any time you ask for driving directions, like these from Norwalk, CT to New York City, NY.
Note that they’re polylines, not polygons. You could certainly draw a polygonal shape using a polyline, but you couldn’t easily fill it with a color, let alone a translucent color. And as for a circle… well, if you want to draw enough line segments so that you approximate the roundness of a circle, you certainly can. It just doesn’t seem like a great idea. Plus there’s no simple way to fill it in.
So in order to draw the overpressure rings, I created a 1000×1000 pixel 24-bit PNG of a circle. To create a ring, I first used the Google Maps API to figure out the latitude and longitude boundaries of the map. From that, I determined the number of miles per degree based on the latitude, and then calculated the number of miles per pixel (mpp) within the view. From there, I determined how wide a ring needed to be to be the right size, created an icon at that size using the big PNG, and added it as an icon.
Whew.
Okay, so that solved the problem of putting the rings on the map. What it didn’t solve was what happened if the zoom level changed, because icons (being raster images) don’t zoom with the map. By default, you wouldn’t want them to: if the pushpin kept growing with the map as you zoomed in, eventually it would get huge and blocky and obscure half the view.
Therefore, the upshot was that every time the zoom level changed, I had to rip away the rings and rebuild them entirely, based on the new mpp value. It was easy to trigger the process:
GEvent.addListener(map, "zoom", zoomLimit);
That’s the API at work for me. I just tack a listener onto the zoom event, and I’m ready to go. Cool. Rebuilding the icons—well, not so cool, although it doesn’t seem to kill the tool’s performance.
All this zoom handling was necessary because icons, as you might expect, are given dimensions in pixels. Polylines, on the other hand, have each point defined with longitude/latitude coordinates. That’s why polylines do scale with change in zoom level—as, again, you’d want them to do by default. If I could have defined my icons’ sizes using longitude/latitude measures instead of pixels, I could have avoided the whole “recalculate the ring sizes every time the zoom level changes” bit and shaved two or three hours off of my development time. (Which was, in total, 12 hours or less.)
Of course, if the API provided polygonal primitives, I’d have avoided even more hackery. If I could have just drawn the circles as circles, using longitudinal degrees as the unit of sizing, then there’d have been even less work and a shorter development time. Something like this:
var base = new GShape();
base.type = circle;
base.anchor = new GPoint(-73.9971, 40.7223); // longitude,latitude
base.radius = 0.0273548; // degrees of latitude
…or something to that effect, with properties for the color and thickness of the outline, and also for the color and transparency of the interior. And so on.
By doing it this way, the shapes (and there could easily be many other types) would be like filled polylines, and would scale in size along with the map. That would have made HYDESim a whole lot easier to create.
You might say, “That’s all well and good, Eric, but how many reasons are there to draw circles on a map besides charting widespread destruction?” I thought of a few possibilities:
- Explicitly showing the scope of a “show me hotels within this many miles of the specified address” type of request
- Someone looking to recreate the WIMPUR map in Google Maps
- Plotting Iridium flare intensities
I’m sure there are countless more. As well, allowing for actual filled polygons would add extra possibilities to applications like chicagocrime.org, which uses polylines to draw ZIP code boundaries. With filled polygons, they could shade the ZIP code in question… or shade all other ZIP codes while leaving the current one unshaded, in order to give it some extra visual pop.
There was one other thing I encountered that’s either a limitation, or I just couldn’t figure out how to deal with it. If you click on a detonation point in HYDESim, it pops up a “blowup” window (their term, not mine!) that shows a zoomed-in view of that point on the map. The overpressure ring overlays are faithfully reproduced on that map, but they aren’t scaled to its zoom level. They exactly match the overlays on the main map, and zooming in and out in that window has no scaling effects.
Ideally, I’d just remove the overlays from the zoom window while leaving them in place on the larger map. I couldn’t find a way to do it. Failing that, I wanted to have the overlays correctly scaled. No dice there either. If there is a way to do either of these and I missed it, hopefully someone will let me know. If not, it’s something I hope the API adds in the future.
The final observation has to do with the icons and interactivity. I wanted to set the overpressure rings to be event-transparent. In other words, I wanted to make it so that the rings didn’t exist as far as the event model was concerned. That way, you could click-and-drag the map even if there’s a ring underneath the mouse pointer. This didn’t appear to be possible, although again, maybe I just couldn’t figure out how. I did play around with the imageMap property, but it didn’t seem to have much effect. Figuring that out would be nice, though. I could leave the detonation point active for popping open the blowup window, and make the rest inert.
Other than that, things went as smoothly as you might expect they would for someone with limited JavaScript skills and no prior experience with the Google Maps API. The examples provided by Google on the documentation page helped immensely, actually, especially the AJAX example. That let me split the city list into a separate file, thus making it much easier to maintain, and get my first hands-on experience with AJAX programming. (I’ve seen AJAX applications before—as long as three years ago, actually—but never written any code along those lines.)
Oh, and one more thing—the fact that the Google Maps API key only works for a specific directory, and not any of its subdirectories, drove me up the wall. Instead of generating a key for meyerweb.com that would cover anything I might do on the site, I’ll have to generate a new key for every new directory. This is why I set up the directory /eric/tools/gmap/, but that just seems so… confining. Similarly, it was annoying that the key was completely bound to the full address. I generated the key for meyerweb.com/eric/tools/gmap/, so if anyone types in www.meyerweb.com/eric/tools/gmap/ they’ll get a key error. It would be nice if at some future time the keys were a little more flexible than they are now.