Re: [magnetometer] Provide API to access uncalibrated magnetometer values

Here's the synthesis I [promised] to deliver:

# Use cases

The Magnetometer specification documents [use cases and requirements]. Below is an evaluation of the use cases mentioned in the spec.

* There are [key use cases] for both (calibrated) magnetometer and uncalibrated magnetometer.
* For both the categories there exists native apps that make use of these capabilities.
* For uncalibrated magnetometer, there exists e.g. [various] [Metal Detector] apps, and a wide array of VR apps for Cardboard that utilize [Magnetic Input for Mobile VR]. Cardboard has [shipped over 10 million units] and as such Magnetic Input for VR can be consider a mainstream use case.
* Gesture recognition based on magnetic field is discussed in [Abracadabra], [Nenya], [MagGetz], and [MagiTact] papers. The [Magnetic Input for Mobile VR paper] states the VR use case can be implemented very reliably on (circa 2015) smartphones in contrast to more advanced gesture recognition techniques mentioned in other papers.

**Editor's conclusion: There are key use cases for both calibrated magnetometer and uncalibrated magnetometer, as well as various native apps that make use of both of these capabilities. This suggests we should consider uncalibrated magnetometer of similar importance to the existing (calibrated) magnetometer.**

# API design

Then, onwards to the API design discussion. Two proposals for the API shape were made:

## Separate constructors

Keep the current (calibrated) `Magnetometer`, and add a new `UncalibratedMagnetometer`. See the [proposed WebIDL].

The `Magnetometer` interface remains unchanged. For the newly added `UncalibratedMagnetometer` interface, the latest reading includes three entries whose keys are "x", "y", "z" and whose values contain [uncalibrated magnetic field] around the 3 different axes, and three additional entries whose keys are "xBias", "yBias", "zBias" and whose values contain the [hard iron distortion] correction around the 3 different axes.

Please note `Magnetometer.{x, y, z}` and `UncalibratedMagnetometer.{x, y, z}` values represent different concepts regardless of them sharing the same attribute names. As a thought experiment, consider the latter `UncalibratedMagnetometer.{a, b, c}`. We might consider renaming these attributes to make this clearer.

## Extend SensorOptions

Add an option to the `Magnetometer` constructor to turn it into an uncalibrated magnetometer. See the [proposed WebIDL for extending SensorOptions].

# API design: discussion

**The following technical details were shared in favour of separate constructors:**

* The API design should cater for varying magnetometer hardware built into devices. Separate constructors make it possible to expose the data from all three classes of magnetometer sensors shipping in devices, namely from magnetometer sensors that:
  * provide calibrated readings only
  * provide uncalibrated readings only, e.g. [Infineon 3D Magnetic Sensor]
  * provide both calibrated and uncalibrated readings

* Interfaces should clearly define model, operations and data that is provided by the implementation of the interface. If model, behavior or type of the data defined by the interface can be changed by construction parameter, it is a good design practice to split interface in favor of runtime variation. In this case, it is more obvious the meaning of `{x, y, z}` in each interface is different.

* Improves encapsulation. No need to dig into internals of the interface instance to understand what it is.

* Easier to manage different types of sensors in the future.

* Improves error handling and in our case, feature detection. If e.g. `UncalibratedMagnetometer` is not exposed on the window, then you know upfront it is not supported by the user agent.

* Works when a device has an uncalibrated magnetometer hardware only.

* Early web developer feedback received indicate developers found the options confusing.

* Consistent API shape. Currently all concrete sensors use the standard SensorOptions without sensor type-specific extensions. Not obvious to a web developer why the magnetometer should diverge from the otherwise consistent API shape.

**The arguments in favour of extending SensorOptions:**

* We've designed the Generic Sensor API around the idea of a 1:1 mapping between sensor type and WebIDL interface. Here, both of these options are actually variation of the same sensor. So from that perspective, it would make sense to treat them as the same interface.

* we're trying to be consistant across a complex landscape

* The right question to ask would be whether either API designs help surface useful information to developers, in a way that lowers cognitive load, makes them understand the overall system better, and thus be more effective. Or does it instead saw confusion.

* When we reason in terms of use cases, we should also reason in terms of how common those use cases are. Does it make sense to turn an API that's designed to help build experimental VR features into a full blown global variable, on par with orientation sensors or geolocation?

* One of the key raison d'être of the Generic Sensor API is to expose a coherent and consistent API for sensors and to help developers knowingly pick the right sensor for their particular use case. This implies having an understanding of the way sensors actually work. [...] So I don't think we should we really have the conversation about which API works better, but instead have the conversation about whether is it important/useful for developers themselves to understand the underlying HW structure when they want to do advanced stuff like this or not.

# Emerging consensus

Later in the thread, there was a proposal from @kenchris: https://github.com/w3c/magnetometer/pull/21#issuecomment-300753160

> to rename the current `Magnetometer` to `GeomagneticFieldSensor` and the proposed `UncalibratedMagnetometer` to `Magnetometer`.

After this proposal we started to see consensus emerge, and all participants seemed to agree on the separate constructors as the way forward, but had different ideas on how these two interfaces should be named:

@tobie: https://github.com/w3c/magnetometer/pull/21#issuecomment-300754259

>Yeah. That seems sort of extreme, tbh, and for the case I'd argue it favors technical purity of developer experience. But I might be convinced otherwise.

@rwaldron: https://github.com/w3c/magnetometer/pull/21#issuecomment-300909993

>I could get behind this. I've made no secret that I utterly despise the use use of "Sensor" as some kind of class naming suffix, and would definitely prefer GeomagneticField.

@alexshalamov: https://github.com/w3c/magnetometer/pull/21#issuecomment-300777720

>I would propose to keep Magnetometer as it is now and add separate interface for UncalibratedMagnetometer. Later, we can add CompassSensor that would provide heading.

**Editor's conclusion: Consensus on the API design emerged, exact naming of the interfaces remains an issue. In the interest of focusing the energy of the participants on more burning issues than naming things, the editor merged the PR inviting further feedback regarding naming of the interfaces to be provided in issue #16.**

[promised]: https://github.com/w3c/magnetometer/pull/21#issuecomment-300727915
[use cases and requirements]: https://w3c.github.io/magnetometer/#usecases-and-requirements
[key use cases]: https://github.com/w3c/magnetometer/issues/16#issuecomment-301775614
[various]: https://itunes.apple.com/us/app/metal-detector-free/id333259405?mt=8
[Metal Detector]: https://itunes.apple.com/us/app/metal-detector/id409682366?mt=8
[Magnetic Input for Mobile VR]: http://smus.com/magnetic-input-mobile-vr/
[shipped over 10 million units]: https://www.theverge.com/2017/2/28/14767902/google-cardboard-10-million-shipped-vr-ar-apps
[Abracadabra]: http://www.chrisharrison.net/index.php/Research/Abracadabra
[Nenya]: http://dl.acm.org/citation.cfm?id=1979238
[MagGetz]: http://dl.acm.org/citation.cfm?id=2501991
[MagiTact]: http://dl.acm.org/citation.cfm?id=1720048
[Magnetic Input for Mobile VR paper]: http://smus.com/magnetic-input-mobile-vr/mimvr-iswc-2015.pdf

[Infineon 3D Magnetic Sensor]: http://www.mouser.com/ds/2/196/Infineon-TLV493D-A1B6-DS-v01_00-EN-890494.pdf
[proposed WebIDL]: https://w3c.github.io/magnetometer/#api

[uncalibrated magnetic field]: https://w3c.github.io/magnetometer/#uncalibrated-magnetic-field
[hard iron distortion]: https://w3c.github.io/magnetometer/#hard-iron-distortion

[proposed WebIDL for extending SensorOptions]: https://github.com/w3c/magnetometer/issues/16#issuecomment-259090628

-- 
GitHub Notification of comment by anssiko
Please view or discuss this issue at https://github.com/w3c/magnetometer/issues/16#issuecomment-302066759 using your GitHub account

Received on Wednesday, 17 May 2017 11:51:16 UTC