磁力计

1. 简介

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

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

Magnetometer 可报告已校准磁场值，和
UncalibratedMagnetometer 可报告未校准磁场值。

磁场是由于电流、磁性材料或地球磁力引起的磁力对磁力计传感器施加的一种场，这种力源于行星自转和地核熔化铁的运动的综合作用。

硬铁畸变由产生磁场的物体（如带磁性的铁）造成。

软铁畸变会拉伸或扭曲磁场，由镍、铁等金属引起。

已校准磁场是指对磁场应用硬铁畸变和软铁畸变校正后的结果。

未校准磁场是指磁场未进行硬铁畸变校正、但已应用软铁畸变校正的结果。因此该读数会反映靠近磁力计的带磁物体运动导致的磁场变化。

2. 示例

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

sensor.onreading = () => {
    console.log("Magnetic field along the X-axis " + sensor.x);
    console.log("Magnetic field along the Y-axis " + sensor.y);
    console.log("Magnetic field along the Z-axis " + sensor.z);
};

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

3. 安全与隐私注意事项

磁力计提供了磁场信息，从理论上讲，可以暴露用户的位置。例如，攻击方式可能是预先磁化某一特定地点的表面，或将某地的持续磁场扰动与建筑物进行映射。由于地球磁场强度不均匀，另一种攻击向量可能是暴露或验证用户的位置。例如，当终端用户通过 VPN 连接时，可将绑定的地理 IP 对应的磁场信息与真实地点的磁力计数据进行对比，从而判断用户是否使用了 VPN。实现者应注意磁场强度与其他因素（如 CPU 执行）相关性带来的旁道泄漏潜在风险，在某些情况下甚至可能泄露关于当前应用或其它标签页已访问网站的信息。[MAGSPY]

未校准磁力计读数可能受周边磁化物体（如饰品）影响，从而泄露可用于按键监控的信息。

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

限制最大采样频率
降低读数精度

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

4. 权限策略集成

本规范采用了策略控制特性，其关键字为 "magnetometer" ，由 [DEVICE-ORIENTATION] 定义。

5. 模型

磁力计传感器类型关联如下数据：

扩展传感器接口: Magnetometer
传感器权限名称: "magnetometer"
传感器特性名称: "magnetometer"
权限撤销算法: 用 "magnetometer" 调用通用传感器权限撤销算法。
虚拟传感器类型: "magnetometer"

最新读数，当Sensor的传感器类型为Magnetometer时，必须包括：

三个条目，其键为 "x"、"y"、"z"，其值为对应轴的磁场。

未校准磁力计传感器类型关联如下数据：

扩展传感器接口: UncalibratedMagnetometer
传感器权限名称: "magnetometer"
传感器特性名称: "magnetometer"
权限撤销算法: 用 "magnetometer" 调用通用传感器权限撤销算法。
虚拟传感器类型: "uncalibrated-magnetometer"

最新读数，当Sensor的传感器类型为Uncalibrated Magnetometer时，必须包括：

三个条目，其键为 "x"、"y"、"z"，其值为三轴的未校准磁场。
另外三个条目，其键为 "xBias"、"yBias"、"zBias"，其值为三轴的硬铁畸变校正值。

磁场值的正负号，必须符合本地坐标系的右手系规则（见下图）。

Magnetometer coordinate system.

5.1. 参考系

本地坐标系表示Magnetometer 与UncalibratedMagnetometer 读数的参考系，可以为设备坐标系或屏幕坐标系。

6. API

6.1. 磁力计接口

[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";
};

new Magnetometer(sensorOptions) 构造步骤是以构造磁力计对象抽象操作，并用this和 sensorOptions做参数调用。

Magnetometer Magnetometer 支持的选项为“frequency”和“referenceFrame”。

6.1.1. Magnetometer.x

x 属性（Magnetometer 接口）表示 X 轴方向的磁场。换言之，该属性返回以 this 和 "x" 为参数调用 get value from latest reading 的结果。

6.1.2. Magnetometer.y

y 属性（Magnetometer 接口）表示 Y 轴方向的磁场。换言之，该属性返回以 this 和 "y" 为参数调用 get value from latest reading 的结果。

6.1.3. Magnetometer.z

z 属性（Magnetometer 接口）表示 Z 轴方向的磁场。换言之，该属性返回以 this 和 "z" 为参数调用 get value from latest reading 的结果。

6.2. 非校准磁力计接口

[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;
};

new UncalibratedMagnetometer(sensorOptions) 构造步骤是以构造磁力计对象抽象操作，参数为 this 和 sensorOptions。

UncalibratedMagnetometer UncalibratedMagnetometer 支持的选项为“frequency”和“referenceFrame”。

6.2.1. UncalibratedMagnetometer.x

x 属性（UncalibratedMagnetometer 接口）表示 X 轴方向的未校准磁场。换言之，该属性返回以 this 和 "x" 为参数调用 get value from latest reading 的结果。

6.2.2. UncalibratedMagnetometer.y

y 属性（UncalibratedMagnetometer 接口）表示 Y 轴方向的未校准磁场。换言之，该属性返回以 this 和 "y" 为参数调用 get value from latest reading 的结果。

6.2.3. UncalibratedMagnetometer.z

z 属性（UncalibratedMagnetometer 接口）表示 Z 轴方向的未校准磁场。换言之，该属性返回以 this 和 "z" 为参数调用 get value from latest reading 的结果。

6.2.4. UncalibratedMagnetometer.xBias

xBias 属性（UncalibratedMagnetometer 接口）表示 X 轴方向的硬铁畸变校正量。换言之，该属性返回以 this 和 "xBias" 为参数调用 get value from latest reading 的结果。

6.2.5. UncalibratedMagnetometer.yBias

yBias 属性（UncalibratedMagnetometer 接口）表示 Y 轴方向的硬铁畸变校正量。换言之，该属性返回以 this 和 "yBias" 为参数调用 get value from latest reading 的结果。

6.2.6. UncalibratedMagnetometer.zBias

zBias 属性（UncalibratedMagnetometer 接口）表示 Z 轴方向的硬铁畸变校正量。换言之，该属性返回以 this 和 "zBias" 为参数调用 get value from latest reading 的结果。

7. 抽象操作

7.1. 构造磁力计对象

输入: object，一个 Magnetometer 或 UncalibratedMagnetometer 对象; options，一个 MagnetometerSensorOptions 对象。

令 allowed 为以 object 的传感器类型调用检查传感器策略控制特性的结果。
如果 allowed 为 false，则：
1. 抛出 SecurityError DOMException。
以 object 和 options 调用初始化传感器对象。
如果 options.referenceFrame 为 "screen"，则：
1. 将 object 的本地坐标系设为屏幕坐标系。
否则，将 object 的本地坐标系定义为设备坐标系。

8. 自动化

本节通过提供磁力计专用虚拟传感器元数据扩展了Generic Sensor API § 9 自动化。

8.1. 磁力计自动化

每类型虚拟传感器元数据映射必须包含如下条目：

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

8.2. 非校准磁力计自动化

每类型虚拟传感器元数据映射必须包含如下条目：

键: "uncalibrated-magnetometer"
值: 一个虚拟传感器元数据，其读数解析算法为非校准磁力计读数解析算法。

8.2.1. 非校准磁力计读数解析算法

输入: parameters，一个 JSON 对象
输出: 一个传感器读数或 undefined

令 reading 为以 parameters 调用解析 XYZ 读数的结果。
如果 reading 为 undefined。
1. 返回 undefined。
令 keys 为列表 « "xBias", "yBias", "zBias" »。
对于 keys 中的每一个 key
1. 令 value 为以 parameters 和 key 调用解析单值数字读数的结果。
  1. 如果 value 为 undefined。
    1. 返回 undefined。
2. 设置 reading[key] 为 value[key]。
返回 reading。

9. 磁力计传感器的局限性

本节为非规范性内容。

地球磁场的方向和强度会因所在位置而变化，尤其是纬度。例如，磁场强度在赤道附近最低，极地附近最高。一些硬铁干扰（即传感器附近存在永久磁体，如手机扬声器中的磁铁）也会影响读数的准确性。电子设备、笔记本电脑、电池等的存在，也会带来软铁干扰。手机上开启飞行模式可能有助于降低电磁干扰。

除了上述空间变化的磁场外，磁场还存在时间变化因素，如太阳风或磁暴，也会扭曲地球的磁层或外部磁场。

10. 用例与需求

本节为非规范性内容。

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

传感器融合。磁力计的一个常见用途是通过传感器融合产生一个绝对朝向传感器 [MOTION-SENSORS] ——它以地球平面为参考，或者罗盘（后者实际上是在前者基础上针对地磁偏角进行地理位置修正后指向真北）。详细的罗盘计算见§ 11 利用磁力计测定罗盘方位。
虚拟现实与增强现实。磁力计可用于 VR 盒子的磁按钮输入 [VRBUTTON]。VR/AR 头戴追踪系统可用磁力计数据帮助校准陀螺仪读数并使偏航与地磁北对齐。
手势识别。各种交互如写字、签名、演奏乐器等也可借助磁棒、笔或者指环等实现 [MAGITACT]。用户在设备周围三维空间做粗手势，磁体运动会影响设备内罗盘传感器探测到的磁场，手势的时间模式可作为发送不同交互命令的依据。缩放、翻页、接听/拒绝通话、点击项目等是应用实例。
室内导航。导航系统可利用移动设备上的磁力计数据 [MAGINDOORPOS] 检测建筑物内部磁场。只要本地变化充分，异常就可用于自定位。室内导航应用如邻近广告、商场/机场寻路、地理围栏等。
金属探测。磁力计可用于工具型应用检测附近是否存在金属，例如在物体中发现隐藏物质。

不同应用对数据粗糙度和采样频率的需求各异。例如，金属探测或磁按钮输入可用较粗的数据和较低的采样频率实现，而手势识别、室内导航、虚拟/增强现实等应用通常需要更高采样率。传感器融合场景中，最优采样频率还取决于算法类型及其它运动传感器的特性。

11. 利用磁力计测定罗盘方位

本节为非规范性内容。

罗盘（可与地球磁极自动对齐的仪器）在导航中已有数百年历史。地球自转轴定义了我们地图使用的地理南北极。但地理极点与磁极存在约 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 in degrees: ' + 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('True heading in degrees: ' + (heading + declination));
});

注：如果设备未与地球表面水平，开发者需引入多种倾斜补偿技术，此时需要三轴加速度计。方向传感器（加速度计与磁力计融合所得）数据亦是实现此场景的前提。

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 规范的相关要求进行解释。[WEBIDL]

磁力计

摘要

本文档状态

1. 简介

2. 示例

3. 安全与隐私注意事项

4. 权限策略集成

5. 模型

5.1. 参考系

6. API

6.1. 磁力计接口

6.1.1. Magnetometer.x

6.1.2. Magnetometer.y

6.1.3. Magnetometer.z

6.2. 非校准磁力计接口

6.2.1. UncalibratedMagnetometer.x

6.2.2. UncalibratedMagnetometer.y

6.2.3. UncalibratedMagnetometer.z

6.2.4. UncalibratedMagnetometer.xBias

6.2.5. UncalibratedMagnetometer.yBias

6.2.6. UncalibratedMagnetometer.zBias

7. 抽象操作

7.1. 构造磁力计对象

8. 自动化

8.1. 磁力计自动化

8.2. 非校准磁力计自动化

8.2.1. 非校准磁力计读数解析算法

9. 磁力计传感器的局限性

10. 用例与需求

11. 利用磁力计测定罗盘方位

12. 致谢

13. 一致性

索引

本规范定义的术语

外部引用定义的术语

参考文献

规范性引用

资料性引用

IDL 索引