方位センサー

1. 導入

Orientation Sensor API は Generic Sensor API [GENERIC-SENSOR] を拡張し、三次元デカルト座標系に対するデバイスの物理的な方位を記述する汎用情報を提供する。

AbsoluteOrientationSensor クラスは OrientationSensor インターフェイスから継承し、地球の参照座標系に対するデバイスの物理的な方位を記述する。

他のサブクラスは、真北などの他の静止した方向、またはデバイス自身の z 位置に対して、その最新の最も安定した z 位置へドリフトしていくような非静止方向に対する方位を記述する。

OrientationSensor サブクラスにより提供されるデータは、 DeviceOrientationEvent からのデータと類似しているが、Orientation Sensor API には次の重要な違いがある:

Orientation Sensor API は、方位データを WebGL 互換形式（クォータニオン、回転行列）で表す。
Orientation Sensor API は、より厳格なレイテンシー要件を満たす。
DeviceOrientationEvent とは異なり、 OrientationSensor サブクラスは、方位データを取得するためにどの低レベルモーションセンサーが使用されるかを明示的に定義し、それにより起こり得る相互運用性の問題を不要にする。
OrientationSensor サブクラスのインスタンスは、 SensorOptions コンストラクター引数を介して設定可能である。

2. ユースケースと要件

ユースケースと要件は、 Motion Sensors Explainer 文書で議論されている。

3. 例

const sensor = new AbsoluteOrientationSensor();
const mat4 = new Float32Array(16);
sensor.start();
sensor.onerror = event => console.log(event.error.name, event.error.message);

sensor.onreading = () => {
  sensor.populateMatrix(mat4);
};

const sensor = new AbsoluteOrientationSensor({ frequency: 60 });
const mat4 = new Float32Array(16);
sensor.start();
sensor.onerror = event => console.log(event.error.name, event.error.message);

function draw(timestamp) {
  window.requestAnimationFrame(draw);
  try {
    sensor.populateMatrix(mat4);
  } catch(e) {
    // mat4 has not been updated.
  }
  // Drawing...
}

window.requestAnimationFrame(draw);

4. セキュリティとプライバシーに関する考慮事項

Generic Sensor API [GENERIC-SENSOR] で説明されているものを超える、特定のセキュリティおよびプライバシーに関する考慮事項はない。

5. モデル

OrientationSensor クラスは Sensor クラスを拡張し、デバイス方位データを表す汎用インターフェイスを提供する。

Orientation Sensor センサー型の最新読み取り値にアクセスするために、ユーザーエージェントは、具象方位センサーが使用する各低レベルセンサーについて、センサーアクセスを要求する抽象操作を呼び出さなければならない。下の表は、具象方位センサーと、低レベルセンサーにより定義される許可トークンとの対応関係を記述する。

OrientationSensor サブクラス	許可トークン
`AbsoluteOrientationSensor`	"`accelerometer`", "`gyroscope`", "`magnetometer`"
`RelativeOrientationSensor`	"`accelerometer`", "`gyroscope`"

AbsoluteOrientationSensor は、文字列 "accelerometer"、"gyroscope"、および "magnetometer" により識別されるポリシー制御機能である。その既定の許可リストは 'self' である。

RelativeOrientationSensor は、文字列 "accelerometer" および "gyroscope" により識別されるポリシー制御機能である。その既定の許可リストは 'self' である。

最新読み取り値は、Orientation Sensor センサー型の Sensor について、キーが "quaternion" であり、値が 4 要素のリストを含むエントリーを含む。リストの要素は、単位クォータニオン [QUATERNIONS] [V_x * sin(θ/2), V_y * sin(θ/2), V_z * sin(θ/2), cos(θ/2)] の成分に等しい。ここで V は回転軸を表す単位ベクトル（その要素は V_x、V_y、および V_z）であり、 θ は単位ベクトル V により定義される軸まわりの回転角である。

注記: クォータニオン成分は、リスト内に [q₁, q₂, q₃, q₀] [QUATERNIONS] として配置される。すなわち、クォータニオンのベクトル部を表す成分が先に来て、cos(θ/2) に等しいスカラー部成分が後に来る。この順序は、既存のほとんどの WebGL フレームワークとの互換性を高めるために使用される。ただし、他のライブラリは、クォータニオンを配列として公開するときに別の順序、たとえば [q₀, q₁, q₂, q₃] を使用する可能性がある。

低レベルモーションセンサーのセンサーフュージョンを通して作成される具象 OrientationSensor サブクラスを下の表に示す:

OrientationSensor サブクラス	低レベルモーションセンサー
`AbsoluteOrientationSensor`	`Accelerometer`, `Gyroscope`, `Magnetometer`
`RelativeOrientationSensor`	`Accelerometer`, `Gyroscope`

注記: Accelerometer、 Gyroscope および Magnetometer 低レベルセンサーは、それぞれ [ACCELEROMETER]、[GYROSCOPE]、および [MAGNETOMETER] 仕様で定義される。センサーフュージョンはプラットフォーム固有であり、ソフトウェアまたはハードウェア、すなわちセンサーハブ上で発生し得る。

この例のコードは、AbsoluteOrientationSensor について、start() を呼び出す前に、明示的に許可を照会する。

const sensor = new AbsoluteOrientationSensor();
Promise.all([navigator.permissions.query({ name: "accelerometer" }),
             navigator.permissions.query({ name: "magnetometer" }),
             navigator.permissions.query({ name: "gyroscope" })])
       .then(results => {
             if (results.every(result => result.state === "granted")) {
               sensor.start();
               ...
             } else {
               console.log("No permissions to use AbsoluteOrientationSensor.");
             }
       });

別の方法は、単に start() を呼び出し、 onerror イベントハンドラーを購読することである。

const sensor = new AbsoluteOrientationSensor();
sensor.onerror = event => {
  if (event.error.name === 'NotAllowedError')
    console.log("No permissions to use AbsoluteOrientationSensor.");
};
sensor.start();

5.1. AbsoluteOrientationSensor モデル

Absolute Orientation Sensor センサー型は、Motion Sensors Explainer § absolute-orientation で説明されるセンサーを表す。これに関連付けられた拡張センサーインターフェイスは AbsoluteOrientationSensorであり、 OrientationSensor のサブクラスである。これに関連付けられた仮想センサー型は "absolute-orientation" である。

絶対方位センサーについては、最新読み取り値["quaternion"] の値は、三次元デカルト座標系 (x, y, z) として定義される地球の参照座標系に対する、デバイスのローカル座標系の回転を表す。ここで:

x 軸は、地面に接し東を指す y.z のベクトル積である。
y 軸は地面に接し、磁北を指す。
z 軸は空を指し、x 軸と y 軸で構成される平面に垂直である。

デバイスのローカル座標系は、低レベルモーションセンサーについて定義されるものと同じである。それはデバイス座標系またはスクリーン座標系のいずれかであり得る。

注記: 下の図は、デバイスのローカル座標系と地球の参照座標系が整列している場合を表す。したがって、方位センサーの最新読み取り値は、各軸まわりの 0 (rad) [SI] 回転を表す。

AbsoluteOrientationSensor coordinate system.

5.2. RelativeOrientationSensor モデル

Relative Orientation Sensor センサー型は、Motion Sensors Explainer § relative-orientation で説明されるセンサーを表す。これに関連付けられた拡張センサーインターフェイスは RelativeOrientationSensorであり、 OrientationSensor のサブクラスである。これに関連付けられた仮想センサー型は "relative-orientation" である。

相対方位センサーについては、最新読み取り値["quaternion"] の値は、静止参照座標系に対する、デバイスのローカル座標系の回転を表す。静止参照座標系は、ジャイロスコープセンサーにより導入されるバイアスによってドリフトし得る。したがって、センサーにより提供される回転値は、時間とともにドリフトし得る。

静止参照座標系は、センサーをホストするデバイスが環境内を移動しても静止したままである、慣性三次元デカルト座標系として定義される。

注記: 相対方位センサーのデータは、磁場の影響を受けないため、絶対方位センサーが提供するものより正確であり得る。

6. API

6.1. OrientationSensor インターフェイス

typedef (Float32Array or Float64Array or DOMMatrix) RotationMatrixType;

[SecureContext, Exposed=Window]
interface OrientationSensor : Sensor {
  readonly attribute FrozenArray<double>? quaternion;
  undefined populateMatrix(RotationMatrixType targetMatrix);
};

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

dictionary OrientationSensorOptions : SensorOptions {
  OrientationSensorLocalCoordinateSystem referenceFrame = "device";
};

6.1.1. OrientationSensor.quaternion

デバイス方位を表す単位クォータニオンの成分を要素として含む、 4 要素の FrozenArray を返す。言い換えると、この属性は、最新読み取り値から値を取得するを this および "quaternion" を引数として呼び出した結果を返す。

6.1.2. OrientationSensor.populateMatrix()

populateMatrix(targetMatrix) メソッドの手順は次のとおりである:

targetMatrix が Float32Array または Float64Array 型であり、そのサイズが 16 未満である場合、"TypeError" 例外を投げ、これらの手順を中止する。
quaternion を、最新読み取り値から値を取得するを this および "quaternion" を引数として呼び出した結果とする。
quaternion が null である場合、"NotReadableError" DOMException を投げ、これらの手順を中止する。
rotationMatrix を、quaternion[0]、quaternion[1]、 quaternion[2]、および quaternion[3] を用いてクォータニオンを回転行列に変換することの結果とする。
targetMatrix が Float32Array または Float64Array 型である場合、次のサブ手順を実行する:
1. targetMatrix[0] = rotationMatrix[0] に設定する
2. targetMatrix[1] = rotationMatrix[1] に設定する
3. targetMatrix[2] = rotationMatrix[2] に設定する
4. targetMatrix[3] = rotationMatrix[3] に設定する
5. targetMatrix[4] = rotationMatrix[4] に設定する
6. targetMatrix[5] = rotationMatrix[5] に設定する
7. targetMatrix[6] = rotationMatrix[6] に設定する
8. targetMatrix[7] = rotationMatrix[7] に設定する
9. targetMatrix[8] = rotationMatrix[8] に設定する
10. targetMatrix[9] = rotationMatrix[9] に設定する
11. targetMatrix[10] = rotationMatrix[10] に設定する
12. targetMatrix[11] = rotationMatrix[11] に設定する
13. targetMatrix[12] = rotationMatrix[12] に設定する
14. targetMatrix[13] = rotationMatrix[13] に設定する
15. targetMatrix[14] = rotationMatrix[14] に設定する
16. targetMatrix[15] = rotationMatrix[15] に設定する
targetMatrix が DOMMatrix 型である場合、次のサブ手順を実行する:
1. targetMatrix.m11 = rotationMatrix[0] に設定する
2. targetMatrix.m12 = rotationMatrix[1] に設定する
3. targetMatrix.m13 = rotationMatrix[2] に設定する
4. targetMatrix.m14 = rotationMatrix[3] に設定する
5. targetMatrix.m21 = rotationMatrix[4] に設定する
6. targetMatrix.m22 = rotationMatrix[5] に設定する
7. targetMatrix.m23 = rotationMatrix[6] に設定する
8. targetMatrix.m24 = rotationMatrix[7] に設定する
9. targetMatrix.m31 = rotationMatrix[8] に設定する
10. targetMatrix.m32 = rotationMatrix[9] に設定する
11. targetMatrix.m33 = rotationMatrix[10] に設定する
12. targetMatrix.m34 = rotationMatrix[11] に設定する
13. targetMatrix.m41 = rotationMatrix[12] に設定する
14. targetMatrix.m42 = rotationMatrix[13] に設定する
15. targetMatrix.m43 = rotationMatrix[14] に設定する
16. targetMatrix.m44 = rotationMatrix[15] に設定する

6.2. AbsoluteOrientationSensor インターフェイス

[SecureContext, Exposed=Window]
interface AbsoluteOrientationSensor : OrientationSensor {
  constructor(optional OrientationSensorOptions sensorOptions = {});
};

AbsoluteOrientationSensor オブジェクトを構築するために、ユーザーエージェントは AbsoluteOrientationSensor インターフェイスについて方位センサーオブジェクトを構築する抽象操作を呼び出さなければならない。

AbsoluteOrientationSensor のサポートされるセンサーオプションは、 "frequency" および "referenceFrame" である。

6.3. RelativeOrientationSensor インターフェイス

[SecureContext, Exposed=Window]
interface RelativeOrientationSensor : OrientationSensor {
  constructor(optional OrientationSensorOptions sensorOptions = {});
};

RelativeOrientationSensor オブジェクトを構築するために、ユーザーエージェントは RelativeOrientationSensor インターフェイスについて方位センサーオブジェクトを構築する抽象操作を呼び出さなければならない。

RelativeOrientationSensor のサポートされるセンサーオプションは、 "frequency" および "referenceFrame" である。

7. 抽象操作

7.1. Orientation Sensor オブジェクトを構築する

入力: orientation_interface、その継承インターフェイスが OrientationSensor を含む、インターフェイス識別子。; options、OrientationSensorOptions オブジェクト。
出力: OrientationSensor オブジェクト。

allowed を、orientation_interface により識別されるインターフェイスを用いてセンサーのポリシー制御機能を確認するを呼び出した結果とする。
allowed が false の場合、次を実行する:
1. SecurityError DOMExceptionを投げる。
orientation を、orientation_interface により識別されるインターフェイスの新しいインスタンスとする。
orientation および options を用いてセンサーオブジェクトを初期化するを呼び出す。
options.referenceFrame が "screen" である場合、次を実行する:
1. orientation のローカル座標系を、スクリーン座標系として定義する。
そうでなければ、orientation のローカル座標系を、デバイス座標系として定義する。
orientation を返す。

7.2. クォータニオンを回転行列に変換する

クォータニオンを回転行列に変換するアルゴリズムは、以下に示すように、クォータニオン [QUATCONV] から変換された列優先順の回転行列のリスト表現を作成する:

Converting quaternion to rotation matrix.

ここで:

W = cos(θ/2)
X = V_x * sin(θ/2)
Y = V_y * sin(θ/2)
Z = V_z * sin(θ/2)

数 x、数 y、数 z、および数 w が与えられたとき、クォータニオンを回転行列に変換するには:

m11 を 1 - 2 * y * y - 2 * z * z とする
m12 を 2 * x * y - 2 * z * w とする
m13 を 2 * x * z + 2 * y * w とする
m14 を 0 とする
m21 を 2 * x * y + 2 * z * w とする
m22 を 1 - 2 * x * x - 2 * z * z とする
m23 を 2 * y * z - 2 * x * w とする
m24 を 0 とする
m31 を 2 * x * z - 2 * y * w とする
m32 を 2 * y * z + 2 * x * w とする
m33 を 1 - 2 * x * x - 2 * y * y とする
m34 を 0 とする
m41 を 0 とする
m42 を 0 とする
m43 を 0 とする
m44 を 1 とする
« m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 » を返す。

7.3. オイラー角からクォータニオンを作成する

数 alpha、数 beta、および数 gamma が与えられたとき、オイラー角からクォータニオンを作成するには:

alphaInRadians を、alpha を度からラジアンに変換したものとする。
betaInRadians を、beta を度からラジアンに変換したものとする。
gammaInRadians を、gamma を度からラジアンに変換したものとする。
cosZ を (0.5 * alphaInRadians) の余弦とする。
sinZ を (0.5 * alphaInRadians) の正弦とする。
cosX を (0.5 * betaInRadians) の余弦とする。
sinX を (0.5 * betaInRadians) の正弦とする。
cosY を (0.5 * gammaInRadians) の余弦とする。
sinY を (0.5 * gammaInRadians) の正弦とする。
quaternionX を (sinX * cosY * cosZ - cosX * sinY * sinZ) とする。
quaternionY を (cosX * sinY * cosZ + sinX * cosY * sinZ) とする。
quaternionZ を (cosX * cosY * sinZ + sinX * sinY * cosZ) とする。
quaternionW を (cosX * cosY * cosZ - sinX * sinY * sinZ) とする。
« quaternionX, quaternionY, quaternionZ, quaternionW » を返す。

8. 自動化

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

8.1. 他の仕様への変更

この仕様は、Device Orientation and Motion § automation と次のように統合する。

方位データ読み取り値を解析するアルゴリズムは、次のように変更される:

reading の "alpha"、 "beta"、および "gamma" キーを設定した後、 reading を返す前に、次の手順を追加する:
1. reading["quaternion"] を、 reading["alpha"]、 reading["beta"]、および reading["gamma"] を用いてオイラー角からクォータニオンを作成するを呼び出した結果に設定する。

注記: この仕様は現在、 WebDriver でクォータニオンを直接指定する（そしてその結果としてクォータニオンからオイラー角を導出する）方法を提供していない。この決定は、単純さのため、および自動化ユーザーは入力としてオイラー角を扱う（または特定のクォータニオン値を選び、対応するオイラー角値を自分で提供する）可能性がはるかに高いという前提のもとで行われた。クォータニオン値を直接提供できることに関心を持つ、異なるユースケースのユーザーからのフィードバックは、この仕様の課題トラッカーを通じて歓迎される。

8.2. Absolute Orientation Sensor の自動化

absolute-orientation 仮想センサー型と、型ごとの仮想センサーメタデータマップ内の対応するエントリーは、Device Orientation and Motion § automation で定義される。

8.3. Relative Orientation Sensor の自動化

relative-orientation 仮想センサー型と、型ごとの仮想センサーメタデータマップ内の対応するエントリーは、Device Orientation and Motion § automation で定義される。

9. 謝辞

Generic Sensor API への取り組みについて Tobie Langel に感謝する。

方位センサー

概要

この文書のステータス

1. 導入

2. ユースケースと要件

3. 例

4. セキュリティとプライバシーに関する考慮事項

5. モデル

5.1. AbsoluteOrientationSensor モデル

5.2. RelativeOrientationSensor モデル

6. API

6.1. OrientationSensor インターフェイス

6.1.1. OrientationSensor.quaternion

6.1.2. OrientationSensor.populateMatrix()

6.2. AbsoluteOrientationSensor インターフェイス

6.3. RelativeOrientationSensor インターフェイス

7. 抽象操作

7.1. Orientation Sensor オブジェクトを構築する

7.2. クォータニオンを回転行列に変換する

7.3. オイラー角からクォータニオンを作成する

8. 自動化

8.1. 他の仕様への変更

8.2. Absolute Orientation Sensor の自動化

8.3. Relative Orientation Sensor の自動化

9. 謝辞

適合性

文書の慣例

適合するアルゴリズム

索引

この仕様で定義される用語

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

参考文献

規範的参考文献

非規範的参考文献

IDL 索引

方位センサー

概要

この文書のステータス

1. 導入

2. ユースケースと要件

3. 例

4. セキュリティとプライバシーに関する考慮事項

5. モデル

5.1. AbsoluteOrientationSensor モデル

5.2. RelativeOrientationSensor モデル

6. API

6.1. OrientationSensor インターフェイス

6.1.1. OrientationSensor.quaternion

6.1.2. OrientationSensor.populateMatrix()

6.2. AbsoluteOrientationSensor インターフェイス

6.3. RelativeOrientationSensor インターフェイス

7. 抽象操作

7.1. Orientation Sensor オブジェクトを構築する

7.2. クォータニオンを回転行列に変換する

7.3. オイラー角からクォータニオンを作成する

8. 自動化

8.1. 他の仕様への変更

8.2. Absolute Orientation Sensor の自動化

8.3. Relative Orientation Sensor の自動化

9. 謝辞

適合性

文書の 慣例

適合する アルゴリズム

索引

この仕様で定義される用語

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

参考文献

規範的参考文献

非規範的参考文献

IDL 索引

文書の慣例

適合するアルゴリズム