磁力计 (Magnetometer)

1. 引言

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

本规范定义了两个新接口

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]

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

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

限制最高采样频率
降低传感器读数精度

这些缓解策略补充了通用传感器 API [GENERIC‑SENSOR] 中定义的通用缓解措施。

4. 权限策略集成

本规范使用了由字符串 "magnetometer" 标识的策略受控特性，该特性在 [DEVICE‑ORIENTATION] 中定义。

5. 模型

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

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

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

三个映射条目，其键为 “x”“y”“z”，其值包含相应轴的磁场信息。

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

扩展传感器接口: 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 包括 “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. 未校准磁力计接口

[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 包括 “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. 构造磁力计对象

input (输入): object，一个 Magnetometer 或 UncalibratedMagnetometer 实例; options，一个 MagnetometerSensorOptions 对象。

令 allowed 为调用检查传感器策略受控特性并传入 object 的传感器类型得到的结果。
If allowed is false, then
1. Throw a SecurityError DOMException.
Invoke initialize a sensor object with object and options.
如果 options.referenceFrame 为 “screen”，则
1. 将 object 的本地坐标系设为屏幕坐标系。
否则，将 object 的本地坐标系设为设备坐标系。

8. 自动化

本节扩展了通用传感器 API § 9 自动化，提供 Magnetometer 专有的虚拟传感器元数据。

8.1. 磁力计自动化

针对每种类型的虚拟传感器元数据的有序映射必须包含如下条目

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

8.2. 未校准磁力计自动化

针对每种类型的虚拟传感器元数据的有序映射必须包含如下条目

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

8.2.1. 未校准磁力计读取解析算法

input (输入): parameters, a JSON Object
output: 一个传感器读取或 undefined

令 reading 为使用解析 XYZ 读取并传入 parameters 的结果。
如果 reading 为 undefined。
1. 返回 undefined。
令 keys 为列表 « "xBias", "yBias", "zBias" »。
对每个 key 在 keys 中执行
1. 令 value 为调用解析单值数字读取，并传入 parameters 与 key 的结果。
  1. If value is undefined.
    1. 返回 undefined。
2. 设定 reading[key] 为 value[key]。
Return reading.

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

本节为非规范性内容.

地球磁场的方向与强度随地点（尤其是纬度）变化。例如，赤道附近的磁场强度最低，极地区域最高。硬铁干扰（如手机扬声器中的永久磁铁）会影响读取精度，电子设备、笔记本、电池等会产生软铁干扰。打开手机的飞行模式可以降低电磁干扰。

除了上述空间变化外，时间因素（如太阳风或磁暴）同样会扭曲地球磁层以及外部磁场。

10. 使用案例与需求

本节为非规范性内容.

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

传感器融合。磁力计常用于传感器融合，以生成一个相对于地球平面的绝对方位传感器 [MOTION‑SENSORS]（即与地球平面保持固定），或用于指南针——在此基础上根据地理位置的磁偏角进行校正，使之指向真北。指南针指向的计算详见 § 11 使用磁力计的指南针指向。
虚拟现实与增强现实。磁力计可用于在 VR 设备外壳上实现磁性按钮输入 [VRBUTTON]。VR/AR 头戴式追踪系统可利用磁力计数据校准陀螺仪，并将偏航对齐至磁北。
手势识别。通过磁棒、磁笔或磁环等磁体，可在设备周围的 3D 空间做出粗略手势。磁体的移动会改变设备内部指南针传感器感知的磁场，时间序列模式可用于向移动设备发送不同的交互指令，如缩放、翻页、接听/拒接电话、点击等 [MAGITACT]。
室内导航。移动设备上的磁力计数据可用于 [MAGINDOORPOS] 检测建筑内部的磁场。若局部磁场变化足够丰富，可利用这些异常实现自定位。室内导航的使用场景包括：附近广告、商场或机场的路径指引、地理围栏等。
金属探测。实用程序可以使用磁力计检测周围金属，例如寻找物体内部的金属夹层。

不同用例对数据粗糙度与采样频率的要求各不相同。例如，金属探测或磁性按钮输入可使用更粗的采样率和更低的频率；而手势识别、室内导航、VR/AR 等则需要更高的采样率。传感器融合场景的最优采样率取决于所使用的融合算法以及其他运动传感器的特性。

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);

给定纬度和经度的地理北的计算方法如下

// Get the latitude and longitude, omitted for brevity here.
let latitude = 0, longitude = 0;

// Get the magnetic declination at the given latitude and longitude.
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]);

    // Compensate for the magnetic declination to get the geographic north.
    console.log('True heading in degrees: ' + (heading + declination));
});

注意：如果设备未与地面保持水平，开发者需要使用三轴加速度计来实现各种倾角补偿技术。需要使用由加速度计和磁力计融合而成的方向传感器数据，才能实现此特定用例。

12. 致谢

Tobie Langel for the work on Generic Sensor API.

13. 符合性

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

本规范的所有文本均为规范性文本，明确标记为非规范性的部分、示例和注释除外。 [RFC2119]

A conformant user agent must implement all the requirements listed in this specification that are applicable to user agents.

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

磁力计 (Magnetometer)

摘要

关于本文档

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 索引