Xamarin.Essentials: OrientationSensorXamarin.Essentials: OrientationSensor

La classe Capteur d’orientation vous permet de surveiller l’orientation d’un appareil dans l’espace tridimensionnel.The OrientationSensor class lets you monitor the orientation of a device in three dimensional space.

Notes

Cette classe permet de déterminer l’orientation d’un appareil dans un espace en 3D.This class is for determining the orientation of a device in 3D space. Si vous avez besoin de déterminer si l’écran de l’appareil vidéo est en mode portrait ou paysage, utilisez la propriété Orientation de l’objet ScreenMetrics disponible à partir de la classe DeviceDisplay.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.

Prise en mainGet started

Pour commencer à utiliser cette API, lisez le Guide de prise en main de Xamarin.Essentials pour vérifier que la bibliothèque est correctement installée et configurée dans vos projets.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.

Utilisation de Capteur d’orientationUsing OrientationSensor

Ajoutez une référence à Xamarin.Essentials dans votre classe :Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

OrientationSensor est activé en appelant la méthode Start pour surveiller les modifications apportées à l’orientation de l’appareil. Il est désactivé en appelant la méthode 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. Toutes les variations peuvent être écoutées via l’événement ReadingChanged.Any changes are sent back through the ReadingChanged event. Voici un exemple d’utilisation :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.
        }
    }
}

Les lectures OrientationSensor sont retournées sous la forme d’un Quaternion qui décrit l’orientation de l’appareil en fonction de deux systèmes de coordonnées 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:

L’appareil (en général, un téléphone ou une tablette) dispose d’un système de coordonnées 3D avec les axes suivants :The device (generally a phone or tablet) has a 3D coordinate system with the following axes:

  • L’axe X positif pointe vers la droite de l’écran en mode portrait.The positive X axis points to the right of the display in portrait mode.
  • L’axe Y positif pointe vers le haut de l’appareil en mode portrait.The positive Y axis points to the top of the device in portrait mode.
  • L’axe Z positif pointe en dehors de l’écran.The positive Z axis points out of the screen.

Le système de coordonnées 3D de la terre a les axes suivants :The 3D coordinate system of the Earth has the following axes:

  • L’axe X positif est la tangente de la surface de la terre et pointe vers l’est.The positive X axis is tangent to the surface of the Earth and points east.
  • L’axe Y positif est aussi la tangente de la surface de la terre et pointe vers le nord.The positive Y axis is also tangent to the surface of the Earth and points north.
  • L’axe Z positif est perpendiculaire à la surface de la terre et pointe vers le haut.The positive Z axis is perpendicular to the surface of the Earth and points up.

Quaternion décrit la rotation du système de coordonnées de l’appareil par rapport au système de coordonnées de la terre.The Quaternion describes the rotation of the device's coordinate system relative to the Earth's coordinate system.

Une valeur Quaternion est très étroitement liée à la rotation autour d’un axe.A Quaternion value is very closely related to rotation around an axis. Si un axe de rotation est le vecteur normalisé (ax, ay, az), et l’angle de rotation est Θ, alors les composants (X, Y, Z, W) du quaternion sont :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))

Il s’agit de systèmes de coordonnées droitiers, donc avec le pouce de la main droit pointée dans le sens positif de l’axe de rotation, la courbe des doigts indique la direction de rotation des angles positifs.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.

Exemples :Examples:

  • Lorsque l’appareil se trouve à plat sur une table avec son écran vers le haut, avec le bord supérieur de l’appareil (en mode portrait) pointant vers le nord, les deux systèmes de coordonnées sont alignés.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. La valeur Quaternion représente le quaternion d’identité (0, 0, 0, 1).The Quaternion value represents the identity quaternion (0, 0, 0, 1). Toutes les rotations peuvent être analysées par rapport à cette position.All rotations can be analyzed relative to this position.

  • Lorsque l’appareil se trouve à plat sur une table avec son écran vers le haut, avec le bord supérieur de l’appareil (en mode portrait) pointant vers l’ouest, la valeur Quaternion est (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). L’appareil a été pivoté de 90 degrés autour de l’axe Z de la terre.The device has been rotated 90 degrees around the Z axis of the Earth.

  • Lorsque l’appareil est maintenu à la verticale afin que le haut (en mode portrait) pointe vers le ciel et que l’arrière de l’appareil soit face au nord, l’appareil a été pivoté de 90 degrés autour de l’axe X.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. La valeur Quaternion est (0.707, 0, 0, 0.707).The Quaternion value is (0.707, 0, 0, 0.707).

  • Si l’appareil est positionné de façon à ce que son bord gauche soit sur une table et que le haut de l’appareil pointe vers le nord, l’appareil a été pivoté de –90 degrés autour de l’axe Y (ou 90 degrés autour de l’axe Y négatif).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). La valeur Quaternion est (0, -0.707, 0, 0.707).The Quaternion value is (0, -0.707, 0, 0.707).

Vitesse de capteurSensor Speed

  • Le plus rapide : obtenir les données de capteur aussi rapidement que possible (aucune garantie de retour sur le thread d’interface utilisateur).Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • Jeu : débit adapté aux jeux (aucune garantie de retour sur le thread d’interface utilisateur).Game – Rate suitable for games (not guaranteed to return on UI thread).
  • Normal : débit par défaut adapté aux changements d’orientation de l’écran.Normal – Default rate suitable for screen orientation changes.
  • UI : débit adapté à une interface utilisateur général.UI – Rate suitable for general user interface.

Si votre gestionnaire d’événements ne garantit pas l’exécution sur le thread d’interface utilisateur et si le gestionnaire d’événements doit accéder aux éléments de l’interface utilisateur, utilisez la méthode MainThread.BeginInvokeOnMainThread pour exécuter ce code sur le thread d’interface utilisateur.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