Skip to content

Maps

This section contains SYMapView manipulations and offline maps management using SYMapLoader class.

Related topics:

  • Adding SYMapView to iOS application is covered in Getting Started.
  • Showing current location on the map is covered in Navigation.

Map Handling

SYMapView.camera provides an interface to get/set the visible part of the map. Key attributes of SYMapCamera are geoCenter (geographical center), zoom (zoom level), tilt, rotation, boundingBox.

As an example, try showing the location of Sygic headquarters with street level zoom by adding these adjustments:

let mapView = SYMapView(frame: view.bounds)
mapView.camera.zoom = 17
mapView.camera.tilt = 0
mapView.camera.geoCenter = SYGeoCoordinate(latitude: 48.145810, longitude: 17.126420)

Zoom Level

Zoom level determines how "close" the map view is to the surface of Earth. Higher zoom levels give a closer view. Zoom 1 is the view on Earth, zoom 10 is approximately view on city, 15 on street, etc.

Rotation

The rotation determines which cardinal direction corresponds with which screen direction of the SYMapView. The valid range is from 0 to 360 degrees. The default value of 0 orients the map so that true north is toward the top of the view. The following code shows how to set the orientation to south-up:

mapView.camera.rotation = 180

Tilt

The tilt value represents the angle at which the map is viewed. You can set tilt using SYMapView.camera.tilt. Value of 0 provides a top-down two-dimensional view of the map. Note that the valid tilt range depends on the current zoom level, the map will apply the closest possible value from the valid range.

// set tilt for 2D to 0, for 3D to 60
let tiltFor2D: SYAngle = 0
let tiltFor3D: SYAngle = 60

// ...
mapView.camera.tilt = self.tiltFor2D
// ...

2D tilt  3D tilt

FPS Limiter

In order to save battery, SYMapView.setFpsLimitMode method allows you to set the maximum FPS performance of your App.

There are 2 modes available:

  • SYFpsLimitModePerformance - Always try to run at maximum FPS.
  • SYFpsLimitModeBalanced - Try to achieve smooth camera movement with minimum performance requirements.
mapView.setFpsLimitMode(.balanced, withFpsLimit: 15.0)

Handling map rendering

Another way to save battery is to turn map rendering off. This can be useful when the map is fully covered by another view (e.g. menu).

Remember to turn it back on when the map is visible again.

mapView.renderEnabled = false

Animations

The SYMapView supports the following animation settings to be used while changing properties, defined by the SYAnimation:

rotateView

  • angle - Camera rotation offset in degrees.
  • duration - Animation duration.
  • curve - Animation curve.
  • completion - Animation completion block.
mapView.camera.rotateView(90.0, withDuration: 1.0, curve: .decelerate, completion: nil)

dragView

  • drag - Camera move offset in screen points.
  • duration - Animation duration.
  • curve - Animation curve.
  • completion - Animation completion block.
mapView.camera.dragView(CGPoint(x: 50.0, y: 100.0), withDuration: 1.0, curve: .decelerate, completion: nil)

dragViewFrom

  • from - Screen from point.
  • to - Screen to point.
  • duration - Animation duration.
  • curve - Animation curve.
  • completion - Animation completion block.
mapView.camera.dragView(from: CGPoint(x: 0.0, y: 0.0), to: CGPoint(x: 50.0, y: 50.0), withDuration: 1.0, curve: .linear, completion: nil)

zoomView

  • zoom - Zoom scale,
  • center - Screen point to zoom at. Usually represents center of pinch gesture touches. Ignored if SYMapView.cameraMovementMode is not SYCameraMovementFree,
  • duration - Animation duration,
  • curve - Animation curve,
  • completion - Animation completion block.
mapView.camera.zoomView(2.0, at: CGPoint(x: 250.0, y: 250.0), withDuration: 2.0, curve: .accelerate, completion: nil)

animate

  • animations - Animation block containing properties changes (animatable properties are geoCenter, transformCenter, rotation, tilt, and zoom),
  • duration - Animation duration,
  • curve - Animation curve,
  • completion - Animation completion block,
mapView.camera.animate({
    mapView.camera.tilt = 20.0
    mapView.camera.zoom = 11
    mapView.camera.rotation = 180.0
    mapView.camera.geoCenter = SYGeoCoordinate(latitude: 48.147, longitude: 17.101878)
}, withDuration: 1.0, curve: .decelerate, completion: nil)

Here are the available SYMapAnimationCurve types:

  • SYMapAnimationCurveLinear ( Swift .linear) - A linear animation curve causes an animation to occur evenly over its duration.
  • SYMapAnimationCurveAccelerate ( Swift .accelerate) - This curve causes the animation to accelerate.
  • SYMapAnimationCurveDecelerate ( Swift .decelerate) - This curve causes the animation to slow down.
  • SYMapAnimationCurveAccelerateDecelerate ( Swift .accelerateDecelerate) - This curve causes the animation to accelerate first and decelerate at the end.
  • SYMapAnimationCurveBounce ( Swift .bounce) - This curve will toggle the animation to bounce.

Screen Points to Coordinates

Conversion of screen points to geographical coordinates and vice versa is provided by SYMapView methods: geoCoordinates(fromScreenPoints:), screenPoints(from:).

let point = NSValue(cgPoint: CGPoint(x: 100, y: 200))
let coordinate = mapView.geoCoordinates(fromScreenPoints: [point])[0]
print("coordinate: \(coordinate.latitude), \(coordinate.longitude)")

Map Skins

Specific map skins are available to offer your application users a choice among different kinds of map appearance. Currently we support day and night themes alongside with car and pedestrian navigation types. You can combine your skin as theme + navigation type.

// To get available skins:
let activeSkins = mapView.availableSkins() 
// returns ["browse", "car", "car_custom", "car_no_signal", "day", "default", "low_performance", "navigation",
// "night", "pedestrian", "pedestrian_no_signal", "realview", "scout"]

// For example, to set a night theme for car navigation type:
mapView.activeSkins = ["night", "car"]

Day skin & Night skin

Gestures

The SYMapView class responds to a number of predefined touch gestures. The default behavior of the map for each gesture type may be used as-is, supplemented, or replaced entirely.

To disable automatic gesture handling, set SYMapView.mapInteractionEnabled property to false.

The following table is a summary of the available gestures and their default behavior.

Gesture Description Following gestures
Rotate Rotate: Two-finger press, simultaneously orbit both fingers around the center point, lift Pinch, Spread, Move
Zoom out Pinch: Two-finger press, move inwards, lift Spread, Rotate, Move
Zoom in Spread: Two-finger press, move outwards, lift
Move Swipe: One-finger press, move, lift/don't lift
Tilt Tilt: Two fingers press, move up (increase the tilt angle) or move down (decrease the tilt angle)
Short touch Short touch: One-finger press, lift

Map Objects

The Sygic Maps SDK allows customization and extensibility by adding variety of objects to a map view. The types of available objects include map markers, routes, polylines, circles. To see full list of objects available, check SYMapObject API reference. Some objects are described in more detail below.

The SYMapObject class provides a generic base class from which most of the specialized map object types inherit. The following is a list of important properties and methods in SYMapObject.

  • type - contains the type of the map object, such as marker, polyline, circle, route, or other.
  • zIndex - determines the objects stacking order, which controls how the object is displayed on the map relative to other objects that may overlap it. Objects with the highest value are placed at the top of the view.
  • visible - determines whether or not the object is drawn on the map view.

Info

In order to display the map object on SYMapView, call add(_:) in Swift or addMapObject: in Objective-C.

SYMapMarker

Displays an image at a fixed geographical position on the map. Provides adjustable image anchor, visible zoom levels, clickable area (see class reference).

Assuming we've already added an image with name "your_image_resource" to our project (this way), the marker can be added as follows:

let marker = SYMapMarker(
    coordinate: SYGeoCoordinate(latitude: 48.145810, longitude: 17.126420),
    image: UIImage(named: "your_image_resource")!
)
mapView.add(marker)

Marker on the map

SYMapCircle

Draws a circle on the map at a fixed geographical location. Color, radius, line color, and other parameters are adjustable (see class reference).

let circle = SYMapCircle(geoCenter: SYGeoCoordinate(latitude: 48.145810, longitude: 17.126420), radius: 40)
circle.fillColor = UIColor(hue: 236, saturation: 27, brightness: 46, alpha: 0.5)
mapView.add(circle)

Circle on the map

SYMapPolyline

Draws one or more connected line segments on the map. The segment vertices are specified by a series of SYGeoCoordinates. The visual appearance of the polyline can be customized (see class reference).

let polyline = SYMapPolyline(coordinates: [
    SYGeoCoordinate(latitude: 48.1418807, longitude: 17.099226),
    SYGeoCoordinate(latitude: 48.1551798, longitude: 17.1251751),
    SYGeoCoordinate(latitude: 48.1458952, longitude: 17.1246556)
])
mapView.add(polyline)

Polyline on the map

Interaction

Map object selection can be detected in 2 ways:

  1. listening to SYMapViewDelegate.mapView(_:didSelect:), SYMapView notifies its delegate any time it recognizes a tap gesture
  2. calling SYMapView.objects(at point:withCompletion:)

Both approaches deliver an array of map objects hit by the tap gesture. Each object can be SYViewObject or its subclass.

Info

SYViewObject instances can be categorized this way:

  • object.baseType == .screen - it's the map itself, object.coordinate contains a geographical coordinate matching the point of tap;
  • object.baseType == .map - it's a map object represented by a subclass of SYMapObject, may be SYMapMarker, SYMapRoute, SYMapRouteLabel;
  • object.baseType == .proxy - it's a place of interest represented by a subclass of SYProxyObject, may be SYProxyPlace, SYProxyCity, SYProxyIncident, use SYProxyObjectsManager to retrieve the object details.

Example - select a map object

Assuming we have a project set up similarly as in Getting Started, and added 2 images: "marker1_200x200", "marker2_200x200" (this way), modify ViewController as follows (recognized object is written to log "didSelectObjects:").

func setupMapView() {
    let mapView = SYMapView(frame: view.bounds)
    mapView.camera.zoom = 17
    mapView.camera.tilt = 0
    mapView.camera.geoCenter = SYGeoCoordinate(latitude: 48.145810, longitude: 17.126420)
    mapView.delegate = self

    let marker1 = SYMapMarker(
        coordinate: SYGeoCoordinate(latitude: 48.1455, longitude: 17.1262),
        image: UIImage(named: "marker1_200x200")!,
        payload: "🔥" as NSString // special symbol is noticeable in log
    )
    let marker2 = SYMapMarker(
        coordinate: SYGeoCoordinate(latitude: 48.1454, longitude: 17.1266),
        image: UIImage(named: "marker2_200x200")!,
        payload: "💧" as NSString // special symbol is noticeable in log
    )

    mapView.add([marker1, marker2])

    // ...
}

// implement SYMapViewDelegate
extension ViewController: SYMapViewDelegate {
    func mapView(_ mapView: SYMapView, didSelect objects: [SYViewObject]) {

        let summary = objects.map {
            if let payload = $0.payload as? String {
                return payload
            } else if $0.baseType == .screen {
                return "map"
            } else {
                return String(describing: type(of: $0))
            }
        }.joined(separator: ", ")

        // result will appear in log
        print("didSelectObjects: \(summary)")
    }
}
// declare protocol conformance
@interface ViewController() <SYMapViewDelegate>
@end

// improve setting up map view
- (void)setupMapView {
    SYMapView *mapView = [[SYMapView alloc] initWithFrame:self.view.bounds];
    mapView.camera.zoom = 17;
    mapView.camera.tilt = 0;
    mapView.camera.geoCenter = [[SYGeoCoordinate alloc] initWithLatitude:48.145810 longitude:17.126420];
    mapView.delegate = self;

    SYGeoCoordinate* geo1 = [[SYGeoCoordinate alloc] initWithLatitude:48.1455 longitude:17.1262];
    SYMapMarker *marker1 = [[SYMapMarker alloc] initWithCoordinate:geo1
                                                             image:[UIImage imageNamed:@"marker1_200x200"]
                                                           payload:@"🔥"];
    SYGeoCoordinate* geo2 = [[SYGeoCoordinate alloc] initWithLatitude:48.1454 longitude:17.1266];
    SYMapMarker *marker2 = [[SYMapMarker alloc] initWithCoordinate:geo2
                                                             image:[UIImage imageNamed:@"marker2_200x200"]
                                                           payload:@"💧"];

    [mapView addMapObjects:@[marker1, marker2]];

    // ...
}

// implement the delegate method
- (void)mapView:(SYMapView *)mapView didSelectObjects:(NSArray<SYViewObject *> *)objects {

    NSMutableArray *descriptions = [[NSMutableArray alloc] init];
    for (SYViewObject *object in objects)
    {
        if ([(NSObject *)object.payload isKindOfClass:[NSString class]])
        {
            [descriptions addObject:object.payload];
        }
        else if (object.baseType == SYViewObjectTypeScreen)
        {
            [descriptions addObject:@"map"];
        }
        else
        {
            [descriptions addObject:NSStringFromClass([object class])];
        }
    }

    // result will appear in log
    NSLog(@"didSelectObjects: %@", [descriptions componentsJoinedByString:@", "]);
}

Offline Maps

Sygic Maps SDK for iOS is able to pre-load map data, allowing the use of maps, search, routing, and other features without an active data connection. Interfaces involved in providing offline maps functionality include SYMapLoader, SYMapLoaderDelegate and SYCountryDetails.

Switch online/offline

By default, Sygic Maps SDK initializes with offline maps mode. Online maps can be enabled/disabled by SYOnlineSession methods: setOnlineMapsEnabledWithCompletion(_:), setOnlineMapsDisabledWithCompletion(_:).

SYOnlineSession.shared().setOnlineMapsEnabledWithCompletion { _ in }

Also online maps can be enabled during SDK initialization by adding a key to the configuration: "MapReaderSettings": ["startup_online_maps_enabled": true], this approach is demonstrated in Getting Started.

SYMapLoader

SYMapLoader identifies a country by it's ISO code (usually, a two-letter string).

Info

Use ISO codes received directly from SYMapLoader, it's not guaranteed that SYMapLoader always operates with ISO 3166 alpha-2 standard.

SYMapLoader API provides such operations with map data stored on the device:

  • getAvailableCountries - returns ISO codes for:
    • SYMapLoaderMapFilterAll - all countries (already downloaded + available for download)
    • SYMapLoaderMapFilterInstalled - only downloaded countries
  • getCountryDetails - get details by a country ISO code
  • getRegionDetails - get details by a region ISO code (some big countries are be split into regions)
  • installMap - download map data for a country ISO code or a region ISO code
  • uninstallMap - remove map data, associated with the specified ISO code, from the device
  • getMapStatus - not installed, installed, loaded, etc.
  • loadMap - after map is downloaded, it must be loaded to make it available for browsing, searching, routing, etc.
  • unloadMap
  • checkForUpdates - check if the new map data is available for the specified ISO code
  • updateMap - download new map data for the specified ISO code
  • detectCurrentCountry - 2 modes:
    • detect current county ISO code automatically by the current IP-address
    • get county ISO code from the region ISO code
  • resumePendingInstallations - resume downloads which were in progress when the app was terminated, if any

Example - List all available countries

class Example: NSObject, SYMapLoaderDelegate {
    var countries = [SYCountryDetails]()

    func demoGetCountries() {
        let mapLoader = SYMapLoader()

        // get all countries
        mapLoader.getAvailableCountries(.all) { (isoCodes: [String], result: SYMapLoaderResult) in
            guard result == .success else {
                print("Error getAvailableCountries: \(result.rawValue)")
                return
            }

            var remainingCount = isoCodes.count
            isoCodes.forEach { (iso: String) in

                // get country details
                mapLoader.getCountryDetails(iso, installedOnly: false) { (result: SYMapLoaderResult, details: SYCountryDetails?) in
                    if let details = details {
                        self.countries.append(details)
                    }
                    else {
                        print("Error getCountryDetails '\(iso)' result=\(result.rawValue)")
                    }

                    remainingCount -= 1
                    if remainingCount == 0 {
                        // all countries are processed, data is ready
                        self.printCountries()
                    }
                }
            }
        }
    }

    func printCountries() {
        countries.forEach { (country: SYCountryDetails) in
            let continent = country.continentName
            let name = country.name
            let size = country.totalSize
            print("\(continent), '\(country.iso)' \(name) \(size) bytes")
        }
    }
}

Example - Install a map

func demoInstallCountry(_ country: SYCountryDetails) {
    let mapLoader = SYMapLoader()
    mapLoader.delegate = self // listen to downloading progress

    mapLoader.installMap(country.iso) { (iso: String, result: SYMapLoaderResult) in
        guard result == .success else {
            print("Error installMap \(iso): \(result.rawValue)")
            return
        }

        // load the map to enable rendering, searching, routing
        mapLoader.loadMap(iso) { (result: SYMapLoaderResult) in
            print("loadMap '\(iso)' result=\(result.rawValue)")
        }
    }
}

func mapLoader(_ maploader: SYMapLoader, didUpdate progress: SYMapInstallProgress, forMap map: String) {
    print("download '\(map)' \(progress.downloadedSize * 100 / progress.totalSize)%")
}

The resumePendingInstallations method checks if some map downloads were interrupted by application exit, and resumes them. If there are no pending installations, the method will finish with completion resumedInstalls = 0, resumedUpdates = 0.

func demoResumePendingInstallations() {
    let mapLoader = SYMapLoader()
    mapLoader.delegate = self
    mapLoader.resumePendingInstallations { (
      installs: [SYMapLoaderResumedTaskDetails],
      updates: [SYMapLoaderResumedTaskDetails],
      result: SYMapLoaderResult
  ) in
      print("resumePendingInstallations -> \(result.rawValue)")
      print("resumed installs: \(installs.count), resumed updates: \(updates.count)")
  }
}

func mapLoader(_ maploader: SYMapLoader, didFinishResumedInstallWith result: SYMapLoaderResult, forMap map: String) {
    print("didFinishResumedInstallWith result=\(result.rawValue) map=\(map)")
}

Optional information about SYMapLoader operations can be received by implementing such methods of SYMapLoaderDelegate:

  • (void)mapLoader:(nonnull SYMapLoader\*)maploader didFinishResumedInstallWithResult:(SYMapLoaderResult)result forMap:(nonnull SYCountryIso\*)map;
  • (void)mapLoader:(nonnull SYMapLoader\*)maploader didUpdateMapInstallProgress:(nonnull SYMapInstallProgress\*)progress forMap:(nonnull SYCountryIso\*)map;

Note: these methods will be called on delegates of all SYMapLoader instances, even if an operation was requested only on one SYMapLoader.

SYMapLoader instances can be created only when SYContext is already initialized.

When Sygic Maps SDK is initialized, all installed maps are loaded automatically, but when the new map is installed, SYMapLoader.loadMap must be called before the map data can be used (for rendering, search, etc.).

All asynchronous operations return SYTask object, it can be used to cancel the operation. If the operation is cancelled, it's completion will be called with result SYMapLoaderResultCancelled. However, it's possible that the operation has already finished internally at the moment of the cancellation request, in this case the completion block will be called with a regular non-cancelled result.