Xamarin.Essentials: OrientationSensorXamarin.Essentials: OrientationSensor

OrientationSensor 클래스를 사용하면 3차원 공간에서 디바이스의 방향을 모니터링할 수 있습니다.The OrientationSensor class lets you monitor the orientation of a device in three dimensional space.

참고

이 클래스는 3D 공간에서 디바이스의 방향을 확인하기 위한 것입니다.This class is for determining the orientation of a device in 3D space. 디바이스의 비디오 디스플레이가 세로 또는 가로 모드인지 확인해야 하는 경우 DeviceDisplay 클래스에서 제공되는 ScreenMetrics 개체의 Orientation 속성을 사용합니다.If you need to determine if the device's video display is in portrait or landscape mode, use the Orientation property of the ScreenMetrics object available from the DeviceDisplay class.

시작Get started

이 API를 사용하기 전에 라이브러리가 제대로 설치되고 프로젝트에 설정되어 있는지 확인하기 위해 Xamarin.Essentials에 대한 시작 가이드를 읽어보세요.To start using this API, read the getting started guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects.

OrientationSensor 사용Using OrientationSensor

클래스에서 Xamarin.Essentials에 대한 참조를 추가합니다.Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

OrientationSensor는 디바이스의 방향 변경 내용을 모니터링하기 위해 Start 메서드를 호출하여 사용되고, Stop 메서드를 호출하여 사용하지 않게 됩니다.The OrientationSensor is enabled by calling the Start method to monitor changes to the device's orientation, and disabled by calling the Stop method. ReadingChanged 이벤트를 통해 변경 내용을 다시 전송합니다.Any changes are sent back through the ReadingChanged event. 다음은 샘플 사용법입니다.Here is a sample usage:


public class OrientationSensorTest
{
    // Set speed delay for monitoring changes.
    SensorSpeed speed = SensorSpeed.UI;

    public OrientationSensorTest()
    {
        // Register for reading changes, be sure to unsubscribe when finished
        OrientationSensor.ReadingChanged += OrientationSensor_ReadingChanged;
    }

    void OrientationSensor_ReadingChanged(object sender, OrientationSensorChangedEventArgs e)
    {
        var data = e.Reading;
        Console.WriteLine($"Reading: X: {data.Orientation.X}, Y: {data.Orientation.Y}, Z: {data.Orientation.Z}, W: {data.Orientation.W}");
        // Process Orientation quaternion (X, Y, Z, and W)
    }

    public void ToggleOrientationSensor()
    {
        try
        {
            if (OrientationSensor.IsMonitoring)
                OrientationSensor.Stop();
            else
                OrientationSensor.Start(speed);
        }
        catch (FeatureNotSupportedException fnsEx)
        {
            // Feature not supported on device
        }
        catch (Exception ex)
        {
            // Other error has occurred.
        }
    }
}

OrientationSensor 판독값은 두 개의 3D 좌표계를 기준으로 디바이스의 방향을 설명하는 Quaternion 형식으로 다시 보고됩니다.OrientationSensor readings are reported back in the form of a Quaternion that describes the orientation of the device based on two 3D coordinate systems:

디바이스(일반적으로 휴대폰 또는 태블릿)에는 다음 축을 포함하는 3D 좌표계가 있습니다.The device (generally a phone or tablet) has a 3D coordinate system with the following axes:

  • 양수 X 축은 세로 모드에서 디스플레이 오른쪽을 가리킵니다.The positive X axis points to the right of the display in portrait mode.
  • 양수 Y 축은 세로 모드에서 디바이스의 위쪽을 가리킵니다.The positive Y axis points to the top of the device in portrait mode.
  • 양수 Z 축은 화면 밖을 가리킵니다.The positive Z axis points out of the screen.

지구의 3D 좌표계에는 다음 축이 있습니다.The 3D coordinate system of the Earth has the following axes:

  • 양수 X 축은 지구 표면에 접하고 동쪽을 가리킵니다.The positive X axis is tangent to the surface of the Earth and points east.
  • 양수 Y 축도 지구 표면에 접하고 북쪽을 가리킵니다.The positive Y axis is also tangent to the surface of the Earth and points north.
  • 양수 Z 축은 지구 표면에 수직이고 위쪽을 가리킵니다.The positive Z axis is perpendicular to the surface of the Earth and points up.

Quaternion은 지구 좌표계를 기준으로 디바이스 좌표계의 회전을 설명합니다.The Quaternion describes the rotation of the device's coordinate system relative to the Earth's coordinate system.

Quaternion 값은 축을 중심으로 하는 회전과 밀접한 관련이 있습니다.A Quaternion value is very closely related to rotation around an axis. 회전의 축이 정규화된 벡터(ax, ay, az)이고 회전 각도가 Θ인 경우 쿼터니언의 (X, Y, Z, W) 구성 요소는 다음과 같습니다.If an axis of rotation is the normalized vector (ax, ay, az), and the rotation angle is Θ, then the (X, Y, Z, W) components of the quaternion are:

(ax·sin(Θ/2), ay·sin(Θ/2), az·sin(Θ/2), cos(Θ/2))(ax·sin(Θ/2), ay·sin(Θ/2), az·sin(Θ/2), cos(Θ/2))

이는 오른손 좌표계이므로, 오른손 엄지손가락이 회전 축의 양수 방향을 가리킬 때 손가락 곡선은 양수 각도에 대한 회전 방향을 나타냅니다.These are right-hand coordinate systems, so with the thumb of the right hand pointed in the positive direction of the rotation axis, the curve of the fingers indicate the direction of rotation for positive angles.

예:Examples:

  • 디바이스가 화면이 위를 향하도록 테이블에 놓여 있고 디바이스의 위쪽(세로 모드)이 북쪽을 가리키는 경우 두 좌표계가 정렬됩니다.When the device lies flat on a table with its screen facing up, with the top of the device (in portrait mode) pointing north, the two coordinate systems are aligned. Quaternion 값은 ID 쿼터니언(0, 0, 0, 1)을 나타냅니다.The Quaternion value represents the identity quaternion (0, 0, 0, 1). 이 위치를 기준으로 모든 회전을 분석할 수 있습니다.All rotations can be analyzed relative to this position.

  • 디바이스가 화면이 위를 향하도록 테이블에 놓여 있고 디바이스의 위쪽(세로 모드)이 서쪽을 가리키는 경우 Quaternion 값은 (0, 0, 0.707, 0.707)입니다.When the device lies flat on a table with its screen facing up, and the top of the device (in portrait mode) pointing west, the Quaternion value is (0, 0, 0.707, 0.707). 디바이스가 지구의 Z 축을 중심으로 90도 회전되었습니다.The device has been rotated 90 degrees around the Z axis of the Earth.

  • 위쪽(세로 모드)이 하늘을 가리키고 디바이스의 뒤쪽이 북쪽을 향하도록 디바이스를 똑바로 드는 경우 디바이스가 X 축을 중심으로 90도 회전되었습니다.When the device is held upright so that the top (in portrait mode) points towards the sky, and the back of the device faces north, the device has been rotated 90 degrees around the X axis. Quaternion 값은 (0.707, 0, 0, 0.707)입니다.The Quaternion value is (0.707, 0, 0, 0.707).

  • 왼쪽 가장자리가 테이블 위에 오고 위쪽이 북쪽을 가리키도록 디바이스를 놓는 경우 디바이스가 Y 축을 중심으로 –90도(또는 음수 Y 축을 중심으로 90도) 회전되었습니다.If the device is positioned so its left edge is on a table, and the top points north, the device has been rotated –90 degrees around the Y axis (or 90 degrees around the negative Y axis). Quaternion 값은 (0, -0.707, 0, 0.707)입니다.The Quaternion value is (0, -0.707, 0, 0.707).

센서 속도Sensor Speed

  • 가장 빠름 – 센서 데이터를 가장 빠르게 가져옵니다(UI 스레드에 반환이 보장되지 않음).Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • 게임 – 게임에 적합한 속도(UI 스레드에 반환이 보장되지 않음).Game – Rate suitable for games (not guaranteed to return on UI thread).
  • 일반 - 화면 방향 변경에 적합한 기본 속도입니다.Normal – Default rate suitable for screen orientation changes.
  • UI - 일반 사용자 인터페이스에 적합한 속도입니다.UI – Rate suitable for general user interface.

이벤트 처리기가 UI 스레드에서 실행하도록 보장되지 않고 사용자 인터페이스 요소에 액세스해야 하는 경우 MainThread.BeginInvokeOnMainThread 메서드를 사용하여 UI 스레드에서 해당 코드를 실행하세요.If your event handler is not guaranteed to run on the UI thread, and if the event handler needs to access user-interface elements, use the MainThread.BeginInvokeOnMainThread method to run that code on the UI thread.

APIAPI