Upgrade to Mapbox GL–based Mapbox Static API

[1ec5]

This PR adds support for the Mapbox GL–powered Mapbox Static API alongside the existing support for the classic Static API. In the process, the existing Swift files have been split up to be more manageable.

The Snapshot class and Overlay subclasses are largely untouched, a consequence of the fact that the new API tries to mimic the classic API’s overlay options. SnapshotOptions has been renamed ClassicSnapshotOptions. This PR takes advantage of the SnapshotOptionsProtocol protocol – meant to provide a common interface for ClassicSnapshotOptions and MarkerOptions – to add another conforming protocol, named SnapshotOptions, that exposes options for working with the new API.

SnapshotOptions is a bit more complex than ClassicSnapshotOptions. Instead of accepting separate centerCoordinate and zoomLevel options, it takes a single camera option of type SnapshotCamera. SnapshotCamera defines both a conventional zoomLevel property and an altitude property (for compatibility with the Mapbox iOS and macOS SDKs’ MGLMapCamera class); the developer can use either.

SnapshotCamera closely parallels the Mapbox iOS and macOS SDKs’ MGLMapCamera class, in much the same way that MapKit’s MKMapSnapshotOptions and MKMapView classes both have camera properties of type MKMapCamera. This library can’t simply reuse MGLMapCamera because it lives in the Mapbox iOS and macOS SDKs, which are separate frameworks. (Perhaps we should move this entire library’s functionality into those SDKs to fix mapbox/mapbox-gl-native#1701?)

GeoJSON(object:) is once again throwable. #23 made it throwable, but #28 had to make it failable instead due to a type mismatch when bridging to Objective-C. As of Swift 3, SE-0112 resolved the type mismatch, so the initializer can once again be throwable without breaking Objective-C support.

The classic snapshot tests have been rewritten to replace clever but untested URL parsing code in tests with much more straightforward string literals that can be verified easily. Now, if you want to know the URL that a particular ClassicSnapshotOptions produces, you can copy the stub’s isPath() call’s argument into a browser instead of having to run the test code. Test fixture images have been added, and the tests verify that an NSImage or UIImage can be created from each test fixture image produced by Snapshot.

To recap:

• [x] Reorganize Swift files
• [x] Rename SnapshotOptions to ClassicSnapshotOptions
• [x] Implement new SnapshotOptions based on GL-based API
• [x] Make GeoJSON initializer throwable
• [x] Make unit test stubs more literal
• [x] Make unit tests rely on image test fixtures
• [x] Add altitude (distance) as a camera option alongside zoom level, for consistency with MGLMapCamera
• [x] Add GL snapshot tests
• [x] Update example applications
• [x] Update playgrounds and readme
• [x] Update documentation comments
• [x] Update readme screenshots once server-side rendering bugs are fixed

Fixes #9.

/cc @frederoni @bsudekum @incanus @friedbunny

[1ec5]

Test coverage is at 76.97%:

Most of the untested code is in convenience methods added for Objective-C compatibility.

[1ec5]

The server-side rendering issues have been fixed, so the remaining work is no longer blocked.

[quicklywilliam]

Huzzah!