Hack 66. Java-Based Desktop Mapping with Openmap

Make personalized maps on your desktop using a free Java program.

While its history goes back farther than written language, serious cartography has always been a pursuit of governments or wealthy, esoteric intellectualsuntil now. For the past decade or so, we have had the computational power to run mapping software on desktop PCs, and a number of companies have provided us with digital atlases with extensive street maps. In the mid-1990s, MapQuest exploded onto the scene, forever changing the way people send out party directions. None of this software, however, really allowed people to personalize their maps. That continued to be a feature of software that cost thousands, if not tens of thousands, of dollars. Only recently has lower-priced, consumer-grade mapmaking software become commonplace, and it still isn't as easy to use as your average Microsoft or Adobe product. However, for über-hackers like us, it's ready for prime time!

6.4.1. Preparation

This hack gets us started with mapmaking in Java by installing an open source application called Openmap and making a custom map of the United States with it. First we'll need to install Java. Openmap requires only a Java Runtime Environment (JRE), but since we're hackers, we'll install a Java Software Development Kit (JSDK), so that we can compile Java code in addition to executing others' programs. Download and install a JSDK from java.sun.com, making sure you get Version 1.4 or higher. Then download Openmap from openmap.bbn.com. While Openmap is open source, it is not licensed under the GPL, so if this concerns you, be sure to carefully read the license before downloading. Just make sure to copy the file openmap.properties from the program's installation directory into your home directory. This will be important later, as the primary way to customize the application is by editing this file.

Make sure everything is going well by running Openmap. If you get something that looks like Figure 6-21, congratulations on making your first map!

Figure 6-21. Starting Openmap

6.4.2. Take a Spin Around Openmap

Unlike a graphics program like Photoshop or Flash, Openmap knows the real-world location of every pixel on the map. Pass your mouse over the world and see the geographic (Lat, Lon) and screen (x, y) coordinates displayed underneath Antarctica. The first thing you probably want to do is zoom in on interesting places. Openmap provides a few different ways to navigate, but we'll use the simplest to get started. Notice the navigation compass in the top left corner of the window. Click on the magnifying glass with the + in the middle to zoom in, and the one with the - to zoom out. Click on the arrows to move laterally in a given direction. You can also zoom to "bookmarked" places on the map that appear in the Layer menu. Right now, there is only one item, "World." We're going to add a new one so that our map opens to the United States.

Quit the program and open a copy of openmap.properties in your home directory using your favorite text editor. Search for gotoMenu.views=. There should be a number of commented-out lines that define three bookmarks for Argentina, India, and the United States. Uncomment these now. This will reveal the bookmarks in Openmap, so save your work, start the program again, and use these new menu items to quickly zoom in on the United States.

The next feature we'll reveal is the wealth of data that comes with the program. From the Layers menu, select "World Cities." The map should now look like it has the measles, covered with little red dots. We can do better than this, though. Choose "Edit Layers..." from the Layers menu. In the dialog box that appears, scroll down to find "World Cities" and click on the legend icon, which sits between the light bulb and the layer name. In the new dialog box, check "Show Location Names" and "Declutter Names." Close the "World Cities" and the Layers dialogs. Now you're well on your way to building your own personal atlas.

6.4.3. Add Data from the Web

One great thing about being in the United States is that the government provides crazy amounts of geographic data for free or very little cost. We're going to get state boundaries from the U.S. Geological Survey to add a little more detail to our U.S. maps. There are a number of other places to download data, such as www.geo-one-stop.gov and nationalmap.usgs.gov, but for our simple purposes, the National Atlas, found at nationalatlas.gov, is the best place to start. Go to http://nationalatlas.gov/mapit.html, read the system requirements, and select "Go straight to the Map Maker." Later you can explore this pretty cool site for hours, but we're just going to grab a file and go. Click on the Download button in the top right corner of the page. In the page that pops up, search for "States." You'll encounter a number of interesting pieces of data that you could download and add to your personal atlas, including crime and employment statistics, but for now keep searching until you find the data set entitled "States." Click on the link to download statesp020.tar.gz, and unpack this file when you're done. You should end up with a directory called statesp020 containing these files:

• statesp020.dbf
• statesp020.shp
• statesp020.shx
• statesp020.txt

Put this folder somewhere convenient. I like to keep all my geographic data in one place, organized by country and province or state. For example, I put these files in /geodata/us/countrywide/.

If it's not already running, fire up Openmap. From the Layers menu, choose "Add Layers..." Select "Shape Layer with Attributes" from the drop-down menu, and replace "Layer Name" with something more useful, like "U.S. States." Now we need to tell Openmap where to find the actual data. To do this, hit the Configure button. This presents the intimidating dialog box, shown in Figure 6-22.

Figure 6-22. Configuring a layer in Openmap

After the first three lines, this dialog is all about cartographic symbolizationpicking the colors your data will draw in. The important thing to know is that default values are filled in for everything, so you just need to fill in the locations of the data set components. If you saved the data using the directory structure I used, your .shp file path will be /geodata/us/countrywide/states/statesp020.shp. Similarly, your .dbf path will be /geodata/us/countrywide/states/statesp020.dbf, and .shx will be /geodata/us/countrywide/states/statesp020.shx. Enter these values and press OK. After a few seconds, the U.S. states should draw on your map in (almost) exactly the right places, as illustrated in Figure 6-23.

Figure 6-23. U.S. state borders, shown in Openmap

6.4.4. Hacking the Hack: Preserve Your Settings

That was exciting, but as soon as you quit Openmap, the U.S. States layer is gone. You'll probably want to add this layer to the basic ones that are always available in the program (if you live in the U.S.). The program doesn't have a save function, but you can program this layer into Openmap's startup file. Open your openmap.properties file again. This time, search for openmap.layers=. This is where you specify what data should show up on your map. The rest of the file consists entirely of properties that describe the location of datafiles and how they should be cartographically symbolized, but they won't show up at all if they aren't listed in openmap.layers. Put the word usstates at the beginning of your list, which should now look something like this:

openmap.layers=usstates date dtlayer distlayer quake daynight cities test graticule demo shapePolitical

You may also want to add usstates to openmap.startUpLayers, so that it's visible when the program starts.

The next step is to specify what we mean by usstates. We'll enter the same information we used when specifying our "Shape Layer with Attributes" from within the program, but here we use a different syntax. Go to the end of the file and type in the following lines:

# My US States layer usstates.class=com.bbn.openmap.layer.shape.ShapeLayer usstates.prettyName=US State Boundaries usstates.shapeFile=/ geodata/us/nationwide/states/statesp020.shp usstates.lineColor=ff000000 usstates.fillColor=ffffffcc

This tells the program where to find the data. It also specifies that the outlines of all polygons should be drawn in black and the insides should be a light yellow, as shown in Figure 6-24.

Figure 6-24. U.S. state borders, shown in Openmap

6.4.5. The Results

I'm sure you've had that eureka moment by now, realizing you have the basic skills needed to be the best mapmaker on your block. In addition to the sites mentioned earlier, government resources like EPA's Enviromapper (http://www.epa.gov/enviro/wme/ and http://www.epa.gov/enviro/html/multisystem_query_java.html) can tell you all about pollution in your community, and the Census Bureau (http://www.census.gov/) gives you the scoop on demographic statistics like race, income, and employment. Just think of the killer maps you can help your children produce for their next class paper!

Raj Singh