ArcGIS Resource Center

Last week, we discussed vector tiling for improving performance of feature layers. While awesome in its own right, if you’re trying to push twenty megabytes of features over the wire, vector tiling isn’t going to save you. Your app will be slow.

How should complex geometries be handled/served? The intuitive approach is to use multiple layers in a service and, depending on the map’s scale, display different layers with varying levels of geometric detail. And why not? You have the tools and you know the API will let you easily craft a solution; it’ll just take a little time to code the thing.

Well, frankly, that’s a lot of work. Feature generalization is a common enough scenario that you would think the API should just know how to do this type of thing. Thankfully, it does.

When you create a Feature Layer, one of the options is maxAllowableOffset. You might recognize this parameter name from the ArcGIS Desktop generalization tools, where it’s been used for years. For more technical details, please refer to the Wikipedia page for the Douglas–Peucker algorithm. If this is new terminology, go check out the ArcGIS Desktop Help for the Generalize tool.

Another bonus is that the FeatureLayer comes with a setter method setMaxAllowableOffset that you can use to simplify features on the fly. Since the web APIs fire an event when the map’s extent/zoom level changes, you can listen for this event and use setMaxAllowableOffset to indicate an appropriate value.

OK, so now all we have to do is figure out a value for maxAllowableOffset. This can take some trial and error, but let me suggest a method: a feature’s geometry should not display more than one vertex per pixel. After all, a pixel is the smallest unit for our displays, so displaying more than one vertex per pixel is wasted effort. If we want to display no more than one vertex per pixel, we can take the map’s width in coordinate space divided by the map’s width in pixels and we have a reasonable value for maxAllowableOffset. With this method, you are telling your Feature Layer to make sure simplified features do differ from the original by more than the width of a pixel. In fact, this is exactly what happens in the Generalize Features JavaScript API sample.

But wait, there’s more! Because this is such a useful idea, ArcGIS.com does it for you automatically. Whenever you add a feature layer to an ArcGIS Online map, maxAllowableOffset is calculated and set appropriately. This results in a better performing map and feature layers that load faster than if complex geometries were sent across the network.

Finally, one caveat. You can’t specify maxAllowableOffset on layers that you allow users to edit. If you’re editing a feature, you need to see the true representation of that feature, including all its participating vertices. Editing a generalized feature and then sending it back to the server could wipe out detailed information that was meticulously created and maintained. We wouldn’t want that, so you can’t specify maxAllowableOffset on Feature Layers that are editable.

Contributed by Derek Swingley of the ArcGIS API for JavaScript development team