`Position.heading` is mis-named

[cbatson]

🐛 Bug Report

The property heading of Position is mis-named. It is actually the course, which can be seen clearly on this line of LocationMapper.m for iOS.

This is rather unfortunate, as heading and course are distinct concepts, and having it mis-named is confusing:

In navigation, the course of a watercraft or aircraft is the cardinal direction in which the craft is to be steered. The course is to be distinguished from the heading, which is the direction where the watercraft's bow or the aircraft's nose is pointed.

In the context of a device, "heading" refers to the direction the device is pointing and is typically provided via a magnetometer. However, "course" refers to the direction the device is traveling and is typically provided via GPS.

Expected behavior

A course should be called "course."

Reproduction steps

None necessary.

Configuration

Version: 1.x

Platform:

• 📱 iOS
• 🤖 Android

[CorjanM]

Having the same issue! Fundamentally different concepts. Passing Postion.heading to other methods expecting a heading throw exceptions stating that heading must have a value of 360 <= heading <= 0. The current implementation of Position.heading can be < 0 which is not a valid value for an actual heading.

[cbatson]

@CorjanM Your issue is a bit different, as a negative value is valid for neither heading nor course. If you're seeing the negative value on iOS, check the documentation for CLLocation.course for why:

A negative value indicates that the course information is invalid.

[mvanbeusekom]

Hi @cbatson,

Thank you for raising this issue. Of course you are 100% correct and we completely missed this detail during the implementation.

However if we would rename the property now, we'd break all implementations of current users. Our suggestion for now would be to update the documentation of the heading property and clearly explain the unfortunate naming issue and the actual value.

In the near future we are planning a complete refactor of this plugin with the idea to expose the native APIs to consumers, in this case we'd use the name course for iOS, bearing for Android and heading on Windows. Which would completely solve the problem.

I will leave this issue open, so we can track the progress of the documentation update.

[cbatson]

Thank you so much @mvanbeusekom, that's a very reasonable approach.