![\"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" }, { "id": "https://ianwwagner.com//kwdc-24.html", "url": "https://ianwwagner.com//kwdc-24.html", "title": "KWDC 24", "content_html": "Yesterday I had the pleasure of attending KWDC 24,\nan Apple developer conference modeled after WWDC,\nbut for the Korean market.\nRegrettably, I only heard about it a few days prior\nthrough a friend at the Seoul iOS Meetup,\nso I wasn’t able to give a talk.
\nThe iOS meetup typically has 20-30 attendees.\nBut wow... the turnout at KWDC far exceeded my expectations.\nNearly 600 attendees showed up,\nand this is only its second year (I also didn’t hear about it last year;\nclearly I live under a rock)!\nThe staff were well organized and friendly,\nand the international participation was significantly better than I had expected.
\nSurprisingly, most of the (30+) event staff also spoke English very well (that’s a first for a Korean conference that I’ve been to).\nI think the organizers did an excellent job in not only attracting an international audience\n(one speaker flew in from Czechia!),\nbut also making them feel welcome.\nHats off to the organizing team for that!\nThis makes me really happy, and I hope this is a big step in raising the level of conferences here.
\nNot only did they have a mix of English and Korean talks,\nthey handled live translation much better than any other event I’ve seen.\nThey used a service called Flitto.\nApparently it’s a Korean company,\nand they were using some AI models to do the heavy lifting.\nIt had some hiccups to be sure,\nbut it did a surprisingly good job!\nThe main complaint I heard was that it would wait for half or 2/3 of a screenful of content, causing jumps that were hard to read.
\nThe speakers I talked with said they had to provide a script in advance,\nwhich we speculate were used to improve the quality of the translations\n(which were still live, even when the presenter went “off script”).\nThe model still failed to recognize technical terms on occasion,\nbut the hiccups were to be expected.\nOverall, the quality of the translation was excellent,\nand I think this will be the future of such events!\nI’ve been at half a dozen events where they give you a radio receiver\nand an earpiece, and it is never a great experience.\nEveryone I talked with said they liked the\ntext on screen approach was better too\n(especially since it was alongside the slides,\nwhich were honestly Apple quality at every single talk I saw!).
\n![\"View](\"media/IMG_8818.jpeg\")
My favorite talk was Pavel’s on “The Magic of SwiftUI Animations.”\nHe even walked up to the podium in a wizard robe 🧙\nI was blown away by the amount of effort that he put into the slides,\nand got a bunch of things to follow up on (like this video on shaders).\nTalking with him after, he said it was the culmination of around 4 years of effort.
\n![\"Pavel](\"media/IMG_8820.jpeg\")
Riana’s talk on Swift Testing\ngot me fired up to switch.\nI wanted to shout with excitement when I heard that Swift finally\nsupports parameterized tests in a native testing framework!\nAnd it’s open source,\nso I hope it will be improve faster than XCTest.\nWho knows; maybe it’ll even get property testing (like QuickCheck, Hypothesis, etc.)!
\nThe third talk that stuck out to me was Rudrank’s\ntalk on widgets.\nHe was a GREAT presenter, with a number of Korean expressions woven throughout,\nwhich the audience loved.\nI also liked how he cleverly wove the Rime of the Ancient Mariner throughout\nthe talk (the title was “Widgets, Widgets Everywhere, and not a Pixel to Spare”).\nMy biggest learning was in the weird differences in the mental model for updates:\nit’s all about the timeline!
\nNetworking at Korean conferences is typically a bit slow to be honest,\nas it is not normal in Korean culture to walk up to someone\nand start a conversation without much context.\nThis event also happened to be exceptional in a good way!
\nThe first big networking opportunity was lunch.\nBut there wasn't a very clear announcement of how lunch would work.\nEveryone was on their own, and the info was rather buried in some PDFs (which I didn’t get somehow)\nand Discord (which I had a hard time navigating).\nTogether with a Danish friend I met at the iOS meetup a few days prior,\nI suggested we wing it and just follow the crowd outside to see where we ended up,\nsince they were clearly better informed than us 🤣
\nWe ended up taking a few turns following a group in front of us,\nand eventually I asked if they would be cool with us crashing their party.\nWe ended up at a crowded Donkatsu buffet a few minutes later.\nThe two at our table were iOS engineers, one working at Hyundai AutoEver,\nand another at 오늘의집,\nand we had a great conversation over lunch!\n(They even bought us coffee after; so friendly!)
\nOne of them mentioned that we should check out the networking area in-between sessions, which I did later.\nIt was a bit hard to find, since it was in a narrow hall,\nafter you passed through a cafe on another floor.\nI think this could have been announced a bit better,\nsince not many people used it, but the conversations I had there were great!
\nAside: another cool thing that I haven’t seen done elsewhere is round-table Q&A.\nAlong with the session times, each speaker was available for Q&A around (literally)\nround tables near the networking zone.\nVery cool idea!
\nThe networking area had one room dedicated to local communities as well,\nincluding the Seoul iOS Meetup,\nthe Korean Swift Coding Club,\nand the AWS Korea User group.\nThe Swift Coding Club in particular was a super cool group.\nSeveral were students,\nand one was working on some apps related to EV charging.\nThis naturally lead to a conversation about the geocoding,\nmaps, and navigation SDKs I’ve been working on at Stadia Maps.\nIt was a good time!
\nFinally, there wasn’t a big after-party or anything,\nbut there was a small event at a bar organized for the speakers and sponsors.\nI didn’t speak, but they were fine letting me tag along.\nI ended up talking for well over an hour with Riana about everything from Swift\nto world cultures to under-representation of women in tech.\nAnd she 100% sold me on attending try! Swift\nin Tokyo next year.\nAnd Mark from RevenueCat,\nwho I also met at the iOS meetup prior,\ntaught me a bunch of things I didn’t know about the history of MacRuby\n(turns out he built the first BaseCamp app using RubyMotion back in the day!).
I ended up getting home at 1:30am for the second time this week.\nBut it was worth it!
\n", "summary": "", "date_published": "2024-10-26T00:00:00-00:00", "image": "media/IMG_8818.jpeg", "authors": [ { "name": "Ian Wagner", "url": "https://fosstodon.org/@ianthetechie", "avatar": "media/avi.jpeg" } ], "tags": [ "conferences", "AI", "translation", "apple", "swift" ], "language": "en" } ] }