ArcGIS JavaScript API Hack: Overriding Basemap Zoom Scales

map layers

At Bruce Harris and Associates, we’ve helped a lot of our clients share their maps through ArcGIS Online (AGOL). Many of these clients also have high quality aerial photography that provide high resolution at the ground level. However, when they try to mix their high quality tiled map services with basemaps provided by ESRI, things don’t always go as planned. They can’t zoom in far enough to see the level of detail they expect from their aerial imagery. In this three-in-one hack, I’ll show how to override the ArcGIS Basemap zoom scales and let your users zoom down to house level and beyond.

First In Wins

In the ArcGIS JavaScript API, there’s a lot that goes on when a map loads its first layer (a.k.a. base layer).

  • What coordinate system does the layer have? What projection?
  • What is the current zoom scale of the first layer?
  • Is the layer tiled or dynamic?
  • If tiled, what zoom scales does the layer support?

By default, the map accepts all these parameters as its own. The first map sets the behavior that the rest of the maps have to follow. Dynamic layers loaded after the first are told to reproject their data to make it fit. Tiled layers don’t even load if they don’t line up with the base layer.

When mashing up map services, remember that “First in wins”. When you load a map with an ESRI basemap, you’re telling the map that ESRI’s map should be first, and everything else will line up with it or else.

But there is hope. There are ways to override either the basemap or the zoom scales to get that “in your backyard” zoom scale you’ve always wanted. While I normally write ArcGIS JavaScript API hacks, this time I’ll give you tips and hacks for ArcGIS Server and ArcGIS Online, too. It’s a mapping hat-trick of tips to help you out.

On the Server Side

For ArcGIS Server, the tiled zoom scales are applied after you’ve published your map service, but before you cached it. If you’ve followed best practices, then you’ve either reprojected your aerials to Web Mercator (Auxiliary Sphere), or you took the easy route and just changed the data frame projection to Web Mercator (depends on whether you allow underlying data to be queried).

With ArcCatalog open, find your published ArcGIS Server map service, right click it, and select Service Properties. Go to the Caching tab and click the checkbox for “Using tiles from a cache”. There will be a big Tiling Scheme dropdown, and the first option it will provide is “ArcGIS Online / Bing Maps / Google Maps”. STOP!!! Before you choose that, remember what we’re doing. We want to zoom in closer than 1:1128 to enjoy our rich, high detail aerial imagery.

The other three options we’re left with are as follows:

  • Choose a tile scheme file
  • Choose an existing cached map/image service
  • or Suggest

Suggest lets ArcGIS Server list some suggested zoom scales, and you get to edit those numbers yourself. But if you’ve ever looked at the zoom scales for the Web Mercator basemaps provided by ESRI, those numbers are crazy long (by at least 8 decimal places). You’re best options are to either use an existing tile schema file, or an existing map service. It should prompt you for a conf.xml file. Since this may be the first one you’ve cached this way, I’ve provided a tile schema file through Github.

Basically, I copied the conf.xml file from a map service already published with ArcGIS Online/Bing/Google tile layers, then added two more levels at the bottom. The previous schema had 19 zoom levels, so I added two more below them. To get the scale and resolution numbers for the last two levels, I divided zoom level 19 by two, and then by two again. You can adjust the numbers according to your needs.

Also note that this file’s CacheTileFormat is set to a PNG32, which is great for complicated linework, crisp annotation, and semitransparent features, but horrible for aerials. You might want to adjust the file to a JPG CacheTileFormat.

Other map services you want to tile can now be pointed to this map service for a tile schema.

Now, if you’ve already cached your map service with the ArcGIS Online tile levels, and you want to change them… well, it gets complicated. While it’s easy to change the visible zoom scales from the existing list, I haven’t found an easy way to change the zoom scales without blowing away the tiles. The easiest solution I’ve heard about is to create a tile package file (*.tpk) from ArcMap, delete the tile cache, change the tile schema, and the import the tile package file into the tiled service using ArcToolbox. I haven’t tested this, yet.

On the AGOL Side

In the current implementation of ArcGIS Online, there’s no way to extend zoom scales when using ESRI’s basemaps. You get what you get if you get a default basemap. If you want to view the map outside of those pre-defined zoom scales, you’ll have to add a new service as the new basemap. This is perfect if you created a map using the previous example.

AGOL Add layer from web prompt
Adding web service layer and setting it as basemap in ArcGIS Online

Note that you lose the ArcGIS Online basemaps when you do this. If you don’t mind, then go ahead with this. It will save you from having to do the next part.

On the App Side

For much of the general public, a custom web application built with the ArcGIS JavaScript API is the way they’ll see your aerial imagery. However, if youwant to mix and match AGOL basemaps and your higher quality imagery, you’re going to have to add a little hackery to make it work.

Remember what I said about First In Wins? Well, there’s more to it than that. The truth is, if the map hasn’t been created with defined zoom scales, it will accept the scales of the first layer. That means, if you create your map, or your ArcGIS Online webmap, with pre-defined zoom scales, you can override the base map zoom scales, and zoom all the way down as far as your imagery will show.

Here’s an example of a regular ArcGIS JavaScript API map created with both a “street” basemap, and custom zoom scales. Normally, an AGOL basemap has twenty zoom scales (0 – 19), but in the example below, we added two more zoom scales. These match the numbers we defined earlier in the custom tiled map service. Defining it this way lets you zoom two levels past the basemaps, making them disappear at that level.

You may have noticed that I also commented out some of the zoom levels at the beginning of the list. Well, if your high quality aerial photos don’t spread all around the world, why would you need to see the map at a world-wide scale? By leaving out the first few layers, you help your application focus on the area that matters. Not only that, but you don’t have the issue where someone viewing your site on an iPhone 4 is zoomed out a level or two further than someone viewing the site on a desktop.

Here’s similar code as above, but with loading an ArcGIS Online webmap. The webmap in question is one of ESRI’s examples, and doesn’t actually show a custom zoom layer. Most of the clients I’ve used this trick with host their own data, and I wouldn’t want to burden their servers with additional traffic.

So, to recap, we’ve learned that first one in defines the rules, unless the rules were defined for them. We also learned how to use ArcGIS basemaps without letting them take over everything. Finally, we learned that Web Mercator zoom scales are tedious to type by hand (or at least I did).

Leave a Reply

Your email address will not be published. Required fields are marked *