MapCruncher for Microsoft Virtual Earth Help

Welcome to MapCruncher for Microsoft Virtual Earth Help

This help file is designed to get you started using MapCruncher for Microsoft Virtual Earth. It contains the following topics:

  • About Map Cruncher introduces MapCruncher.
  • Using MapCruncher walks you through creating a simple mashup.
  • Advanced Features provides information on advanced MapCruncher features.
  • Troubleshooting MapCruncher provides guidance in troubleshooting MapCruncher issues.
  • MapCruncher Tips provides tips to help you get the most out of MapCruncher.
  • MapCruncher Limitations describes some known limitations of MapCruncher.

© 2007 Microsoft Corporation. All rights Reserved. Send Documentation Feedback


About MapCruncher

MapCruncher is a tool designed to quickly convert existing maps into an online format that is as fast and easy to use as Virtual Earth. MapCruncher transforms maps into a common Mercator projection used by Virtual Earth. By putting a large collection of maps into a common projection, users can mix-and-match maps to use them in new ways. MapCruncher will take your input map (such as a PDF), and generate a collection of small, correctly-aligned tiles that can be viewed in Virtual Earth.

There are a few things that MapCruncher is not. MapCruncher is not designed to handle schematic (not to-scale) maps. MapCruncher is not geographically perfect. It uses an approximation to transform maps, and thus sacrifices some precision in feature location. MapCruncher is not a tool for drawing maps; instead, it is designed to convert existing maps into a web-viewable form.


Using MapCruncher

This topics demonstrates how to use MapCruncher by showing you how to create a simple mashup of the Microsoft Redmond campus map.

  1. Find a map you want to crunch in a supported file type. Be aware that maps may be under copyright, which restricts your ability to republish them. For this help file we are going to use the Microsoft Redmond Campus Map found at http://members.microsoft.com/careers/mslife/locations/images/campus_map.jpg, as shown in Figure 1.

    Figure 1. The Microsoft Redmond campus map

  2. Right-click campus_map.jpg and save it to your local disk.
  3. Launch MapCruncher. It begins by creating a New Mashup document.
  4. Select File, Add Source Map, and select campus_map.jpg, as shown in Figure 2.

    Figure 2. Selecting a source map

  5. Create the first of three correspondences as follows:
    1. Navigate around the source map to find an identifiable feature. Drag the mouse to pan. Double-click to center and zoom, or use the mouse wheel to zoom in and out. Place the feature under the crosshairs, as shown in Figure 3 (shown at zoom level 5).

      Figure 3. Placing an identifiable feature (156th Ave NE and NE 36th St)

    2. Navigate around the Virtual Earth map to find the corresponding feature, as shown in Figure 4 (shown at zoom level 15).

      Figure 4. Placing the corresponding Virtual Earth feature

    3. Label the point (this step is optional), as shown in Figure 5.

      Figure 5. Labeling a point

    4. Click Add, as shown in Figure 6.

      Figure 6. Adding a correspondence

      Repeat this process for the other two correspondences. Now you have a rough registration between the maps. The procedure for adding more correspondences is easier, and each correspondence you add reduces error.
  6. Click Lock, as shown in Figure 7.

    Figure 7. Locking the map

    Note that as you manipulate the source map, the Virtual Earth map moves along with you.
  7. Find a new point on the source map, as shown in Figure 8.

    Figure 8. Finding a new point

  8. Click Unlock, as shown in Figure 9.

    Figure 9. Unlocking the map

  9. Fine-tune the position on the Virtual Earth map, as shown in Figure 10. Notice how we changed the campus map zoom level to 6 and the Virtual Earth zoom level to 16.

    Figure 10. Fine tuning the map

  10. Label and add the new point. Repeat this process until you find that new points do not seem to require very much tuning.

    Tip: Error distances and the error wand
    Troubleshoot: How many points do I need?
    Troubleshoot: Why does my map look skewed?
  11. Tell the visitors where to find the original maps (this step is optional), as shown in Figure 11.

    Figure 11. Adding source information

  12. Select the Maximum (Closest) Zoom value and click the Render button, as shown in Figure 12.

    Figure 12. Select zoom level and start rendering process

    MapCruncher calculates a default zoom level based on the size of the source map. MapCruncher renders in order from far-away tiles to zoomed-in tiles, so you can request a higher zoom level than you require, and cancel rendering at any time.

    NOTE: Each additional zoom level quadruples the number of tiles generated, and also the time taken to render and the space required to store the tiles. At level 1, four tiles cover the surface of the Earth; street level is around level 19. Before you set the zoom level greater than 19, be aware that at high zoom levels estimation can take minutes and rendering can take hours.
  13. Select an output folder where the rendered results are stored, as shown in Figure 13. You can select a folder served by your Web server, if you want to publish the results.

    Figure 13. Set rendering options

  14. Click the Start button. As MapCruncher begins rendering, it estimates the rendered output size, as shown in Figure 14.

    Figure 14. MapCruncher estimate

    It should take about a minute to render the campus map.
  15. Use the links to view the rendered tiles inside MapCruncher, or with your Web browser (this step is optional), as shown in Figure 15.

    Figure 15. Viewing the rendered tiles

  16. If you are publishing your results on your Web site, copy the rendered folder to your Web server, and open the SamplePage.html file in a browser. It should look something like Figure 16.

    Figure 16. Viewing SamplePage.html

  17. You can use the SamplePage.html file as a basis to create your own customized page. Be sure to place your customized data outside the folder rendered by MapCruncher, so that if you re-render your maps from MapCruncher, you don't lose your updated data. Your custom HTML page should point to the automatically generated .crunched.xml file; that way, when you re-render your map, the new contents appear automatically in your custom HTML page.


Advanced Features

This topic describes a number of advanced MapCruncher features.

Editable Bounding Regions

By default, MapCruncher makes everything beyond the bounding box of the original source map transparent. You can trim out more of the source map to cut out insets, legends, or to make better-fitting boundaries between adjacent source maps in a single layer. The round corner points of the blue bounding region can be adjusted by dragging, as shown in Figure 1.

Figure 1. Editable bounding regions

To make more complicated shapes, right-click on a blue edge and choose Add Point, as shown in Figure 2.

Figure 2. Adding a point

Multiple Source Maps in a Single Layer

A layer is a single tile set that is always viewed at once. It may comprise a single source map, or multiple source maps. Figure 3 shows four maps from adjacent counties displayed as one continuous layer.

Figure 3. Four adjacent maps displayed as one continuous layer

To add source maps to a layer, right-click on the layer name in the Map Layers pane and choose Add Source Map, as shown in Figure 4.

Figure 4. Adding a source map

The source maps in a layer overlap in the order they appear in the Map Layers pane. You can drag and drop a source map to reorder it. Selecting the layer name changes the Source Map to a preview of the composite layer. MapCruncher displays a progress bar during preview because composite layers are composed of many pieces, and preview can take a long time to render.

MapCruncher does not contain the functionality to modify the z-order of source maps in a layer. However, you can implicitly set the z-order by editing the YUM file (it is an XML file) to reorder the <SourceMap> sections.

Multiple Layers

Rendering transforms all of the source maps in a layer into a single unit. However, MapCruncher also supports distinct layers that can be individually activated in the browser, as shown in Figure 5.

Figure 5. Two distinct layers

A context menu in the layer tree lets you add additional layers, which MapCruncher renders into separate tile folders. The SamplePage.html file demonstrates how to let your Web visitor turn individual layers on and off, as shown in Figure 6.

Figure 6. Adding layers

Browser performance note: if you do not need to compose maps dynamically, incorporate the maps in one layer rather than in separate layers. Because the browser must download a separate set of images for every layer, viewing several layers simultaneously can hinder performance.

Legends

You can specify where MapCruncher places legends on a source map using the Add Legend command on a layer, as shown in Figure 7.

Figure 7. Adding a legend

Use Editable bounding regions to clip out the legend, as shown in Figure 8.

Figure 8. Clipping a legend

Transparent Areas

MapCruncher creates a transparent area in the following circumstances:

  • Regions beyond the bounds of each source map are transparent.
  • Regions within the source map that are marked transparent, such as in a PNG file, or not drawn, such as in a PDF file, are transparent.
  • Regions excluded using an editable bounding region are transparent.
  • The VirtualEarth SDK provides a method, VEShape.SetFillColor, to make an entire layer transparent.
  • You can define a color set, and either make out all regions of those colors transparent, or all regions not of those colors transparent.

To define a color set and make a region of that color transparent, select a source map, then select the Transparency tab, as shown in Figure 9.

Figure 9. Selecting a transparent color

Use the source map crosshairs to identify colors to add to the color list (just as you would add a correspondence point), and select Add Color Under Crosshairs. The source map will show the effect immediately, as shown in Figures 10 and 11.

Figure 10. Selecting a transparent color

Figure 11. The resulting transparent map

Fuzziness controls how nearly a color must match the selected color to be knocked out; a larger number includes more nearby colors. This can help knock out “almost-white” regions, such as artifacts created by JPG compression. In our sample map, increasing the fuzziness beyond 6 has little benefit.

Halo expands the opaque region by the chosen number of pixels, typically allowing a contrasting neighboring color in the source map to show through. This can help make map features more visible when displayed against various backgrounds. For example, a black source map label may look fine superimposed over a light-colored road map, but be very difficult to read when the background is changed to an aerial photography of a dark forest.

Sharing Options

The Mashup Render Options window lets you select output options for rendering. To have MapCruncher copy the rendered data to a folder, use the Output Folder text box, as shown in Figure 12.

Figure 12. Selecting an output folder

To have MapCruncher also copy your source files to the same folder, select the Copy source maps and crunchup data to the output folder checkbox, as shown in Figure 13.

Figure 13. Selecting the Copy source maps checkbox

This option copies the original source map files plus the YUM file to the rendered output folder. This makes it simple to make your mashup available on the Web. By doing this, any Web visitor that views your mashup can reconstruct it from these original files, and perhaps modify it. If you prefer to only publish the crunched version of your data, but keep the source map files (PDF and JPG input files) private, uncheck this box.

To have MapCruncher tag the MapLayers.crunched.xml file marked it as public domain, select the Permit composition checkbox, as shown in Figure 14.

Figure 14. Selecting the Permit composition checkbox

This option permits others to build mashups that build on your crunched tiles. Note that this option only marks the XML description file as public domain; it does not mark the crunched tiles, YUM file, or the source map images as being in the public domain. To discourage others from building new mashups that compose with your mashup data, uncheck this box, and insert a comment in the MapLayers.crunched.xml file explicitly outlawing their use.


Troubleshooting MapCruncher

Why does my map look so skewed?

One likely possibility is that the map is schematic (not to-scale), like the Washington DC subway map in Figure 1. In that case, MapCruncher cannot transform the map.

Figure 1. Washington DC Subway Map

Another possibility is that the map is mostly to-scale, but the cartographer has taken a few liberties. MapCruncher had difficulty registering points on the Vashon Island map shown in Figure 2. The note next to the explains why.

Figure 2. Vashon Island map and note

Another notorious map with liberal geographic features is the New York MTA Subway map. The remark in the key, as shown in Figure 3, explains why.

Figure 3. MTA map remark

Another possibility is that you have selected some dramatically incorrect correspondences.

No matter how many points I add, I always have to fine-tune a little

If you have to fine-tune a lot, you may have a not-to-scale map. Perhaps one or two points are incorrectly matched, and are throwing the rest of the approximation off. Use the error column, and re-check the correspondences with the worst errors. Replace suspect correspondences.

Make sure you are using correspondence points that are widely separated on the source map. If you start with a dense cluster, MapCruncher has to extrapolate for far-away points, and extrapolation produces bigger errors than interpolation. In this Los Angeles Transit map, all of the correspondences are in the city, which leaves features at the edge of the map not tied down, as shown in Figure 4.

Figure 4. Los Angeles Transit map

Sometimes the road atlas data in Virtual Earth doesn’t match the aerial photography. We recommend registering to features in the Hybrid View, as shown in Figure 5.

Figure 5. Hybrid view

Ultimately, you may never get a perfect match. This can happen due to limitations of MapCruncher’s approximate transformation, or due to errors in the source map itself, as shown in Figure 6.

Figure 6. Source map with errors

How many correspondence points do I need?

Some source maps, such as aerial photographs or floor plans, are drawn in “conformal projections”, and can be registered with as few as two points, as shown in Figure 7.

Figure 7. A map with two correspondence points

Other maps require at least three points. Figure 8 shows the two correspondences are correct, but the source map is obviously locked in an incorrect position: the Northern border of Washington is not East-West, as it appears on the right. That’s because the chosen source map happens to not be a conformal projection.

Figure 8. Non-Conformal Projection of Northern Washington

Adding one additional point tells MapCruncher how to fix the problem, as shown in Figure 9.

Figure 9. Normal Projection of Northern Washington

MapCruncher rarely needs more than 15 to 20 correspondences, even on detailed maps such as a county-wide map with street-level detail. Beyond that, other sources of error usually limit the fidelity of the results.


MapCruncher Tips

This section contains some tips to help you use MapCruncher more effectively.

Supported Source Map Types

MapCruncher supports the following source map types:

PDF

The highest-quality results are usually obtained from a PDF file. PDF files often contain vector graphics, which look good even when they are rendered at high zoom levels.

JPG, PNG, TIFF, GIF, BMP

These raster formats can be used with MapCruncher, but unless the source map is at high resolution, the results will look poor at high zoom levels. Scanned maps (such as historical maps) are often available as raster images.

WMF, EMF

These file formats seem to be less common, but they can include vector data, and can produce high-quality results.

Error distances and the Error Wand

When the maps are locked, the correspondence table includes an Error column that shows how well the approximation could match up your points; it is sorted with the greatest error at the top. If the topmost point has a substantially greater error than those below, this suggests that you may have misidentified that point, as shown in Figure 1.

Figure 1. Error Column

Double-click the suspect point. The green wand leads from the point you selected towards where MapCruncher suspects that the correct point should go. Do you think the point in Figure 2 matches the intersection?

Figure 2. Questionable point

If you look closely, the pin in the source map is a block too far North, as shown in Figure 3.

Figure 3. One block too far North

Moving the map in Small Increments

Use the Ctrl-Arrows to move the source or Virtual Earth map views under the crosshairs by small increments.

Using the Source Info Tab

Use the Source Info tab to store the URL, home page, and description of the source map. This information is included in the sample output page generated by MapCruncher. If you publish your mashup to the Web, this information much easier for your Web site visitors to find the original map.

Recursive Registration

Click View, Show Rendered Layer to place your own rendered tiles over the Virtual Earth map. You can use this function to register one map into Virtual Earth, and then register a second map to features only visible in your own first map.

Fine-Tuning a Point Using the Update Button

When fine-tuning a correspondence point, you can select the point in the correspondence list, nudge the maps under the crosshairs, and then click the Update button to adjust the stored correspondence. Update can also be used to rename a point.

Insets

If a source document contains multiple maps that must be registered separately, such as insets, you may Add Source Map multiple times, specifying the same source file repeatedly as shown in Figure 4. Use editable bounding regions to select different parts of each added instance of the map.

Figure 4. Insets

Multiple Page Source Documents

If your source map appears in a PDF file with multiple pages, you can click Add Source Map, and save the YUM file. Then use a text editor to change the PageNumber attribute in the YUM file.

Source Maps from URIs

MapCruncher can load a source map from a URI each time it starts. To do this, replace the existing <Document> tag for the map with one similar to Listing 1.

<Document>
   <UriDocument Uri="http://adds.aviationweather.gov/data/satellite/latest_WMC_vis.jpg" PageNumber="0" />
</Document>

Listing 1. URI Document tag

Invoking MapCruncher from the Command Line

MapCruncher can be invoked from the command line with the name of a YUM file to open. If you also supply a render flag, MapCruncher render the YUM file and exits when it is done. Combined with Source maps from URIs, this enables the creation of a scripted pipeline.


MapCruncher Limitations

This topic describes some known limitations of MapCruncher.

Schematic (not to-scale) Maps

MapCruncher is not designed to handle schematic (not to-scale) maps. In a to-scale map, MapCruncher can infer from only a few correspondences how all of the rest of the data should be transformed. In a schematic map, the cartographer has taken arbitrary liberty with the world geometry, and no set of correspondences say anything certain about other unlabeled points.

Approximate Re-Projection

MapCruncher uses an approximation to re-project to-scale maps from their original projections into Virtual Earth’s Mercator projection, and thus sacrifices some precision in feature location. Disciplined cartography involves understanding both the relationship between angular measures (latitude and longitude) and the surface of the Earth, and the relationship between those angular measures and the surface of the map (projection geometry). MapCruncher understands neither. Instead of modeling source projection, source datum, Virtual Earth datum, and Virtual Earth projection, MapCruncher uses a simple function to directly approximate the relationship between the original map and the Virtual Earth map.

Mathematically speaking, MapCruncher uses either an affine or a quadratic polynomial to approximate the projection. The quadratic polynomial admits curvature in the approximation, which helps handle the curves that appear in conic projections, as shown in Figure 1.

Figure 1. Approximate projection

Polynomial fitting can only be approximate, because a polynomial can never quite match the trigonometric curves produced by geographic projections.

However, that the approximation is suitable for a wide variety of maps. Frequently, the source map exhibits more internal error than the approximation. Approximation error is apparent in very detailed maps (maps whose smallest feature is tiny compared to the extent of the map): In the case of the King County Bike Map, the approximation seems to be responsible for errors of up to about a quarter-block.

Some High Zoom Levels Cause Long UI Stalls

If you zoom far into a vector map with text, the UI can stall (including a frozen mouse pointer) for quite some time. The only work-around is to avoid zooming too far into a vector map with text.

Browser Support

MapCruncher is compatible with the following browsers:

  • Microsoft Internet Explorer 6 and later versions on Microsoft Windows
  • Mozilla Firefox 1.5 and later versions on Microsoft Windows, Apple MacOS X, and Linux