Did you know that basic relief shading is fairly simple to accomplish? I didn’t until a few days ago when I was flipping through the Slocum et al. cartography textbook, Thematic Cartography and Geographic Visualization, wherein a four-step process is presented. It sounded easy, so it was time for further adventures in raster-based cartography in Flash! I swore off code projects outside my day job because they tend to be more headache- and hair-loss-inducing than enjoyable, but an easy one that produces pretty pictures is worth an exception.

I previously tried raster map projection in AS3, and the same caveats apply. Flash shouldn’t be your first choice for hill-shading, but it’s good to demonstrate that it can be done on the fly in AS3, which could occasionally come in handy. Here follows a tutorial-like explanation of how simple shaded relief can be achieved in AS3. Code is only shown in bits and pieces, so to see it all in one place (or if you want to skip the details), you can download the source AS3 file and the source image file.

1) THE DATA SOURCE
Any shaded relief map is born of elevation data, typically from a digital elevation model (DEM), a.k.a. digital terrain model. Ideally the relief map would be generated from the actual elevation values in the DEM, but a DEM is often visually displayed as a grayscale image, which is what my example uses as a source. (See the bottom of this post for a bit more info on DEM data.) Darker means lower elevation; lighter means higher. The price of using the image as a starting point is precision, as there are only 256 different gray values (elevations) in the image.

My source, an elevation map of the Hawaiian island of Moloka’i, is below.

2) LOADING AND PREPARING DATA
To generate the shaded relief it’s necessary to go through the DEM image pixel-by-pixel, calculate a result pixel for the relief, and draw that pixel to an an output image. So the setup for this whole thing is to load the image using a Loader, draw it to a BitmapData, and create another BitmapData for the relief map.

public class ShadedRelief extends Sprite
{
	private var loader : Loader = new Loader();
	private var sourceBitmap : BitmapData;
	private var reliefBitmap : BitmapData;
	public function ShadedRelief()
	{
		loader.load( new URLRequest("molokai.png") );
		loader.contentLoaderInfo.addEventListener(Event.COMPLETE,onLoaded);
	}
	private function onLoaded( event : Event ) : void
	{
		sourceBitmap = new BitmapData( loader.width, loader.height );
		sourceBitmap.draw( loader );
		reliefBitmap = new BitmapData( loader.width, loader.height,true, 0 );
	}
}

3) GET YOUR MATH ON
Now I start following the mathematical steps laid out in the Slocum et al. text, which are three. For each pixel in the grid:

1. Calculate the slope of the land.
2. Calculate the aspect of the land (the direction it faces).
3. Calculate a reflectance value.

These calculations are made by observing the data in a 3×3 pixel window, at the center of which is the pixel of interest. So to start, loop through the rows and columns of the source image. There are, I think, more efficient ways to do pixel-level manipulation than what I spell out below, but I’m keeping it simple here.

private function drawMap() : void
{
	for ( var i : int = 0; i < sourceBitmap.width; i ++ ) {
		for ( var j : int = 0; j < sourceBitmap.height; j ++ ) {
			// magic will occur here
		}	
	}
}

For reference, here’s a diagram of the 3×3 window for any given pixel (i,j):

The Z values represent elevation values for each pixel. To find the slope of the cell, do a simple rise over run division in both the x and y directions.

From the x and y slopes follows an overall slope:

The grayscale image no longer has any real elevation values, so the 0-255 gray value will stand in. That can be obtained with the BitmapData.getPixel method and from that grabbing just one of the RGB channels, e.g. source.getPixel(i+1,j) & 0xFF. The D value (the distance between pixels) isn’t known in meaningful units anymore either, so D could just be 1. However, for some reason I found that using a slightly larger number produced a nicer result. My slope code looks like this:

var topValue : Number = sourceBitmap.getPixel( i, Math.max(j-1,0) ) & 0xff;
var leftValue : Number = sourceBitmap.getPixel( Math.max(i-1,0), j ) & 0xff;
var rightValue : Number = sourceBitmap.getPixel( Math.min(i+1,sourceBitmap.width-1), j ) & 0xff;
var bottomValue : Number = sourceBitmap.getPixel( i, Math.min(j+1,sourceBitmap.height-1) ) & 0xff;
 
var slx : Number = (rightValue - leftValue)/3;
var sly : Number = ( bottomValue - topValue )/3;
var sl0 : Number = Math.sqrt( slx*slx + sly*sly );

Next, the aspect. First, get a local angle between the x slope and the overall slope.

To get an azimuth (0º to 360º, where north is 0º, east 90º, etc.), this table is provided:

Code, then. Remember that AS3 works in radians, not degrees.

var phi : Number = Math.acos( slx/sl0 );
if ( sl0 == 0 ) { // account for division by zero trouble
	phi = 0;
}
var azimuth : Number;
if ( slx > 0 ) {
	if ( sly > 0 ) azimuth = phi + 1.5*Math.PI;
	else if ( sly < 0 ) azimuth = 1.5*Math.PI - phi;
	else phi = 1.5*Math.PI;
} else if ( slx < 0 ){
	if ( sly < 0 ) azimuth = phi + .5*Math.PI;
	else if ( sly > 0 ) azimuth = .5*Math.PI - phi;
	else azimuth = .5*Math.PI;
} else {
	if ( sly < 0 ) azimuth = Math.PI;
	else if ( sly > 0 ) azimuth = 0;
}

And now, a reflectance value, which will be the brightness of the final output pixel. A Lambertian reflectance is suggested, and the formula provided ends up looking like this in code:

var sunElev : Number = Math.PI*.25;
var sunAzimuth : Number = 1.75*Math.PI;
 
var L : Number = Math.cos( azimuth - sunAzimuth )*Math.cos( Math.PI*.5 - Math.atan(sl0) )*Math.cos( sunElev ) + Math.sin( Math.PI*.5 - Math.atan(sl0) )*Math.sin( sunElev );

The sunAzimuth and sunElevation values can be freely chosen and will affect the final appearance of shadows. 315º (northwest) and 45º respectively are pretty typical values. For some reason that I haven’t figured out, I ended up with some negative reflectance values, which I guess indicate black holes on the surface of the earth. I don’t understand the math going on here, but setting those to zero seemed to make the result look okay. (If anyone can explain or help me here, it’d be greatly appreciated!)

4) DRAW THE RELIEF
The reflectance value just needs to be translated into a shade of gray. The reflectance is basically a proportion of white, so to get RGB values it needs to be multiplied by 255 and assigned to each of the three channels. Finally, the pixel can be drawn on the output image.

var grayValue : Number = int(255 * L);
 
if ( grayValue < 0 ) {
	grayValue = 0;
}
// doing ARGB instead of RGB because transparency comes in handy elsewhere
reliefBitmap.setPixel32(i,j,0xff << 24 | grayValue << 16 | grayValue << 8 | grayValue);

Running through all that gets me the following Moloka’i map.

5) HYPSOMETRIC TINTING
The gray relief map wowed me enough the first time because I was amazed at how simple it was to produce (despite my lengthy explanation above). But it’s not a nice map without colors! Hypsometric tinting, in which colors are mapped to elevation ranges, is a common and aesthetically pleasing technique on relief maps. To get hypsometric tints on my relief map, another BitmapData is drawn based on the grayscale source image, but this time the math is much simpler. All that needs to be done is to match the gray value of each source pixel to a color class or a point in a continuous gradient of colors. I settled on the following gradient for elevation colors. It stays mostly in the greens to reflect the tropical setting, and moves a bit toward warmer colors at just the highest elevations.

I won’t explain all the code in detail, but basically I drew a vector gradient 256 pixels wide, then sampled the color at each x location and saved it in an array. Thus each 0-255 gray value can be matched to an index in that array. Then, in the loop where all that reflectance math is taking place, I added a couple of lines to draw that color to another BitmapData.

Note there is some additional funny business involving the first couple of values in the array. This is to deal with the ocean in my map. I had trouble getting the blues to look good in the gradient, so after creating the array I set those blues using brute force. I also didn’t want the ocean to show up as gray in the relief image, so if a pixel has a value at that low end that indicates it as water, it isn’t drawn to the relief map.

var gradientColors : Array = [0x0000ff,0x004000,0x679167, 0x81b279, 0xbfdfa8, 0xd0b8aa];
var gradientRatios : Array = [1,3,1*255/4,2*255/4,3*255/4,4*255/4];
var gradientAlphas : Array = [0,1,1,1,1,1];
var matrix : Matrix = new Matrix();
matrix.createGradientBox(255,5);
var gradientShape : Shape = new Shape();
gradientShape.graphics.beginGradientFill("linear",gradientColors,gradientAlphas,gradientRatios,matrix);
gradientShape.graphics.drawRect(0,0,255,5);
gradientShape.graphics.endFill();
 
gradBmp = new BitmapData(255,5);
gradBmp.draw(gradientShape);
 
var colors : Array = [];
 
for ( var n : int = 0; n < 256; n ++ ) {
	colors.push( gradBmp.getPixel32(n,2) );
}
// ARGB again
colors[0] = 0xffccccff;
colors[1] = 0xffccccff;
 
[...]
 
for ( var i : int = 0; i < sourceBitmap.width; i ++ ) {
	for ( var j : int = 0; j < sourceBitmap.height; j ++ ) {
		[...]
		var centerValue : Number = sourceBitmap.getPixel( i,j ) & 0xff;
		tintBitmap.setPixel32( i,j,colors[int(centerValue)] );
		[...]
		if ( centerValue >= 3 ) reliefBitmap.setPixel32(i,j,0xff << 24 | grayValue << 16 | grayValue << 8 | grayValue);
	}	
}

The hypsometric tinting by itself looks like this:

6) PUTTING IT ALL TOGETHER
The final map is a matter of combining the relief and tint images. I found that overlaying the relief map at 30% opacity looked pretty good. A blur filter on both the tint and relief maps helps to smooth out the pixelated coastline and some noise, respectively. And a glow filter on the relief map provides a nice coastal effect, even if I haven’t quite perfected it here.

tintBitmap.applyFilter( tintBitmap, new Rectangle(0,0,tintBitmap.width,tintBitmap.height), new Point(), new BlurFilter(1.2,1.2) );
var tintMap : Bitmap = new Bitmap(tintBitmap);
addChild(tintMap);
 
reliefBitmap.applyFilter( reliefBitmap, new Rectangle(0,0,reliefBitmap.width,reliefBitmap.height), new Point(), new BlurFilter(2,2) );
reliefBitmap.applyFilter( reliefBitmap, new Rectangle(0,0,reliefBitmap.width,reliefBitmap.height), new Point(), new GlowFilter(0xffffff,.75,45,45,3,2) );
var reliefMap : Bitmap = new Bitmap( reliefBitmap );
addChild( reliefMap );
reliefMap.alpha = .3;

Pow. And pau.

7) ADDITIONAL RESOURCES
The formulas in the Slocum et al. textbook are derived from:
Eyton, J.R. (1991) “Rate-of-change-maps.” Cartography and Geographic Information Systems 18, no. 2:87–103.
As for the textbook itself, I’m looking at the second edition, pages 300-301.

It’s been a while since I actually sought out DEM data, but at least for the United States the best source remains the USGS. You can download data for anywhere in the country at http://seamless.usgs.gov/. The USGS also has some worldwide data with GTOPO30. A bit of Googling will likely lead you to additional sources of DEMs.

DEM data may not always come in a format suitable for this particular tutorial. (But remember that this is not the way to go most of the time anyway.) It may come in the actual DEM file format, or perhaps a GeoTIFF that you may have trouble opening in ordinary image editing software. Unfortunately I’m not up on the best ways to convert DEMs to grayscale images. I grew to like MicroDEM, a Windows program from several years ago, for all kinds of DEM manipulation. I’m a Mac user but have fired up Windows on my machine more than once to use this program. Anyway, again the best I can suggest is to use your Google-fu.

Finally, there is no avoiding mentioning the man who is barely short of a deity of relief shading: Tom Patterson. Mr. Patterson, who is known to and revered by all cartographers, does mind-blowing work for the National Park Service, and he has been kind enough to impart some of his wisdom through shadedrelief.com. Do check out that site for a lot of good information and tutorials. He also has created the wonderful Natural Earth I, II, and III maps and has co-spearheaded the Natural Earth vector effort.

Recently I’ve heard two friends independently inquire about some sort of basic guide for loading and drawing a shapefile in Flash. The only real tutorial/example I can recall is here, dealing with Google Maps. But these guys are looking for something more bare-bones. Being a regular user of Edwin van Rijkom’s invaluable code libraries for reading shapefiles, and usually forgetting the process myself, I thought it would be a good idea to put together a very simple set of AS3 classes that load a shapefile and throw a map on screen.

So to get those jerks off my back, I wrote a little thing called ShpMap, which supplements van Rijkom’s classes by loading and drawing a shapefile. It’s nothing fancier than that. Sometimes all you need is to get your base map on screen. (Update: just to round it out a little more, I’ve added basic loading and parsing of a shapefile’s accompanying DBF file, which contains attribute data. This also uses classes by van Rijkom.)

I hope that this class (and the several associated classes) can both be directly usable for some projects and serve as a basic guide to using van Rijkom’s classes to load shapefiles.

Dig it:

• An example that loads and displays a US states shapefile (and then puts a square on my house and colors the state of Wisconsin green). View the source code here.
• Download the source code. (My classes plus van Rijkom’s, as well as a demo US States shapefile.)

1. Added a “moveTo” argument to the curveThroughPoints method, following the idea in one comment on my blog post. Ignore it if you wish, but if you set it to false, the curves will connect to wherever graphics drawing left off rather than moving to the beginning of the curve and starting anew.
2. Hooray trigonometry! Messed with some of the angle calculations to fix problems with zero angles and division by zero. I hope it worked.
3. Provided a line of code that can be altered to use lineTo for straight segments of 3 or more points rather than curving.

Straight lines were raised as an issue in several comments. While I think I have fixed the crazy behavior of straight horizontal and vertical lines, I suspect the result for three points in a line may be surprising at first glance. For instance, the three middle points in the image below are all aligned horizontally.

The S-curve through those points may look odd at first, but it’s actually to be expected with these cubic Bézier curves. Of those three points, only the middle one has curve control points that are also aligned horizontally. The outer two have control points that are also based on the points outside the line. Here’s an approximate example from Illustrator of what they look like

I’ve left that as the default behavior, but I did insert some code that can be modified so that the curve essentially stops curving when it reaches several points in a line, draws a straight line through them, and then continues curving as normal after that. Here’s what the same example looks like with that option enabled.

It’s probably often fine, but I caution that it can result in sharp corners. Here’s the same with those dots removed:

I’m uncertain what’s best, so I’ve made that a line of code that has to be changed rather than a more accessible option. I’d be glad to hear ideas on how best to handle it. Feel free to change it however you like, of course. That and other modifications are identified in the comments.

Download the class here: CubicBezier.as
The previous version is here, in case I screwed something up. Forgive my lack of version control.

I’ve put together two AS files:

• A PanZoomMap class, with some simple panning and zooming methods.
• An example class that creates an instance of the PanZoomMap and demonstrates zooming, basic click and drag panning, and a zoom box.

The code has some simple comments that I hope give an idea of how it works. I’ll let them do the talking, as anything I write here is likely to be long-winded and confusing.

The example is really very basic. A real interactive map is likely to require some more complicated capabilities than what I have provided here, but this is a starting point that may be helpful to anyone who needs an introduction.

Here’s what the test file does. A simple click-and-drag pan/zoom example:

And a zoom box example:

So I have a single map that I need to show at several different scales in an interactive fashion. It’s got to be a pretty big image to look decent when I zoom in, so that means a large file and a long download. But I only need to see the scaled-down map when it first loads. I don’t want to wait for a big image to download when I just need a little one to start! The hip (or some might say “smart”) way to deal with such a problem is to break the image into tiles and load said tiles on the fly as needed. But this is a simple, one-off creation, and I’m too lazy, too stupid, or too pressed for time to figure out tiling.

That was my situation recently. And I thought to myself hey, the world needs more backward-looking individuals, and patted myself on the back for avoiding learning and taking the easy way out: use Flash’s timeline to fake a progressive download!

The solution takes advantage of the way a Flash movie loads: rather than waiting for the whole file to load, individual timeline frames appear as soon as their content has loaded. It’s something I first exploited for my CincinnatiRoads map, embedding videos right in the timeline to allow easier playback manipulation but also have a progressive download. Flash, from what I can tell, supports progressive JPEGs but does not display them progressively.

So, for my map:

1. Save a scaled-down image that is a manageable file size.
2. Divide the full-res image into tiles, also of manageable file sizes (mine is 16 tiles).
3. In Flash, plop the small image from (1) on the stage.
4. Then place the full-res tiles on top of the small image, scaling them down (in Flash!) to match the size of the small image. (When they’re blown back up by zooming in, they’ll look fine.) Place each tile in its own layer, and move each to its own frame. My timeline looks like this:

That’s all. No code (except a stop() at the end), very little thinking, and maybe a half hour spent. I then drop it into my map interface. When the movie loads, it should show up as soon as the small image has finished loading, and then the high-res tiles will come in one by one. Hopefully you noticed that the simple demo map at the top of this post appeared without too much delay even though the full image is a few thousand pixels across and the file is a couple of megabytes (and if files of that size load quickly anyway because you have an amazing internet connection, shut up and I hate you).

Caveats:

• Yes, I know this is not much different from having only two images: one small and one large. But I figured it’s better to see pieces of the high-res image appear as they load rather than nothing… nothing… nothing… EVERYTHING. And it almost looks like there is some kind of actual tiling going on!
• This was helpful for displaying an image that takes too long to download but is not too large to handle. It is not a solution for loading an absolutely huge image. That’s going to bog down the system in the end.

Lately some of my Flash mapping colleagues and I have come to rely on transforming geographic data—say, shapefiles—into various map projections on the client side via the ActionScript vector drawing methods. (See, for example, a post by my friend Zachary Johnson with an old-as-the-hills demo. And don’t you worry: we’ll be releasing something way, way cooler eventually.) But as cartographers know, vector data is just one side of things. What about raster data?

These days Flash allows good pixel-level manipulation of raster images with the BitmapData class. As a cartographer, I thought I’d try a little experiment in map projections.

The goal: Convert an “unprojected” (plate carrée) world map map to a Winkel Tripel projection. I used an image from Wikipedia as a starting point.

This is what we want to end up with:

Not terribly long ago for a mapping project I wasted a ridiculous amount of time on someone else’s dime attempting to reproject a raster map using the ActionScript DisplacementMapFilter class. If you don’t know, what the DisplacementMapFilter does is use the colors on a displacement map image (a BitmapData object) to determine displacement of pixels on another object. One color channel determines the x displacement and another the y displacement, both relative to the midpoint in the range of values for that color (i.e., 127 out of 255). For example, if we use the red channel for x and the blue channel for y, and a pixel in the displacement map has a red value of 255 and a blue value of 0, the corresponding pixel in the target object will be displaced positively 100% in the x direction and negatively 100% in the y direction. The actual number of pixels that 100% represents depends on a specified scale factor.

For a map projection, then, what we have to do is go through the unprojected source image pixel by pixel and determine how far each pixel has to be displaced on both axes by plugging the latitude and longitude values for the pixel into a projection formula. Using red for the x displacement and blue for the y displacement, below is the displacement map I generated for turning the unprojected map into Winkel Tripel.

I then applied that to the source image. The result? Yuck.

It’s probably possible to mess with this method and produce better results. As previously suggested, though, I’ve already spent too much time doing that without coming up with anything decent. In my experience there are three drawbacks to using the DisplacementMapFilter for map projections: (1) because of the way the filter works, if what you know ahead of time is the exact distance that pixels need to be displaced, it seems to be necessary to iterate over every single pixel twice, once to determine the maximum displacement in each direction for the entire image and once to then actually draw the displacement map; (2) precision in displacement is very limited, as it can only be from 0 to 127, in whole numbers, in either direction (multiplied by the scale factor); and (3) some projections will result in larger images than the original unprojected map, and it is a nuisance to try to deal with those using this method.

Screw it, then. Why not just move the pixels manually? To do this, we basically look at each pixel in the source image, run its latitude and longitude through the projection formula to determine its new location on the projected map, and then draw that pixel on the projected map with the color of the source pixel. Here’s what happened when I did that:

Hey, it’s the correct shape! But there are two issues with distorting a map to project it, namely, that the map is going to be compressed in some places and stretched in others. I’ve already attempted to deal with the compression in the above image. Instead of directly transferring the color of a source pixel to the projected map, I kept track of all the source colors that corresponded to a pixel on the projected map, then drew the average color on that projected pixel. Otherwise, when more than one source pixel corresponds to a projected pixel, the color would just be replaced every time one of those source pixels is encountered. In this case it was actually difficult to see much difference, but the attempt at resampling seemed like a good idea.

The second issue, the stretched parts, is evident in the above map, showing up as those white (empty) curves emanating from the edges. That occurred where pixels on the projected map had no corresponding source pixel because of distance distortions in the projection. To correct for this I did a simple interpolation in which I identified pixels with no data and assigned each a color that was the average of any neighboring colors. With that, then, we have our final map:

It’s not the most beautiful map, but not too bad, I’d say. That’s just one type of projection, though. As you might expect, the more interpolation that’s needed, the worse it’s going to look with these methods. Below, for example, is part of a Mercator projection. (Remember how I said larger map projections are a nuisance with the DisplacementMapFilter? Well, they’re kind of a nuisance in general, hence “part of” a map here.) The Mercator projection stretches the map pretty significantly in high latitudes, and as you can see the map doesn’t look very good near the top and bottom.

It’s also worth noting that these raster methods are probably best with continuous images like the example used here. The flaws are more noticeable with a rasterized line map, as below (projected using a source image from the wonderful Gallery of Map Projections).

And Mercator’s not so hot:

For the record, here’s what a nice, scalable, vector map projection from a shapefile looks like in Flash:

This little experiment has demonstrated that reprojecting raster maps in ActionScript is possible, perhaps with acceptable results in a pinch, but it’s far from perfect. I don’t doubt that it would be possible to use more advanced resampling and interpolation methods, but this is already a lot to deal with. The projections here took several seconds to compute and draw on my machine. That’s probably already an eternity in computer time, especially for a relatively small image, and it’s only going to grow as the algorithm becomes more complex. (Okay, minus the time that would be saved if my surely inefficient code were improved.) This kind of thing isn’t Flash’s strong suit anyway, right? Real geographic raster processing is being done with things like GDAL.

But again: in a pinch, it works!

Some references:

• The aforementioned Gallery of Map Projections is a good resource for seeing what different projections look like.
• This Java applet demonstrating map projections appears to use a raster map, though I’m not entirely sure how it operates. The source code is available.
• For map projection formulas, I recommend Wolfram Mathworld or Wikipedia.
• If you have access to the journal Cartographic Perspectives, check out Number 59 (Winter 2008) to see a gallery artistic renderings of map projection distortions by daan Strebe. The displacement map image used in this post reminded me of those images, which were presented at the 2007 NACIS conference.

The bottom line is that I had no luck finding a satisfactory way to use Flash’s built-in curveTo method—which draws quadratic Bézier curves—and instead opted for creating cubic Bézier curves (compare the two in the above image from the Flash documentation). Thanks to Flash’s BezierSegment class, it’s pretty easy to construct these curves. With my limited understanding of the math involved, however, finding good control points for a continuous curve was a bit more challenging.

I put together an AS3 CubicBezier class, which for now just contains two methods: one to draw a continuous series of curves through many points (as was my goal), and one to draw a single curve between two points (seemed worthwhile to throw that in), both demonstrated below. I’m sure there are a few kinks (ha!) to work out, but generally the results seem pretty satisfying. This was written with cartographic generalization in mind, but hopefully it can be more broadly useful.

Files:
These are old versions! See my update post for the latest.
CubicBezier.as
curveTest.zip (AS plus the above demo)

It’s basically a Sprite that has simple drawing methods with dashed lines. Just make a new instance, providing the line width, color, and an array of alternating dash and gap lengths (in pixels). Then call moveTo() and lineTo() methods directly on the Sprite, not its graphics property. (You can also do beginFill() if you want.) For example:

Try it out below!

This is by no means complete, as I’d like to add the rest of the usual drawing methods (curves are going to be tricky) and resolve the bugs that surely exist.  For now, though, download the DashedLine class as is; hopefully it’ll make sense through the basic comments I’ve included.

DashedLine.as
dashTest.zip (AS file plus the above demo FLA)