Posts Tagged ‘GIS’

The Sweet Java Topology Suite – Part II

March 4, 2009

In a previous post, we described how we started using the Java Topology Suite (JTS) to manipulate postal/zip code polygons that we are viewing in an application built on MapQuest’s Flex API. Since then, we have added the ability to join multiple postal codes into territories. Sometimes over 1,000 postal code polygons will be combined to form a single territory.

We ran into two significant technical hurdles. First, MapQuest’s API doesn’t support polygons with inner holes. So, a donut-shaped polygon would just look like a circle, with no hole in the middle. The other problem was that some of the postal codes were so complicated that the unify process would fail.

Union of postal code polygons with a hole in the middle

Union of postal code polygons with a hole in the middle

This union of postal code polygons should have a hole in the middle

Union of postal code polygons, missing the hole in the middle

If you read the other article, you saw that we did use JTS to simplify polygons (by reducing the number of points that make up the polygon). However, we didn’t end up using those in production because the edges of the simplified polygons would not line up. They end up looking like broken glass, because the simplify process had no regard for adjacent polygon edges.

Simplified polygons with edges that don't line up

Simplified polygons with edges that don't line up

So, we set out on an adventure to simplify the polygons so that the edges of the simplified postal codes matched up. We received some very responsive and helpful guidance from Martin Davis, one of the principle developers of JTS. He also pointed us to the open source tool OpenJUMP, which he also helped to build. Source code from that tool was very helpful as we created our own automated simplification process.

Here’s the simplification process in a nutshell:

  1. Convert the MapQuest postal code polygon data for the current patch (like the lower 48 states) to Well-Known Text (WKT) and save each postal code polygon to an individual file on the file system. For the lower 48 states, this resulted in more than 41,000 files. Here is an unsimplified version of the few polygons we’ll simplify in this example:

    Original, unsimplified postal code polygons

    Original, unsimplified postal code polygons

  2. Read all of the WKT files, one per postal code, and store them as JTS Geometry objects in a collection. To support step six (below), we store the postal code in the geometry object using the very handy Geometry.userData property. That way, each original/source geometry remembers what postal code it represents.
  3. Use JTS to convert the polygons to merged LineString objects. This creates a collection of the outlines of every polygon, where the common polygon edges become a single line.

    Extracted border lines of original polygons

    Extracted border lines of original polygons

  4. Use JTS to simplify the merged LineStrings by reducing the number of coordinates that define each line. Our code iterates across every merged LineString and uses JTS’s DouglasPeuckerSimplifier with a simplify tolerance of 0.01.

    Simplified polygon border lines

    Simplified polygon border lines

  5. Use JTS to create polygons from the simplified LineStrings. The primary JTS class was the magic Polygonizer class, along with code from OpenJUMP that prepared the line data for the Polygonizer.

    New polygons made from simplified lines

    New polygons made from simplified lines

  6. Now the tough part. We have a collection of simplified polygons, but they aren’t linked to any postal codes, so we can’t find the polygon and use it in our application. We needed to match the simplified polygon with the original. Since this is among the most involved processes, I’ll describe it in a bit more detail:
    1. Add each of the original polygons to a JTS SpatialIndex called STRtree. The STRtree provides a quick query interface to find polygons that fall within a spatial constraint.
    2. Iterate through each of the simplified polygons, and:
      1. Query the STRtree to find all of the original polygons that touch the envelope (bounding rectangle) of the current simplified polygon.
      2. Find the polygon in that set which has the smallest distance between its center point and the simplified polygon’s center point.
      3. Once the best matching simplified polygon is found, we copy the postal code from the original Geometry’s userData.
      4. Some simplified polygons have no match in the original set because of holes, so those non-matches are thrown out in this process.
    3. Now that each simplified polygon has been identified as matching a postal code, we write new WKT files for each postal code. Our code that writes these files automatically creates MultiPolygon objects for those postal codes that are made up of more than one polygon.

    Simple polygons that remain after match with originals

    Simple polygons that remain after match with originals

In order to run this process on the lower 48 United States, I had to allocate 7GB of my 8GB of RAM to the JVM so that all 41,000 polygons could be simplified at the same time. Fortunately, it’s worth the time to build. Here are the number of coordinates needed to represent all of the polygons for the three areas, both originally and after simplification, along with the savings realized:

Coordinate Count
Original Simplified Reduction
Lower 48 United States 6,276,000 544,000 12x smaller
Alaska 262,000 15,000 17x smaller
Hawaii 72,000 960 75x smaller

Here’s a larger area of polygons, before and after simplification:

Original postal code polygon sample

Original postal code polygon sample

Simplified postal code polygon sample

Simplified postal code polygon sample

In order to create polygons that maintain any holes in the middle with MapQuest’s polygon API, we used JTS to cut a small slice between any inner features and the exterior of the polygon. This leaves a line in the middle of the polygon, but it’s more acceptable than no hole at all. Hopefully MapQuest will support polygons with inner holes in a later release. In fact, it would be really cool if MapQuest would incorporate other structures and features from JTS, including native WKT support.

Simplified postal codes on map

Simplified postal codes on map

Territory on map with hole enabled by slice

Territory on map with hole enabled by slice

We are very grateful for the Java Topology Suite and the polygon processing it allowed us to complete. The project we’re building for Dave’s Endorsed Local Provider program will be much more successful with these improvements.

Java Topology Suite — Sweet!

August 26, 2008

We have been building a sophisticated mapping application in Adobe Flex that enables our internal advisors for Endorsed Local Providers (ELPs) to visualize the regions that our partners cover throughout the country. We’re using MapQuest’s Enterprise API, which has a pretty robust ActionScript 3 library along with a nice Java library.

We wanted to be able to display many zip code polygons on the map, and enable our advisors to click on a zip code and see the ELPs who cover that zip code, among other things. However, early in development, we found that the performance of the application suffered greatly when displaying a large number of zip code polygons.

With focused intensity, we took several steps to improve the performance of the map. These steps include:

  • Reduce the complexity of the zip code polygons.
  • Combine zip codes with multiple polygons into a single polygon.
  • Cache the resulting polygon definitions in our local database, as gzipped XML.

After several failed attempts to accomplish these tasks, we found the Java Topology Suite (JTS), an open source collection of geospacial data manipulation tools created by Vivid Solutions of Victoria, Canada. While capable of many other things, we used JTS to unify multiple polygons into a single polygon, and to reduce their complexity.

Here’s our process to unify and simplify polygons from MapQuest’s API through JTS:

  1. Extract the polygons from a MapQuest FeatureCollection to Well-Known Text (WKT) format.
  2. Create a JTS Geometry object for each polygon.
  3. Use JTS to create a GeometryCollection, then union the polygons with the Geometry.buffer() function.
  4. Simply the resulting polygon with JTS’s TopologyPreservingSimplifier.simplify() function.

Here is the most important portion of the code that does all of the above:

/**
 * Unifies and simplifies a MapQuest FeatureCollection using JTS.
 */
public synchronized FeatureCollection unifyFeatureCollection(
    FeatureCollection origFc, double simplifyTolerance) throws Exception
{
    // Extract polygons from FeatureCollection and convert to Well-Known Text
    ArrayList polygonsAsWTK = featureCollectionToWTK(origFc);

    // Create JTS Geometries
    WKTReader rdr = new WKTReader();
    Geometry[] geom = new Geometry[polygonsAsWTK.size()];
    for (int i = 0; i  0) {
        unifiedPolygon = TopologyPreservingSimplifier.simplify(
                                    unifiedPolygon, simplifyTolerance);
    }
    // Convert result back to FeatureCollection and return
    return jtsGeometryToFeatureCollection(origFc, unifiedPolygon);
}

/**
 * Called by unifyFeatureCollection(), returns
 * the union of the input Geometry array as a single
 * JTS Geometry.
 */
private Geometry unifyPolygonArray(Geometry[] geom)
{
    GeometryFactory fact = geom[0].getFactory();
    Geometry geomColl = fact.createGeometryCollection(geom);
    Geometry union = geomColl.buffer(0.0);
    return union;
}

/**
 * Changes a JTS Geometry into a MapQuest FeatureCollection
 */
private FeatureCollection jtsGeometryToFeatureCollection(
    FeatureCollection origFc, Geometry unifiedPolygon)
{
    FeatureCollection newFc  = new FeatureCollection();
    List polygons  = PolygonExtracter.getPolygons(unifiedPolygon);
    for (Geometry currPolygon : polygons)
    {
        // Parse: POLYGON ((-123.862898 46, -123.863671 46.000707, ....)
        String polygonAsWKT = currPolygon.toText();
        String [] wktPoints = polygonAsWKT.substring(
                                (polygonAsWKT.indexOf("((")+2),
                                 polygonAsWKT.indexOf(")")).split(", ");
        ArrayList newLatLngList = wktPointsToLatLngList(wktPoints);
        PolygonFeature newPf = makePolygonFeatureFromPoints(origFc, newLatLngList);
        newFc.add(newPf);
    }
    return newFc;
}

The result: it works really well. There is still room for performance improvement, but the gains we observed were extremely significant

If you’re working with mapping applications, we’d love to hear from you.  Leave us a comment and tell us about it.