磁力计

1. 简介

Magnetometer 扩展了 Generic Sensor API [GENERIC-SENSOR]， 以提供设备主磁力计传感器检测到的磁场信息。 磁力计传感器以 μT（微特斯拉）为单位，测量三个 物理轴（x、y、z）上的磁场。

本规范定义了两个新接口：

• Magnetometer 用于报告已校准磁场值，以及

• UncalibratedMagnetometer 用于报告未校准磁场值。

磁场是一种 会因电流、磁性材料或地球磁力产生的磁效应而对磁力计传感器 施加磁力的场；地球磁力归因于行星自转和地核中熔融 铁运动的共同作用。

硬铁 畸变由能够产生磁 场的物体造成， 例如被磁化的铁。

软铁 畸变会拉伸或扭曲 磁场，并且由 镍和铁等金属 造成。

已校准 磁场是应用了硬铁畸变和软铁 畸变 校正的磁场。

未校准 磁场是未应用硬铁 畸变 校正、但应用了软铁畸变校正的 磁场， 因此会报告由磁化物体在磁力计附近移动而引起的磁场 变化。

2. 示例

let sensor = new Magnetometer();
sensor.start();

sensor.onreading = () => {
    console.log("X 轴方向的磁场 " + sensor.x);
    console.log("Y 轴方向的磁场 " + sensor.y);
    console.log("Z 轴方向的磁场 " + sensor.z);
};

sensor.onerror = event => console.log(event.error.name, event.error.message);

3. 安全与隐私考虑

Magnetometer 提供有关磁场的信息，并且理论上可以暴露用户的位置。 例如，攻击向量可以是某个特定位置中预先磁化的表面，或者 建筑物造成的位置与恒定磁场扰动之间的映射。由于 地球磁场强度不均匀，另一种攻击向量可能是暴露或 验证用户的位置。例如，如果终端用户通过 VPN 连接，则可以将与 地理 IP 信息关联的磁场同真实位置处的磁力计读数进行比较， 从而判断用户是否正在使用 VPN。实现者应当意识到通过 磁场强度与 CPU 执行等其他方面之间的相关性发生侧信道泄漏的潜在风险； 在某些情况下，这可能泄漏关于其他标签页中使用的应用程序或访问过的网站的 信息。[MAGSPY]

未校准磁力计读数可能会受附近磁化物体的影响，例如首饰， 从而暴露可能被用于击键 监控的信息。

为缓解这些特定威胁，用户代理应 使用以下一种或两种缓解策略：

• 限制最大采样频率

• 降低传感器读数的准确度

这些缓解策略补充了 Generic Sensor API [GENERIC-SENSOR] 中定义的通用 缓解措施。

4. 权限策略集成

本规范利用由字符串 "magnetometer" 标识的策略控制特性， 该字符串定义于 [DEVICE-ORIENTATION]。

5. 模型

Magnetometer 传感器类型具有 以下关联数据：

扩展传感器接口

Magnetometer

传感器权限名称

"magnetometer"

传感器特性名称

"magnetometer"

权限撤销算法

以 "magnetometer" 调用通用传感器权限撤销 算法。

虚拟传感器类型

"magnetometer"

最新读数，对于其传感器类型为 Magnetometer 的 Sensor 而言，必须包含：

• 三个条目，其键为 "x"、"y"、"z"，并且其值包含相应轴上的磁场。

Uncalibrated Magnetometer 传感器类型具有 以下关联数据：

扩展传感器接口

UncalibratedMagnetometer

传感器权限名称

"magnetometer"

传感器特性名称

"magnetometer"

权限撤销算法

以 "magnetometer" 调用通用传感器权限 撤销算法。

虚拟传感器类型

"uncalibrated-magnetometer"

最新读数，对于其传感器类型为 Uncalibrated Magnetometer 的 Sensor 而言，必须包含：

• 三个条目，其键为 "x"、"y"、"z"，并且其值包含 3 个不同轴周围的未校准 磁场。

• 另外三个条目，其键为 "xBias"、"yBias"、"zBias"，并且其值包含 3 个不同轴周围的硬铁畸变 校正。

磁 场值的符号必须遵循 局部 坐标系中的右手约定（见下图）。

5.1. 参考坐标系

局部坐标系表示 Magnetometer 和 UncalibratedMagnetometer 读数的参考坐标系。 它可以是设备坐标系，也可以是屏幕坐标系。

6. API

6.1. Magnetometer 接口

[SecureContext,
  Exposed=Window]
interface Magnetometer : Sensor {
  constructor(optional MagnetometerSensorOptions sensorOptions = {});
  readonly attribute double? x;
  readonly attribute double? y;
  readonly attribute double? z;
};

enum MagnetometerLocalCoordinateSystem { "device", "screen" };

dictionary MagnetometerSensorOptions : SensorOptions {
  MagnetometerLocalCoordinateSystem referenceFrame = "device";
};

Magnetometer 支持的传感器选项 为 "frequency" 和 "referenceFrame"。

6.1.1. Magnetometer.x

x 属性在 Magnetometer 接口中表示 X 轴周围的磁场。 换言之，此属性返回以 this 和 "x" 为参数调用 从最新读数获取值的结果。

6.1.2. Magnetometer.y

y 属性在 Magnetometer 接口中表示 Y 轴周围的磁场。 换言之，此属性返回以 this 和 "y" 为参数调用 从最新读数获取值的结果。

6.1.3. Magnetometer.z

z 属性在 Magnetometer 接口中表示 Z 轴周围的磁场。 换言之，此属性返回以 this 和 "z" 为参数调用 从最新读数获取值的结果。

6.2. UncalibratedMagnetometer 接口

[SecureContext,
  Exposed=Window]
interface UncalibratedMagnetometer : Sensor {
  constructor(optional MagnetometerSensorOptions sensorOptions = {});
  readonly attribute double? x;
  readonly attribute double? y;
  readonly attribute double? z;
  readonly attribute double? xBias;
  readonly attribute double? yBias;
  readonly attribute double? zBias;
};

UncalibratedMagnetometer 支持的传感器选项 为 "frequency" 和 "referenceFrame"。

6.2.1. UncalibratedMagnetometer.x

x 属性在 UncalibratedMagnetometer 接口中表示 X 轴周围的未校准磁场。 换言之，此属性返回以 this 和 "x" 为参数调用 从最新读数获取值的结果。

6.2.2. UncalibratedMagnetometer.y

y 属性在 UncalibratedMagnetometer 接口中表示 Y 轴周围的未校准磁场。 换言之，此属性返回以 this 和 "y" 为参数调用 从最新读数获取值的结果。

6.2.3. UncalibratedMagnetometer.z

z 属性在 UncalibratedMagnetometer 接口中表示 Z 轴周围的未校准磁场。 换言之，此属性返回以 this 和 "z" 为参数调用 从最新读数获取值的结果。

6.2.4. UncalibratedMagnetometer.xBias

xBias 属性在 UncalibratedMagnetometer 接口中表示 X 轴周围的硬铁畸变校正。 换言之，此属性返回以 this 和 "xBias" 为参数调用 从最新读数获取值的结果。

6.2.5. UncalibratedMagnetometer.yBias

yBias 属性在 UncalibratedMagnetometer 接口中表示 Y 轴周围的硬铁畸变校正。 换言之，此属性返回以 this 和 "yBias" 为参数调用 从最新读数获取值的结果。

6.2.6. UncalibratedMagnetometer.zBias

zBias 属性在 UncalibratedMagnetometer 接口中表示 Z 轴周围的硬铁畸变校正。 换言之，此属性返回以 this 和 "zBias" 为参数调用 从最新读数获取值的结果。

7. 抽象操作

7.1. 构造一个 magnetometer 对象

8. 自动化

本节通过提供 Magnetometer 特定的虚拟传感器元数据， 扩展了 Generic Sensor API § 9 自动化。

8.1. Magnetometer 自动化

每类型虚拟传感器元数据映射 必须具有以下条目：

键

"magnetometer"

值

一个虚拟传感器元数据，其读数解析算法为 解析 XYZ 读数。

8.2. Uncalibrated Magnetometer 自动化

每类型虚拟传感器元数据映射 必须具有以下条目：

键

"uncalibrated-magnetometer"

值

一个虚拟传感器元数据，其读数解析算法为 未校准磁力计 读数解析算法。

8.2.1. Uncalibrated Magnetometer 读数解析算法

9. Magnetometer 传感器的局限性

本节为非规范性内容。

地球磁场的方向和大小会随位置变化，尤其会随纬度变化。例如， 大小在赤道附近最低，在两极附近最高。 某些硬铁干扰，即传感器附近存在永磁体（例如手机扬声器中的磁体）， 也会影响读数的准确度。 电子设备、笔记本电脑、电池等的存在也会造成软铁干扰。 移动电话中的飞行模式选项可能有助于降低电磁干扰。

除了上述磁场的空间变化之外， 太阳风或磁暴等基于时间的变化，也会扭曲地球的磁层或外部磁场。

10. 用例和需求

本节为非规范性内容。

磁力计可用于多种用例，例如：

• 传感器融合。磁力计的常见用例是传感器融合，以生成一个相对于地球平面静止的 绝对方向传感器 [MOTION-SENSORS]， 或者生成一个罗盘；后者基本上是前者再根据地理位置对磁偏角进行校正， 使其指向真北。罗盘航向的计算详见 § 11 使用 Magnetometer 得到罗盘航向。

• 虚拟现实和增强现实。磁力计可用于为 VR 外壳实现使用磁性按钮的输入 [VRBUTTON]。VR 和 AR 的头戴式跟踪系统可以使用磁力计数据来帮助校准陀螺仪读数，并将偏航读数 与磁北对齐。

• 手势识别。书写、签名和演奏乐器等各种交互也可以借助杆、笔或戒指等磁体来启用 [MAGITACT]。 用户使用磁体在设备周围的 3D 空间中做出粗略手势。磁体的移动会影响设备中集成的 罗盘传感器所感测到的磁场。 手势的时间模式可作为向移动设备发送不同交互命令的基础。缩放、翻页、 接听/拒接电话、点击项目 都是一些用例。

• 室内导航。导航系统可以使用移动设备上的磁力计数据 [MAGINDOORPOS] 来检测建筑物内部的磁场。若局部变化足够丰富，这些异常可用于自定位。室内导航的用例包括 例如近距离广告、商场或机场中的寻路，以及地理围栏。

• 金属检测。磁力计可由实用工具应用程序用于检测附近是否存在金属， 例如查找隐藏在物体内部的夹杂物。

11. 使用 Magnetometer 得到罗盘航向

本节为非规范性内容。

罗盘是一种会与地球磁极对齐的仪器，数百年来一直用于 导航。 地球的自转轴定义了我们用于地图参考的地理北极和南极。 事实证明，地理极和 磁极之间存在大约 11.5 度（约 1000 英里）的差异。 偏 角会应用到磁方向上，以校正这种情况。

如果设备始终与地球表面保持水平，则只使用地球磁场的 x 和 y 分量即可确定罗盘航向， 即与地球表面共面的方向。 要确定地理北（或真北）航向，应加上适当的偏角。

磁 偏角或 偏角，是水平面上磁北与真北之间的角度， 它取决于地球表面的位置，并随时间变化。 按惯例，当磁北位于真北以东时偏角为正，位于真北以西时为负。 你可以获取磁偏角的实时值，例如使用美国国家海洋和大气管理局 （NOAA）提供的磁偏角计算器。

磁北按如下方式计算：

let sensor = new Magnetometer();
sensor.start();
let heading = Math.atan2(sensor.y, sensor.x) * (180 / Math.PI);
console.log('以度为单位的航向：' + heading);

给定纬度和经度处的地理北可按如下方式计算：

// 获取纬度和经度，此处为简洁起见省略。
let latitude = 0, longitude = 0;

// 获取给定纬度和经度处的磁偏角。
fetch('https://www.ngdc.noaa.gov/geomag-web/calculators/calculateDeclination' +
      '?lat1=' + latitude + '&lon1=' + longitude + '&resultFormat=csv')
  .then(response => response.text()).then(text => {
    let declination = parseFloat(text.replace(/^#.*$/gm, '').trim().split(',')[4]);

    // 补偿磁偏角以得到地理北。
    console.log('以度为单位的真航向：' + (heading + declination));
});

注：如果设备未与地球表面保持水平， 开发者需要 应用各种倾斜补偿技术，为此她需要一个 3 轴 加速度计。要实现这一特定用例，需要来自方向传感器的数据； 方向传感器是加速度计和磁力计传感器的融合。

12. 致谢

感谢 Tobie Langel 在 Generic Sensor API 方面的工作。

13. 符合性

符合性要求以 描述性断言和 RFC 2119 术语的组合来表达。规范性部分中的关键词 "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、 "RECOMMENDED"、"MAY" 和 "OPTIONAL" 应按 RFC 2119 中的描述来解释。 不过，为了可读性，这些词在本规范中并非全部以大写字母 出现。

除明确标记为非规范性的章节、示例和注释外，本规范的全部文本均为规范性内容。 [RFC2119]

符合规范的用户 代理必须实现本规范中列出的所有适用于用户代理的 要求。

本规范中的 IDL 片段必须按 Web IDL 规范中对 符合性 IDL 片段的要求来解释。[WEBIDL]