방향 센서

1. 소개

Orientation Sensor API는 Generic Sensor API [GENERIC-SENSOR]를 확장하여 3차원 데카르트 좌표계와 관련된 장치의 물리적 방향을 설명하는 일반 정보를 제공한다.

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"이고 값이 네 요소 목록을 포함하는 항목을 포함한다. 목록의 요소는 단위 쿼터니언의 구성 요소 [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"]의 값은 장치의 로컬 좌표계가 지구의 기준 좌표계와 관련하여 갖는 회전을 나타낸다. 이는 다음과 같은 3차원 데카르트 좌표계(x, y, z)로 정의된다:

x축은 y.z의 벡터곱으로, 지면에 접하고 동쪽을 가리킨다.
y축은 지면에 접하고 자북을 향한다.
z축은 하늘을 향하며 x축과 y축으로 이루어진 평면에 수직이다.

장치의 로컬 좌표계는 저수준 모션 센서에 대해 정의된 것과 동일하다. 이는 장치 좌표계이거나 화면 좌표계일 수 있다.

참고: 아래 그림은 장치의 로컬 좌표계와 지구의 기준 좌표계가 정렬된 경우를 나타낸다. 따라서 orientation sensor의 최신 판독값은 각 축에 대한 0(rad) [SI] 회전을 나타낸다.

AbsoluteOrientationSensor coordinate system.

5.2. RelativeOrientationSensor 모델

Relative Orientation Sensor 센서 타입은 Motion Sensors Explainer § relative-orientation에 설명된 센서를 나타낸다. 그 관련 확장 센서 인터페이스는 RelativeOrientationSensor이며, OrientationSensor의 하위 클래스이다. 그 관련 가상 센서 타입은 "relative-orientation"이다.

상대 방향 센서의 경우, 최신 판독값["quaternion"]의 값은 장치의 로컬 좌표계가 정지 기준 좌표계와 관련하여 갖는 회전을 나타낸다. 정지 기준 좌표계는 자이로스코프 센서가 도입하는 바이어스로 인해 드리프트할 수 있으므로, 센서가 제공하는 회전 값은 시간이 지남에 따라 드리프트할 수 있다.

정지 기준 좌표계는 센서를 호스팅하는 장치가 환경을 통해 이동하는 동안에도 정지 상태를 유지하는 관성 3차원 데카르트 좌표계로 정의된다.

장치의 로컬 좌표계는 저수준 모션 센서에 대해 정의된 것과 동일하다. 이는 장치 좌표계이거나 화면 좌표계일 수 있다.

참고: 상대 방향 센서 데이터는 자기장의 영향을 받지 않으므로 절대 방향 센서가 제공하는 데이터보다 더 정확할 수 있다.

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

장치 방향을 나타내는 단위 쿼터니언의 구성 요소를 포함하는 네 요소 FrozenArray를 반환한다. 즉, 이 속성은 this와 "quaternion"을 인수로 하여 최신 판독값에서 값 가져오기를 호출한 결과를 반환한다.

6.1.2. OrientationSensor.populateMatrix()

populateMatrix(targetMatrix) 메서드 단계는 다음과 같다:

targetMatrix가 Float32Array 또는 Float64Array 타입이고 크기가 16보다 작으면, "TypeError" 예외를 던지고 이 단계를 중단한다.
this와 "quaternion"을 인수로 하여 최신 판독값에서 값 가져오기를 호출한 결과를 quaternion으로 둔다.
quaternion이 null이면, "NotReadableError" DOMException을 던지고 이 단계를 중단한다.
quaternion[0], quaternion[1], quaternion[2], quaternion[3]으로 쿼터니언을 회전 행렬로 변환한 결과를 rotationMatrix로 둔다.
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 객체.

orientation_interface가 식별하는 인터페이스로 센서 정책 제어 기능 검사를 호출한 결과를 allowed로 둔다.
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 자동화를 확장하여 Orientation Sensor 전용 가상 센서 메타데이터를 제공한다.

8.1. 다른 명세에 대한 수정

이 명세는 다음과 같이 Device Orientation and Motion § 자동화와 통합된다.

orientation data reading 구문 분석 알고리즘은 다음과 같이 수정된다:

reading의 "alpha", "beta", "gamma" 키를 설정한 뒤, reading을 반환하기 전에 다음 단계를 추가한다:
1. reading["alpha"], reading["beta"], reading["gamma"]로 오일러 각도에서 쿼터니언 생성을 호출한 결과로 reading["quaternion"]을 설정한다.

참고: 이 명세는 현재 WebDriver에서 쿼터니언을 직접 지정하고(그 결과 쿼터니언에서 오일러 각도를 도출하는) 방법을 제공하지 않는다. 이 결정은 단순성을 위해, 그리고 자동화 사용자가 입력으로 오일러 각도를 사용하는 경우가 훨씬 더 많을 것이라는 가정(또는 특정 쿼터니언 값을 선택하고 그에 해당하는 오일러 각도 값을 직접 제공할 것이라는 가정)하에 이루어졌다. 쿼터니언 값을 직접 제공할 수 있기를 원하는 다른 사용 사례를 가진 사용자들의 의견은 이 명세의 이슈 추적기를 통해 환영한다.

8.2. Absolute Orientation Sensor 자동화

absolute-orientation 가상 센서 타입 및 타입별 가상 센서 메타데이터 맵의 해당 항목은 Device Orientation and Motion § 자동화에 정의되어 있다.

8.3. Relative Orientation Sensor 자동화

relative-orientation 가상 센서 타입 및 타입별 가상 센서 메타데이터 맵의 해당 항목은 Device Orientation and Motion § 자동화에 정의되어 있다.

9. 감사의 말

Generic Sensor API 작업을 해 준 Tobie Langel에게 감사한다.