Xamarin.Essentials: OrientationSensor

Класс OrientationSensor позволяет наблюдать за ориентацией устройства в трехмерном пространстве.

Начало работы

Чтобы начать использовать этот API, ознакомьтесь с руководством по началу работы с Xamarin.Essentials, чтобы правильно настроить и установить библиотеку в проектах.

Использование OrientationSensor

Добавьте ссылку на Xamarin.Essentials в своем классе:

using Xamarin.Essentials;

OrientationSensor включается вызовом метода Start для отслеживания изменений в ориентации устройства и отключается методом Stop. Все изменения возвращаются через событие ReadingChanged. Вот простой пример использования:

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с описанием ориентации устройства в двух трехмерных системах координат:

Устройство (обычно это телефон или планшет) использует трехмерную систему координат со следующими осями:

• Положительное значение X обозначает направление вправо от экрана в книжной ориентации.
• Положительное значение Y обозначает направление вверх от устройства в книжной ориентации.
• Положительное значение Z обозначает направление вперед перпендикулярно экрану.

Трехмерная система координат относительно Земли имеет следующие оси:

• Положительное значение X указывает на восток по касательной к поверхности Земли.
• Положительное значение Y указывает на север по касательной к поверхности Земли.
• Положительное значение X указывает вверх перпендикулярно поверхности Земли.

Quaternion описывает вращение системы координат устройства по отношению к системе координат Земли.

Значение Quaternion очень тесно связано с поворотом вокруг оси. Если ось вращения обозначить нормализованным вектором (_x,_y,_z), а угол поворота — Θ, то компоненты кватерниона (X, Y, Z, W) вычисляются следующим образом:

(a_x·sin(Θ/2), a_y·sin(Θ/2), a_z·sin(Θ/2), cos(Θ/2)).

Это правосторонние системы координат: если направить большой палец правой руки в направлении положительного изменения координат по оси вращения, изгиб пальцев будет указывать направление вращения с положительным значением угла поворота.

Примеры:

• Если устройство лежит горизонтально на столе экраном вверх и при этом верхний край устройства (в книжной ориентации) указывает на север, эти системы координат совпадают. Значение Quaternion представляет единичный кватернион (0, 0, 0, 1). Все повороты можно анализировать относительно этой позиции.

• Если устройство лежит горизонтально на столе экраном вверх и при этом верхний край устройства (в книжной ориентации) указывает на запад, Quaternion принимает значение (0, 0, 0,707, 0,707). Это означает, что устройство повернуто на 90 градусов вокруг оси Z в системе координат Земли.

• Когда устройство удерживается вертикально так, что его верхняя часть (в книжной ориентации) направлена вверх, к небу, а задняя панель устройства расположена с северной стороны, устройство считается повернутым на 90 градусов вокруг оси X. Значение Quaternion равно (0,707, 0, 0, 0,707).

• Если устройство размещается так, что его левый край размещен на столе, а верхний край указывает на север, устройство считается повернутым на 90 градусов вокруг оси Y (или на 90 градусов вокруг отрицательной оси Y). Значение Quaternion равно (0, -0,707, 0, 0,707).

Скорость датчика

• Fastest (Максимальная) — максимально быстрое получение данных датчика (возврат в поток пользовательского интерфейса не гарантирован).
• Game (Игра) — скорость, подходящая для игр (возврат в поток пользовательского интерфейса не гарантирован).
• Normal (Нормальная) — скорость по умолчанию, которая подходит для изменений ориентации экрана.
• UI (Пользовательский интерфейс) — скорость, которая подходит для типичного пользовательского интерфейса.

Если нет гарантии, что обработчик событий будет запущен в потоке пользовательского интерфейса, и этому обработчику событий требуется доступ к элементам интерфейса, используйте метод MainThread.BeginInvokeOnMainThread для запуска кода в потоке пользовательского интерфейса.

API

• Исходный код OrientationSensor
• Документация по API для OrientationSensor