![\"A](\"media/mapkit-flipped-tiles.png\")
Despite nearly 15 years of developing iOS apps on a daily basis,\nit’s occasionally jarring to go back to some of the older APIs.\nToday's blog is about MapKit,\nwhich isn't quite as old as CoreGraphics, but dates back to iOS 3.0!\nIt was a bit slimmer back then, but some of the APIs we'll be looking at today go back to iOS 7!
\nTo set the stage, MKMapView, the main "view" in MapKit,\nlets you add a sort of minimalist Apple Maps experience to your app in approximately one line of code.\nOr no code if you're using Storyboards / Interface Builder.\nThis is about 100x easier than it is on any other platform I can think of.
But map-centric user experiences almost never stop with just a basemap.\nYou probably want to throw some data on top, like the outline of an area of interest,\nmaybe filled in with some color coding.\nOr maybe a route line, or a "pin" to show all the nearby hotels and how much they charge per night.\nThese are all vector data in industry jargon.
\nOne of my former clients was an agricultural tech startup that was later acquired\nby a company with a large business related to weather data.\nIt turns out weather is really important to farmers.\nAnd a lot of weather data, like radar and expected precipitation,\nare displayed as a raster overlay on the map.\nIn this case, usually transparently.
\nA second use case for overlays is custom cartography.\nApple's maps are fine (superb, actually!) for many use cases,\nbut you can't customize very much about them.\nThis might be a dealbreaker if you need something outside the box\nlike hillshading or ocean depth,\nor if you want to swap out the satellite imagery for something more locally up to date.
\nOverlays are the solution to this too; you can replace the entire base layer with your own!\n(Sadly MapKit can't, and probably won't ever support slick vector tile rendering from third-party sources.\nCheck out MapLibre Native instead for vector basemaps and a whole lot more.)
\nToday's post is about overlays in MapKit,\nsome surprising behaviors that I found along the way,\nand maybe even a few bits of ancient wisdom\nto share on StackOverflow.
\nMapKit has long had support for overlays.\nPer Apple's docs,\nit looks like user overlays were added in iOS 7.\nBut if you poke around closely,\nyou might notice that the MapKit docs are subtly split into two APIs:\nMapKit for AppKit and UIKit, and MapKit for SwiftUI.
\nThe SwiftUI docs aren't just about a nicer way to use MKMapView in your SwiftUI apps;\nit's about a completely different API, still under the MapKit umbrella.\nIn contrast to the old API where you have to implement a delegate just to add something to the map,\nthe new API is relatively modern.\nBut it's missing a few things.\nAnd the largest hole of them all is.... you guessed it! No overlays!
To be fair to Apple, the new API is pretty new.\nAnd it probably seems like the use cases for raster overlays are fairly niche,\nbut I'm a bit confused why Apple dropped this functionality.\nSo if you're building a live weather radar app,\nyou need to use the AppKit and UIKit variant of MapKit.\nOr MapLibre.
\nBut let's say you actually do need to use MapKit for this purpose?\nThere are at least two good reasons you might want to:
\nMKTileOverlayOk, let's take a look at the APIs here.\nThe first one we'll look at is MKTileOverlay.\nThis is a pretty straightforward class that describes a tile-based data source.\n(If you've used maps for a while, you may occasionally notice when the map fills in like a mosaic;\ninternally it's made up of these "tiles" that are stitched together client-side.)\nIt has properties describing the valid zoom range\nand a few ways of specifying where to get the tiles.
The constructor takes a urlTemplate string argument.\nThe template looks like this: https://tiles.stadiamaps.com/tiles/stamen_terrain/{z}/{x}/{y}.png?api_key=YOUR-API-KEY.\nThis is supposed to "just work."\nBut if you need something a bit more advanced,\nyou can implement url(forTilePath:) instead to return a URL.
This sounds like an "oh, that's nice" sort of API,\nbut it's surprisingly useful.\nFor example, they support a {scale} placeholder,\nbut there is no maximumScale parameter in the public interface.\nFor reasons that should be obvious, few if any tile servers\nare investing in rendering out PNG tiles at triple the normal resolution,\nso @2x is the max that most will support.
If you implement url(forTilePath:), the constructor parameter is ignored.\nA rather clunky method of encapsulating things,\nbut I'll give the Apple engineers some slack,\nas this dates back to the era when object-oriented programming reigned supreme\nand we hadn't rediscovered the joy of protocols yet.
Finally, if you want even more control,\nyou have loadTile(at:result:), which asynchronously loads the tile data.\nThis gives you ultimate freedom in how you make your network request,\nif you make a network request at all, how you cache tiles, etc.\nWe'll revisit this in a bit.
Adding an overlay to the map is not quite as straightforward as mapView.addOverlay(overlay).\nThe design of MKMapView is quite flexible... so much so that you have to implement\nmapView(_:rendererFor:) on your delegate, or else no overlays will render!\nEnter MKTileOverlayRenderer.\nThe map view itself doesn't know what to do with the overlay.\nIt requires an overlay renderer to do that, and MKTileOverlayRenderer is built for tile overlays like this.
A simple and "obvious" way to bring everything together looks something like this:
\nimport UIKit\nimport MapKit\n\nlet stadiaApiKey = "YOUR-API-KEY" // TODO: Get one at client.stadiamaps.com\nclass ViewController: UIViewController {\n\n @IBOutlet var mapView: MKMapView!\n\n override func viewDidLoad() {\n super.viewDidLoad()\n\n let overlay = MKTileOverlay(urlTemplate: "https://tiles.stadiamaps.com/tiles/stamen_terrain/{z}/{x}/{y}.png?api_key=\\(stadiaApiKey)")\n mapView.addOverlay(overlay)\n }\n\n}\n\nextension ViewController: MKMapViewDelegate {\n func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {\n if let tileOverlay = overlay as? MKTileOverlay {\n return MKTileOverlayRenderer(overlay: tileOverlay)\n } else {\n return MKOverlayRenderer(overlay: overlay)\n }\n }\n}\nNot too bad, aside from the large amount of boilerplate (also ignoring for the moment that the images aren't scale optimized).\nThere's just one problem... the UX is awful!
\n\n\n[!bug]
\naddOverlaydocs bugAt the time of this writing, the docs for
\naddOverlay\nstate that "The map view adds the specified object to the group of overlay objects in theMKOverlayLevel.aboveLabelslevel."\nThis is not what actually happens.\nSo the above code is theoretically correct, but will be even more surprisingly broken in practice.\nTo fix this bug, writemapView.addOverlay(overlay, level: .aboveLabels).
I initially thought the flashing behavior was a result of a poor cache implementation.\nSo the first thing I did was to write my own MKTileOverlay subclass.\nI knew I wanted to provide my own loadTile(at:result:) implementation anyways (to load the max available image scale).
After digging into the cache behavior though (and replacing it with my own instance of URLCache which I could inspect),\nI realized the problem was not the cache responsiveness.
MKTileRenderer was the next suspect.\nRegrettably, this is a completely closed source library,\nso there's no way to know for sure what's going on under the hood,\nbut I was able to reverse engineer a few things.
First, the problem is related to the way MKTileOverlayRenderer\nimplements canDraw(_:zoomScale:) and draw(_:zoomScale:in:).\nThe class seems to indicate that it can't draw anything when the data is not available at this exact zoom level.\nThis is rather annoying,\nsince the entire map will disappear and then rapidly fill in every time you cross over a zoom boundary!
Which means we have to go even deeper.\nTime to implement our own overlay renderer!
\nThe overall approach I settled on for the first (and fortunately only!) pass\nwas to leave canDraw(_:zoomScale:) unimplemented, so it will always try to draw something.\nFor the draw method, my goal was to put cache hits directly in the hot path,\nand kicking off async requests in case something wasn't in the cache.
Here's most of the code:
\n/// A generic protocol for MapKit tile overlays which implement their own queryable cache.\n///\n/// This is useful for making overlays more responsive, and allowing for fallback tiles\n/// to be fetched by the renderer while waiting for the higher zoom tiles to load over the network.\n/// While technically not required, it's easiest to just subclass `MKTileOverlay`.\npublic protocol CachingTileOverlay: MKOverlay {\n /// Fetches a tile from the cache, if present.\n ///\n /// This method should retorn as quickly as possible.\n func cachedData(at path: MKTileOverlayPath) -> Data?\n func loadTile(at path: MKTileOverlayPath, result: @escaping (Data?, (any Error)?) -> Void)\n\n var tileSize: CGSize { get }\n}\n\npublic class CachingTileOverlayRenderer: MKOverlayRenderer {\n private var loadingTiles = AtomicSet<String>()\n\n public init(overlay: any CachingTileOverlay) {\n super.init(overlay: overlay)\n }\n\n public override func draw(_ mapRect: MKMapRect, zoomScale: MKZoomScale, in context: CGContext) {\n // Shift the type; our constructor ensures we can't get this wrong by accident though.\n guard let tileOverlay = overlay as? CachingTileOverlay else {\n fatalError("The overlay must implement MKCachingTileOverlay")\n }\n\n // (Snipped) Calculate the range of tiles the mapRect intersects\n\n // Loop over the tiles that intersect mapRect...\n for x in firstCol...lastCol {\n for y in firstRow...lastRow {\n // Create the tile overlay path\n let tilePath = MKTileOverlayPath(x: x, y: y, z: currentZoom, contentScaleFactor: self.contentScaleFactor)\n\n if let image = cachedTileImage(for: tilePath) {\n // (Snipped) Compute tile rect\n let drawRect = self.rect(for: tileRect)\n // If we have a cached image for this tile, just draw it!\n drawImage(image, in: drawRect, context: context)\n } else {\n // Miss; load the tile\n loadTileIfNeeded(for: tilePath, in: tileRect)\n }\n }\n }\n }\n\n func cachedTileImage(for path: MKTileOverlayPath) -> ImageType? {\n guard let overlay = self.overlay as? CachingTileOverlay else { return nil }\n if let data = overlay.cachedData(at: path) {\n return ImageType(data: data)\n }\n return nil\n }\n\n func loadTileIfNeeded(for path: MKTileOverlayPath, in tileMapRect: MKMapRect) {\n guard let overlay = self.overlay as? CachingTileOverlay else { return }\n\n // Create a unique key for the tile (MKTileOverlayPath is not hashable)\n // and use this to avoid duplicate requests.\n let tileKey = "\\(path.z)/\\(path.x)/\\(path.y)@\\(path.contentScaleFactor)"\n guard !loadingTiles.contains(tileKey) else { return }\n\n loadingTiles.insert(tileKey)\n\n overlay.loadTile(at: path) { [weak self] data, error in\n guard let self = self else { return }\n self.loadingTiles.remove(tileKey)\n\n // When the tile has loaded, schedule a redraw of the tile region.\n DispatchQueue.main.async {\n self.setNeedsDisplay(tileMapRect)\n }\n }\n }\n}\nIt worked!\nWell, almost...
\n
That was my first attempt at grabbing the cgImage property of a UIImage\nand slapping it onto the context.\nThe drawImage function ended up being rather annoying for both UIKit and AppKit.
// At the top of your file\n#if canImport(UIKit)\ntypealias ImageType = UIImage\n#elseif canImport(AppKit)\ntypealias ImageType = NSImage\n#endif\n\n// Later, inside the overlay renderer...\n\nfunc drawImage(_ image: ImageType, in rect: CGRect, context: CGContext) {\n#if canImport(UIKit)\n UIGraphicsPushContext(context)\n\n image.draw(in: rect)\n\n UIGraphicsPopContext()\n#elseif canImport(AppKit)\n let graphicsContext = NSGraphicsContext(cgContext: context, flipped: true)\n\n NSGraphicsContext.saveGraphicsState()\n NSGraphicsContext.current = graphicsContext\n image.draw(in: rect)\n NSGraphicsContext.restoreGraphicsState()\n#endif\n}\nNot very pretty (especially with the conditional compilation to support macOS), but it gets the job done.
\nOne more wart to acknowledge...this approach requires a bit of faith in URLCache being responsive.\nBut it got rid of the flicker, and I think that's the bigger win.
\n\n[!question] What about the snipped code?!
\nYeah, I skipped over a bunch of math to calculate some rectangles.\nIt wasn't very interesting, and this is a LONG post.\nYou can find the full code on GitHub.
\n
CachingTileOverlayAfter some minimal testing, it became clear that the default caching behavior\nwas not going to cut it.\nWe can't see the source code, but it looks like internally,\nApple either uses URLSession.shared or sets up a new session with caching behavior similar to URLCache.shared.\nThis, somewhat understandably, doesn't do much if any disk caching.\nBut map users expect data to be cached for snappy app relaunches!
I ended up setting up a cache like this:
\nlet cache = URLCache(memoryCapacity: 25 * 1024 * 1024, diskCapacity: 100 * 1024 * 1024)\nIt's not entirely clear when exactly the memory contents are flushed to disk, but this is a big improvemnet already.\nDon't forget to configure your URLSession to use the new cache!\nI set up the session as in instance variable that's configured during init.
self.urlSession = URLSession(configuration: configuration)\nNext, we need to actually create the request and load it in loadTile(at:result:).
public override func loadTile(at path: MKTileOverlayPath, result: @escaping (Data?, (any Error)?) -> Void) {\n let url = self.url(forTilePath: path)\n let request = URLRequest(url: url, cachePolicy: cachePolicy)\n\n if let response = cache.cachedResponse(for: request) {\n result(response.data, nil)\n return\n }\n\n urlSession.dataTask(with: request) { data, _, error in\n result(data, error)\n }.resume()\n}\nNothing super special here.\nBut it's worth noting I also made cachePolicy an instance variable for extra configuability.\nAnd that's pretty much all the interesting bits in the overlay.
`canReplaceMapContent`
\nIf you're implementing a basemap layer with this approach, make sure you set canReplaceMapContent!\nThis lets MapKit skip drawing all layers underneath yours.\nDon't do this if you're just adding a transparent overlay on top.
For a full implementation of an overlay,\ncheck out this one for Stadia Maps raster layers.
\nWith the zoom transition "flicker" solved for cases where the tile was already in the cache,\nI noticed there was another problem with MKTileOverlayRenderer.\nIt refuses to show tiles from anything but the current zoom level.\nThis causes a jarring effect when zooming in, as the map is erased and slowly redrawn\nas new (non-cached) tiles are loaded.
MapKit is the first framework I can recall seeing with this behavior.\nOther frameworks will just "overzoom" the existing tiles.\nI was able to overcome this, but admittedly it required quite a lot of hackery.\nThe first thing we need to change is our drawing method.\nIt needs a fallback case.
if let image = cachedTileImage(for: tilePath) {\n // If we have a cached image for this tile, just draw it!\n drawImage(image, in: drawRect, context: context)\n} else if let fallbackImage = fallbackTileImage(for: tilePath) {\n // If we have a fallback image, draw that instead to start.\n drawImage(fallbackImage, in: drawRect, context: context)\n\n // Then, load the tile from the cache (if necessary)\n loadTileIfNeeded(for: tilePath, in: tileRect)\n} else {\n // Total cache miss; load the tile\n loadTileIfNeeded(for: tilePath, in: tileRect)\n}\nNothing too surprising here.\nWe try to load a fallback image, and THEN kick off the tile fetch.\nThe majority of the logic lives in fallbackTileImage(for:):
/// Attempts to get a fallback tile image from a lower zoom level.\n///\n/// The idea is to try successively lower zoom levels until we find a tile we have cached,\n/// then use it until the real tile loads.\nfunc fallbackTileImage(for path: MKTileOverlayPath) -> ImageType? {\n var fallbackPath = path\n var d = 0\n while fallbackPath.z > 0 && d < 2 { // We'll go up to 2 levels higher\n d += 1\n fallbackPath = fallbackPath.parent\n\n if let image = cachedTileImage(for: fallbackPath) {\n let srcRect = cropRect(d: d, originalPath: path, imageSize: image.size)\n\n return image.cropped(to: srcRect)\n }\n }\n return nil\n}\nThis code looks for cached tiles up to 2 levels "higher up."\nIf it finds one, it returns that image to be temporarily rendered as a stand-in.\nThis method in turn relies on two more methods:\nan extension on MKTileOverlayPath to get the parent tile,\nand a cropRect function which returns a sub-rectangle of the fallback image\nwhich we want to display.
In digital maps, the map is subdivided into tiles.\nAt zoom level 0, the whole world is a single tile.\nEvery time you zoom in a level, each tile is subdivided into 4.\nThis property lets us use a previously loaded image from a lower zoom level as a stand-in.
\nThis took way too much trial and error to get right.\nFirst, we need to do some math to calculate which section of the cached image we should crop to and "overzoom."\nThen we need to actually crop the image, which is easier said than done.\nNeither UIImage nor NSImage provide a cropping API directly,\nso we need to drop down to CoreGraphics.
To make matters worse, AppKit and UIKit somewhat infamously use different coordinate systems,\nwith the origins in different spots.\nSo our cropping functions OR our rect calculation need to be aware of the difference.
\nThis code is not particularly interesting to be honest,\nbut here are links to the files on GitHub:
\ncropRect)\n\n[!question] What about zooming out?
\nI currently don't apply the same tricks when zooming out.\nAs you zeem out, MapKit still clears tiles rather than showing smaller versions of what it has already.\nThis is a trickier problem since, while each child has exactly one parent tile,\nwhen you go in reverse, the task is to load 4 tiles and stitch them together.\nPRs welcome if anyone wants to take a swing!
\n
Mapkit is full of surprises.\nWhile it works pretty well out of the box with a vanilla map style from Apple on a fast network,\nsomething as simple as adding raster overlays can be devilishly complicated.\nHere's to hoping that Apple eventually publishes the source code for MapKit.\nI would happily sobmit some PRs to improve it,\nincluding adding support for overlays in the SwiftUI API!
\nIn the meantime, I've published a Swift package\nwith the caching overlay and renderer outlined in this post.\nCheck it out on GitHub.
\n", "summary": "", "date_published": "2025-02-11T00:00:00-00:00", "image": "media/mapkit-flipped-tiles.png", "authors": [ { "name": "Ian Wagner", "url": "https://fosstodon.org/@ianthetechie", "avatar": "media/avi.jpeg" } ], "tags": [ "ios", "swift", "apple", "maps" ], "language": "en" } ] }