磁力計

W3C 作業草案,

この文書の詳細
このバージョン:
https://www.w3.org/TR/2026/WD-magnetometer-20260514/
最新公開バージョン:
https://www.w3.org/TR/magnetometer/
編集者草案:
https://w3c.github.io/magnetometer/
以前のバージョン:
履歴:
https://www.w3.org/standards/history/magnetometer/
フィードバック:
public-device-apis@w3.org 件名行 “[magnetometer] … メッセージのトピック …” で（アーカイブ）
Magnetometer 課題リポジトリ
編集者:
Anssi Kostiainen（Intel Corporation）
Rijubrata Bhaumik（Intel Corporation）
テストスイート:
GitHub 上の web-platform-tests

Copyright © 2026 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

概要

この仕様は、X、Y、Z 軸における磁場を測定するための具体的な センサーインターフェイスを定義する。

この文書のステータス

この節は、公開時点におけるこの文書のステータスを説明する。 現在の W3C 公開物の一覧およびこの技術報告書の最新改訂版は、 W3C 技術報告書 インデックスで確認できる。

この文書は、 Devices and Sensors Working Group により、 Recommendation track を用いる Working Draft として公開された。この文書は W3C Recommendation となることを意図している。

この文書に関するコメントを送りたい場合は、 public-device-apis@w3.org （購読、 アーカイブ）に送信されたい。 電子メールを送信するときは、 件名に “magnetometer” というテキストを含め、 できれば次のようにすること: “[magnetometer] …コメントの要約…”。 すべてのコメントを歓迎する。

Working Draft としての公開は、 W3C およびそのメンバーによる承認を意味しない。この文書は草案文書であり、いつでも 更新、置換、または 他の文書により廃止される可能性がある。この 文書を進行中の作業以外として引用することは不適切である。

この文書は、 W3C Patent Policy の下で運営されるグループにより作成された。 W3C は、このグループの成果物に関連して行われた 特許開示の公開一覧を維持しており、 そのページには特許を開示するための指示も含まれている。 ある個人が、その個人が Essential Claim(s) を含むと考える特許について実際の知識を有する場合、 その個人は W3C Patent Policy 第 6 節に従って情報を開示しなければならない。

この文書は、2025年8月18日版 W3C Process Document により管理される。

複数のブラウザーエンジンがこの仕様について懸念を表明している。これは どのブラウザーエンジンでもデフォルトでは利用できない。現在の形のまま W3C Recommendation に進むことは想定されていない。

この仕様は開発者からのフィードバックと価値の高いユースケースを求めている。フィードバックは GitHub 経由で提供されたい。

この文書は随時保守および更新される。この文書の一部は作業中である。

1. 序論

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

この仕様は、2 つの新しいインターフェイスを定義する:

磁場とは、 電流、磁性材料、または惑星の自転と地球核内の溶融鉄の運動との複合的効果に起因する 地球の磁力によって生成される磁気効果により、磁力計センサーに磁気力を及ぼす 場である。

硬鉄 歪みは、磁化された鉄など、 磁場を生成する 物体によって作られる。

軟鉄 歪みは、 磁場を伸張または歪ませ、 ニッケルや鉄などの金属によって引き起こされる。

校正済み 磁場とは、磁場に硬鉄歪みおよび軟鉄 歪みの補正を適用したものである。

未校正 磁場とは、 磁場であって、硬鉄 歪み補正は行わず、軟鉄歪み補正を適用したものであり、 そのため、磁力計の近くを移動する磁化された物体によって引き起こされる 磁場の変化を報告する。

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 経由で接続している場合、 geo IP 情報に関連付けられた磁場を実際の位置での磁力計読み取り値と比較することで、 ユーザーが VPN を使用しているかどうかを判別できる。実装者は、 磁場強度と CPU 実行などの他の側面との相関を介したサイドチャネル漏洩の潜在的リスクに 注意するべきであり、特定の状況下では、他のタブで使用されているアプリケーションや 訪問されたウェブサイトについての情報が漏洩する可能性がある。 [MAGSPY]

未校正磁力計の読み取り値は、宝飾品など近くにある磁化された物体の影響を受ける可能性があり、 それによりキーストローク 監視に使用され得る情報が暴露される可能性がある。

これらの特定の脅威を緩和するため、ユーザーエージェントは 次の緩和戦略の一方または両方を用いるべきである:

これらの緩和戦略は、 Generic Sensor API [GENERIC-SENSOR] で定義される 汎用的な 緩和策を補完する。

4. Permissions Policy との統合

この仕様は、ポリシー制御機能を利用する。この機能は、 [DEVICE-ORIENTATION] で定義される文字列 "magnetometer" により識別される。

5. モデル

Magnetometer センサー型は、 次の関連データを持つ:

拡張センサーインターフェイス

Magnetometer

センサー権限名

"magnetometer"

センサー機能名

"magnetometer"

権限失効アルゴリズム

"magnetometer" を用いて 汎用センサー権限失効 アルゴリズムを呼び出す。

仮想センサー型

"magnetometer"

センサー型が Magnetometer である Sensor についての 最新の読み取り値には、次のものが含まれなければならない:

Uncalibrated Magnetometer センサー型は、 次の関連データを持つ:

拡張センサーインターフェイス

UncalibratedMagnetometer

センサー権限名

"magnetometer"

センサー機能名

"magnetometer"

権限失効アルゴリズム

"magnetometer" を用いて 汎用センサー権限 失効アルゴリズムを呼び出す。

仮想センサー型

"uncalibrated-magnetometer"

センサー型が Uncalibrated Magnetometer である Sensor についての 最新の読み取り値には、次のものが含まれなければならない:

磁場値の符号は、 ローカル 座標系における右手系の規約に従わなければならない（下図を参照）。

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 オブジェクト。

  1. allowed を、object の センサー型を用いて センサーのポリシー制御機能を確認する を呼び出した結果とする。

  2. allowed が false の場合:

    1. SecurityError DOMException を投げる。

  3. object および options を用いて センサーオブジェクトを初期化するを 呼び出す。

  4. options.referenceFrame が "screen" の場合:

    1. object のローカル座標系を画面座標系に設定する。

  5. そうでなければ、object のローカル座標系をデバイス座標系として定義する。

8. 自動化

この節は、Magnetometer 固有の仮想センサーメタデータを提供することで、 Generic Sensor API § 9 Automation を拡張する。

8.1. Magnetometer の自動化

型ごとの仮想センサーメタデータ マップは、 次のエントリーを持たなければならない:

キー

"magnetometer"

値

仮想センサーメタデータであって、その 読み取り解析アルゴリズムが XYZ 読み取りを解析するであるもの。

8.2. Uncalibrated Magnetometer の自動化

型ごとの仮想センサーメタデータ マップは、 次のエントリーを持たなければならない:

キー

"uncalibrated-magnetometer"

値

仮想センサーメタデータであって、その 読み取り解析アルゴリズムが uncalibrated magnetometer 読み取り解析アルゴリズムであるもの。

8.2.1. Uncalibrated Magnetometer 読み取り解析アルゴリズム

入力

parameters、JSON Object

出力

センサー読み取り値または undefined

  1. reading を、parameters を用いて XYZ 読み取りを解析するを行った結果とする。

  2. reading が undefined である場合。

    1. undefined を返す。

  3. keys を、リスト « "xBias", "yBias", "zBias" » とする。

  4. keys の各 key について反復する

    1. value を、parameters および key を用いて 単一値数値読み取りを解析する を呼び出した結果とする。

      1. value が undefined である場合。

        1. undefined を返す。

    2. reading[key] を value[key] に設定する。

  5. reading を返す。

9. Magnetometer センサーの制限

この節は非規範的である。

地球磁場の方向および大きさは場所、特に緯度によって変化する。たとえば、 大きさは赤道付近で最も低く、極付近で最も高い。 センサーの近くに永久磁石（たとえば電話のスピーカー内の磁石）が存在することを意味する 一部の硬鉄干渉も、読み取り値の精度に影響する。 電子機器、ラップトップ、バッテリーなどの存在も、軟鉄干渉の一因となる。 携帯電話のフライトモードオプションは、電磁干渉を減少させるのに役立つ可能性がある。

上記の磁場の空間的変動に加え、太陽風や磁気嵐のような時間的変動も、 磁気圏または地球の外部磁場を歪ませる。

10. ユースケースと要件

この節は非規範的である。

磁力計は、たとえば次のようなさまざまなユースケースに使用できる:

データの粗さおよびサンプリング周波数に関する要件は、対象となるユースケースによって異なり得る。 たとえば、金属探知または磁気ボタンを用いた入力は、ジェスチャー認識、屋内ナビゲーション、 または VR および AR のユースケースに比べて、より粗いデータおよびより低いサンプリング周波数で実装できる可能性が高い。 センサーフュージョンのユースケースでは、最適な結果をもたらすサンプリング周波数は、 たとえばセンサーフュージョンアルゴリズムや関与する他のモーションセンサーの特性に依存する。

11. 磁力計を用いたコンパス方位

この節は非規範的である。

地球の磁極に自らを合わせる器具であるコンパスは、 何世紀にもわたって航海に使用されてきた。 地球の自転軸は、地図参照に使用する地理的な北極および南極を定義する。 地理的な極と磁極との間には約 11.5 度（約 1000 マイル）のずれがあることがわかっている。 偏角は、 この状況を補正するために磁気方向に適用される。

デバイスが常に地表に対して水平である場合、コンパス方位は、地球磁場の x および y 成分、すなわち地表と同一平面上の方向のみを用いて決定できる。 地理的な北（または真北）方位を決定するには、適切な 偏角を加算する。

磁気 偏角または 偏角とは、水平面上における磁北と真北との間の角度であり、 地表上の位置に依存し、時間とともに変化する。 慣例により、偏角は磁北が真北の東にある場合に正であり、西にある場合に負である。 磁気偏角のリアルタイム値は、たとえば National Oceanic and Atmospheric Administration（NOAA）が提供する Magnetic declination calculator を使用して取得できる。

磁北は次のように計算される:

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 軸 加速度計が必要である。加速度計および磁力計センサーの融合である orientation sensor からのデータは、この特定のユースケースを実装するために必要である。

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 仕様で説明されるように、 適合する IDL 断片に要求されるものとして解釈されなければならない。 [WEBIDL]

索引

この仕様により定義される 用語

参照により定義される 用語

参考文献

規範的参考文献

[ACCELEROMETER]
Anssi Kostiainen. Accelerometer. 2025年2月12日。 CRD。URL: https://www.w3.org/TR/accelerometer/
[DEVICE-ORIENTATION]
Reilly Grant; Marcos Caceres. Device Orientation and Motion. 2025年2月12日。CRD。URL: https://www.w3.org/TR/orientation-event/
[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.es/ecma262/multipage/
[GENERIC-SENSOR]
Rick Waldron. Generic Sensor API. 2026年1月21日。 CRD。URL: https://www.w3.org/TR/generic-sensor/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard。URL: https://infra.spec.whatwg.org/
[PERMISSIONS]
Marcos Caceres; Mike Taylor. Permissions. 2025年10月6日。 WD。URL: https://www.w3.org/TR/permissions/
[PERMISSIONS-POLICY-1]
Ian Clelland. Permissions Policy. 2025年10月6日。 WD。URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. 1997年3月。Best Current Practice。URL: https://datatracker.ietf.org/doc/html/rfc2119
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard。URL: https://webidl.spec.whatwg.org/

非規範的参考文献

[MAGINDOORPOS]
Janne Haverinen, Anssi Kemppainen. Global indoor self-localization based on the ambient magnetic field. Informational。URL: https://doi.org/10.1016%2Fj.robot.2009.07.018
[MAGITACT]
Hamed Ketabdar, Kamer Ali Yüksel, Mehran Roshandel. Magitact. Informational。URL: https://dl.acm.org/doi/10.1145/1719970.1720048
[MAGSPY]
Nikolay Matyunin, Yujue Wang, Tolga Arul, Kristian Kullmann, Jakub Szefer, Stefan Katzenbeisser. MagneticSpy: Exploiting Magnetometer in Mobile Devices for Website and Application Fingerprinting. Informational。URL: https://dl.acm.org/doi/abs/10.1145/3338498.3358650
[MOTION-SENSORS]
Kenneth Christiansen; Alexander Shalamov. Motion Sensors Explainer. 2017年8月30日。NOTE。URL: https://www.w3.org/TR/motion-sensors/
[VRBUTTON]
Boris Smus. Magnetic input for Google cardboard. Informational。URL: https://bugs.chromium.org/p/chromium/issues/detail?id=445926

IDL 索引

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

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