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;

Start メソッドを呼び出して OrientationSensor を有効にし、デバイスの向きの変更を監視します。無効にする場合は 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 の読み取り値が Quaternion の形式で返されます。これは、2 つの 3D 座標系に基づくデバイスの向きを表現しています。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:

  • デバイスが画面を上に向けてテーブルの上に平らに置かれ、デバイスの上部 (縦向きモード) が北を指している場合、2 つの座標系は揃っています。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 の値は単位四元数 (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

  • Fastest – センサー データを最高速度で取得します (UI スレッドに返ることが保証されません)。Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • Game – ゲームに適した速度です (UI スレッドに返ることが保証されません)。Game – Rate suitable for games (not guaranteed to return on UI thread).
  • Normal – 画面の向きの変更に適した既定の速度です。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