Calibrate course based on heading changes

[1ec5]

We currently use only the course from GPS location updates, ignoring the heading from the magnetometer, because the phone doesn’t necessarily face the same direction that the user is headed. For example, it could be sitting in a cupholder rotated to the side to face the driver, in which case the heading is constantly offset.

Unfortunately, the course is just as noisy as any other component in a GPS location update, typically noisier than headings. The map can end up rotating back and forth even as the user travels in a straight line, potentially wasting energy as the map performs unnecessary symbol placement (see mapbox/mapbox-gl-native#9031).

We should ignore changes in course that aren’t accompanied by changes in heading. The assumption is that any real change in course would require the phone to face a different direction, whether it’s in a car cupholder or in a pedestrian’s hand. (However, #2215 would switch to headings for walking directions, ignoring the course outright.)

RouteController currently passes the course to MBNavigator verbatim and never uses the heading:

mapbox-navigation-ios/MapboxCoreNavigation/RouteController.swift

Line 190 in 05c1f9f

locations.forEach { navigator.updateLocation(for: MBFixLocation($0)) }

mapbox-navigation-ios/MapboxCoreNavigation/MBNavigator.swift

Line 10 in 05c1f9f

bearing: location.course >= 0 ? location.course as NSNumber : nil,

LegacyRouteController only disqualifies a course if the device doesn’t support course readings at all (such as in an iPhone simulator). It doesn’t even use the heading for the so-called heading-based turn completion heuristic:

mapbox-navigation-ios/MapboxCoreNavigation/LegacyRouteController.swift

Lines 100 to 107 in 05c1f9f

	// If there is no snapped location, and the rawLocation course is unqualified, use the user's heading as long as it is accurate.
	if snappedLocation == nil,
	let heading = heading,
	let loc = rawLocation,
	!loc.course.isQualified,
	heading.trueHeading.isQualified {
	return CLLocation(coordinate: loc.coordinate, altitude: loc.altitude, horizontalAccuracy: loc.horizontalAccuracy, verticalAccuracy: loc.verticalAccuracy, course: heading.trueHeading, speed: loc.speed, timestamp: loc.timestamp)
	}

mapbox-navigation-ios/MapboxCoreNavigation/LegacyRouteController.swift

Lines 457 to 460 in 05c1f9f

	} else if location.course.isQualified {
	let userHeadingNormalized = location.course.wrap(min: 0, max: 360)
	courseMatchesManeuverFinalHeading = finalHeadingNormalized.difference(from: userHeadingNormalized) <= RouteControllerMaximumAllowedDegreeOffsetForTurnCompletion
	}

mapbox-navigation-ios/MapboxCoreNavigation/CLLocationDirection.swift

Lines 16 to 18 in dc9f1e9

	var isQualified: Bool {
	return self > -1
	}

NavigationMapView uses the course verbatim and doesn’t use the heading for anything, though #2215 would switch to heading for walking directions:

mapbox-navigation-ios/MapboxNavigation/NavigationMapView.swift

Line 344 in 05c1f9f

let newCamera = camera ?? MGLMapCamera(lookingAtCenter: location.coordinate, altitude: altitude, pitch: 45, heading: location.course)

/ref #2046
/cc @mapbox/navigation-ios @avi-c @d-prukop @mapbox/navnative

[1ec5]

@Aurora-Boreal pointed out this paper, which is focused on Android APIs but could provide some insights on the right heuristics to use when using both course and heading.

[a-kosak-mbx]

We currently use only the course from GPS location updates, ignoring the heading from the magnetometer, because the phone doesn’t necessarily face the same direction that the user is headed.

We are currently working on algorithm that couples car and phone coordinate systems even if they are relatevely floating. If phone is in cupholder it's easy enough to translate magnetometer data into car coordinate systems and fuse it with gyroscopes for higher stability and reliablility.