磁力計

1. はじめに

Magnetometerは、Generic Sensor API [GENERIC-SENSOR] を拡張して、デバイスの一次磁力計センサーによって検出された磁場に関する情報を提供します。磁力計センサーは、μT（マイクロテスラ）単位でx, y, zの全ての物理軸の磁場を測定します。

本仕様は、2つの新しいインターフェースを定義します：

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. セキュリティとプライバシーに関する考慮事項

Magnetometerは磁場に関する情報を提供するため、理論的にはユーザーの位置情報を明らかにする可能性があります。たとえば、攻撃ベクトルには特定の場所に予め磁化された表面がある場合や、建物による一定の磁場の乱れと位置のマッピングなどが考えられます。地球の磁場の強度が一様でないため、別の攻撃ベクトルとしてユーザーの位置暴露や検証もあり得ます。たとえば、エンドユーザーがVPN接続している場合、Geo IP情報と関連付けられた磁場と実際の磁力計読み取り値を比較することで、ユーザーがVPNを使用しているかを判定できる場合があります。実装者は、磁場強度とCPU実行などの他の要素との相関によるサイドチャネル漏洩の潜在的リスクを認識してください。これにより、特定条件下では利用アプリケーションや他タブで閲覧中のウェブサイト等の情報が漏れる可能性があります。[MAGSPY]

非較正磁力計の読み取り値は近くの磁化されたオブジェクト（例：アクセサリー等）の影響を受けるため、キーストローク監視に利用されうる情報を露出する可能性もあります。

これらの特定脅威を緩和するため、ユーザーエージェントは以下のいずれかまたは両方の緩和策を用いるべきです：

最大サンプリング頻度の制限
センサー読み取り精度の低下

これらの緩和策は、Generic Sensor API [GENERIC-SENSOR] で定義された一般的な緩和策を補完します。

4. パーミッションポリシー統合

本仕様は、ポリシー管理機能として "magnetometer" を利用します。これは[DEVICE-ORIENTATION]で定義されています。

5. モデル

磁力計センサータイプには、次の関連データがあります：

拡張センサーインターフェース: Magnetometer
センサー許可名: "magnetometer"
センサー機能名: "magnetometer"
許可取り消しアルゴリズム: Generic Sensor許可取り消しアルゴリズムを "magnetometer" で呼び出します。
仮想センサータイプ: "magnetometer"

最新読み取り値は、Sensor のセンサータイプが磁力計の場合、以下を含まなければなりません：

"x", "y", "z" をキーにし、それぞれのエントリで該当軸方向の磁場を値として持つ。

非較正磁力計センサータイプには、次の関連データがあります：

拡張センサーインターフェース: UncalibratedMagnetometer
センサー許可名: "magnetometer"
センサー機能名: "magnetometer"
許可取り消しアルゴリズム: Generic Sensor許可取り消しアルゴリズムを "magnetometer" で呼び出します。
仮想センサータイプ: "uncalibrated-magnetometer"

最新読み取り値は、Sensor のセンサータイプが非較正磁力計の場合、以下を含まなければなりません：

"x", "y", "z" をキーにした3つのエントリ（値はそれぞれ非較正磁場）
"xBias", "yBias", "zBias" をキーにした3つの追加エントリ（値はそれぞれハードアイアン歪み補正）

磁場の値の符号は、ローカル座標系における右手系規則に従うものとします（下図参照）。

Magnetometer coordinate system.

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

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

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. 磁力計オブジェクトの構築

入力: 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 Automationを拡張し、Magnetometer固有の仮想センサメタデータを提供する。

8.1. 磁力計自動化

タイプごとの仮想センサメタデータのマップには次のエントリが含まれていなければならない：

key: "magnetometer"
value: 仮想センサメタデータで、読み取りパースアルゴリズムが parse XYZ readingであるもの。

8.2. 非較正磁力計自動化

タイプごとの仮想センサメタデータのマップには次のエントリが含まれていなければならない：

key: "uncalibrated-magnetometer"
value: 仮想センサメタデータで、読み取りパースアルゴリズムが非較正磁力計読み取り値パースアルゴリズムであるもの。

8.2.1. 非較正磁力計読み取り値パースアルゴリズム

入力: parameters、JSON Object
出力: センサー読み取り値またはundefined

readingを、parse XYZ readingにparametersを与えて得られる結果とする。
もしreadingがundefinedなら。
1. undefinedを返す。
keysをリスト« "xBias", "yBias", "zBias" »とする。
各keyについて：
1. valueを単一値数値読み取りパースをparametersとkeyで呼び出した結果とする。
  1. もしvalueがundefinedなら。
    1. undefinedを返す。
2. Set reading[key] を value[key] に設定する。
readingを返す。

9. 磁力計センサーの制限事項

このセクションは非規範的です。

地球の磁場の向きや強さは場所によって変化し、特に緯度によって異なります。たとえば、強さは赤道付近で最も弱く、極付近で最も強くなります。磁力計の近くに永久磁石（例：携帯電話のスピーカーなど）があると、ハードアイアン干渉が発生し、読み取り精度に影響します。また、電子機器やノートパソコン、バッテリー等の存在もソフトアイアン干渉の要因となります。携帯電話の機内モードを利用すると電磁干渉を低減できる場合があります。

上記の空間的な磁場変動に加えて、太陽風や磁気嵐などの時間的変動によって地球の磁気圏や外部磁場が歪められることもあります。

10. ユースケースと要件

このセクションは非規範的です。

磁力計はさまざまなユースケースで利用できます。たとえば：

センサーフュージョン。磁力計は絶対方位センサーAbsolute Orientation Sensor [MOTION-SENSORS]や、電子コンパスの生成に使われます。後者はジオロケーションに応じて偏角の補正を施したもので、真北を指せるようになります。コンパス方位の算出例は§ 11 磁力計を用いた方位測定を参照。
バーチャルリアリティ（VR）・拡張現実（AR）。磁力計はVRエンクロージャー用磁気ボタン入力[VRBUTTON]を実装したり、ヘッドマウントトラッキングでジャイロセンサー値の校正やヨー値を真北に合わせる補助に使われます。
ジェスチャ認識。磁石を使った棒・ペン・指輪の動きなどで多様なインタラクションを可能とします[MAGITACT]。ユーザーはデバイス周辺の空間で大まかな動きをし、その磁場への影響パターン（時系列）がジェスチャとなります。ズーム、ページ送り、着信/拒否、アイテムクリック等が代表例です。
屋内ナビゲーション。携帯端末の磁力計データを使い、建物内部の磁場を計測します[MAGINDOORPOS]。局所的な磁場変動を利用し自己位置推定が可能になります。屋内広告、モールや空港での案内、ジオフェンシング等の用途があります。
金属探知。ユーティリティアプリで磁力計を使って近くの金属の有無（例：物体中のインクルージョン調査）を検出できます。

データの粗さやサンプリング周波数への要件はユースケース次第で変わることがあります。たとえば、金属探知や磁気ボタン入力では粗いデータや低周波数で十分な場合が多いですが、ジェスチャ認識・屋内ナビゲーション・VR/ARではより高精度が必要です。センサーフュージョン用途では最適周波数もセンサの統合方法や他運動センサの特性によって変わります。

11. 磁力計を用いた方位測定

このセクションは非規範的です。

コンパス（地磁気の極に合わせる機器）は、何世紀も航法で利用されてきました。地球の自転軸が地理的な北極・南極を定義しますが、地理極と磁極は約11.5度（約1600km）ずれており、この補正に偏角を加えます。

デバイスが常に地面に水平な場合、地磁気のx およびy 成分からコンパス方位を計算できます。真北（地理的な北）を得るには適切な偏角を加えます。

磁気偏角または偏角は、水平面上での磁北と真北のなす角で、地表の位置・時刻で変化します。慣例的に磁北が真北より東なら正、西なら負となります。リアルタイム値はNOAAが提供するMagnetic declination calculator等で取得可能です。

磁北は次のように算出できます：

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

注: デバイスが地面に水平でない場合、各種チルト補正（傾き補正）手法を適用する必要があり、そのためには3軸加速度センサーが必要です。加速度センサーと磁力計のフュージョンであるオリエンテーションセンサーのデータがこの用途には必要です。

12. 謝辞

Generic Sensor API 作業に対して Tobie Langel に感謝します。

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. Magnetometerインターフェース

6.1.1. Magnetometer.x

6.1.2. Magnetometer.y

6.1.3. Magnetometer.z

6.2. UncalibratedMagnetometerインターフェース

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