Création d’un fournisseur de données de système de sensibilisation spatiale — MRTK2

Le système de sensibilisation spatiale est un système extensible permettant de fournir des applications avec des données sur des environnements réels. Pour ajouter la prise en charge d’une nouvelle plateforme matérielle ou d’une nouvelle forme de données Spatial Awareness, un fournisseur de données personnalisé peut être requis.

Cet article explique comment créer des fournisseurs de données personnalisés, également appelés Observateurs spatiaux, pour le système de sensibilisation spatiale. L’exemple de code illustré ici provient de l’implémentation SpatialObjectMeshObserver de classe qui est utile pour charger des données de maillage 3D dans l’éditeur.

Notes

Le code source complet utilisé dans cet exemple se trouve dans le Assets/MRTK/Providers/ObjectMeshObserver dossier.

Structure d’espaces de noms et de dossiers

Les fournisseurs de données peuvent être distribués de deux façons :

  1. Modules complémentaires tiers
  2. Partie du Kit de ressources Microsoft Mixed Reality

Le processus d’approbation pour les soumissions de nouveaux fournisseurs de données à MRTK varie selon le cas et sera communiqué au moment de la proposition initiale. Les propositions peuvent être soumises en créant un problème de type demande de fonctionnalité.

Module complémentaire tiers

Espace de noms

Les fournisseurs de données doivent disposer d’un espace de noms pour atténuer les collisions de noms potentielles. Il est recommandé que l’espace de noms inclut les composants suivants.

  • Nom de la société produisant le module complémentaire
  • Domaine de fonctionnalité

Par exemple, un fournisseur de données Spatial Awareness créé et fourni par la société Contoso peut être « Contoso.MixedReality.Toolkit.SpatialAwareness ».

Structure de dossiers

Il est recommandé que le code source des fournisseurs de données soit retardé dans une hiérarchie de dossiers, comme illustré dans l’image suivante.

Exemple de structure de dossiers

Où le dossier ContosoSpatialAwareness contient l’implémentation du fournisseur de données, le dossier Éditeur contient l’inspecteur (et tout autre code spécifique à l’éditeur Unity) et le dossier Profils contient un ou plusieurs objets prédéfinis de script de profil.

Soumission MRTK

Espace de noms

Si un fournisseur de données de système de sensibilisation spatiale est soumis au dépôt Mixed Reality Toolkit, l’espace de noms doit commencer par Microsoft.MixedReality.Toolkit (par exemple: Microsoft.MixedReality.Toolkit.SpatialObjectMeshObserver)

et le code doit se trouver dans un dossier sous MRTK/Providers (ex: MRTK/Providers/ObjectMeshObserver).

Structure de dossiers

Tout le code doit se trouver dans un dossier sous MRTK/Providers (ex: MRTK/Providers/ObjectMeshObserver).

Définir l’objet de données spatiales

La première étape de la création d’un fournisseur de données Spatial Awareness détermine le type de données (par exemple, les maillages ou les plans) qu’il fournira aux applications.

Tous les objets de données spatiales doivent implémenter l’interface IMixedRealitySpatialAwarenessObject .

La base de ressources Mixed Reality fournit les objets spatiaux suivants qui peuvent être utilisés ou étendus dans de nouveaux fournisseurs de données.

Implémenter le fournisseur de données

Spécifier l’héritage de l’interface et/ou de la classe de base

Tous les fournisseurs de données Spatial Awareness doivent implémenter l’interface IMixedRealitySpatialAwarenessObserver , qui spécifie les fonctionnalités minimales requises par le système de sensibilisation spatiale. La fondation MRTK inclut la BaseSpatialObserver classe qui fournit une implémentation par défaut de cette fonctionnalité requise.

public class SpatialObjectMeshObserver :
    BaseSpatialObserver,
    IMixedRealitySpatialAwarenessMeshObserver,
    IMixedRealityCapabilityCheck
{ }

Notes

L’interface IMixedRealityCapabilityCheck est utilisée par la SpatialObjectMeshObserver classe pour indiquer qu’elle prend en charge la fonctionnalité SpatialAwarenessMesh.

Appliquer l’attribut MixedRealityDataProvider

Une étape clé de la création d’un fournisseur de données Spatial Awareness consiste à appliquer l’attribut MixedRealityDataProvider à la classe. Cette étape permet de définir le profil et les plateformes par défaut pour le fournisseur de données, lorsqu’il est sélectionné dans le profil De sensibilisation spatiale, ainsi que le nom, le chemin d’accès aux dossiers et bien plus encore.

[MixedRealityDataProvider(
    typeof(IMixedRealitySpatialAwarenessSystem),
    SupportedPlatforms.WindowsEditor | SupportedPlatforms.MacEditor | SupportedPlatforms.LinuxEditor,
    "Spatial Object Mesh Observer",
    "ObjectMeshObserver/Profiles/DefaultObjectMeshObserverProfile.asset",
    "MixedRealityToolkit.Providers")]
public class SpatialObjectMeshObserver :
    BaseSpatialObserver,
    IMixedRealitySpatialAwarenessMeshObserver,
    IMixedRealityCapabilityCheck
{ }

Implémenter les méthodes IMixedRealityDataProvider

Une fois la classe définie, l’étape suivante consiste à fournir l’implémentation de l’interface IMixedRealityDataProvider .

Notes

La BaseSpatialObserver classe, via la BaseService classe, fournit uniquement des implémentations vides pour IMixedRealityDataProvider les méthodes. Les détails de ces méthodes sont généralement spécifiques au fournisseur de données.

Les méthodes qui doivent être implémentées par le fournisseur de données sont les suivantes :

  • Destroy()
  • Disable()
  • Enable()
  • Initialize()
  • Reset()
  • Update()

Implémenter la logique du fournisseur de données

L’étape suivante consiste à ajouter la logique du fournisseur de données en implémentant l’interface de fournisseur de données spécifique, par exemple IMixedRealitySpatialAwarenessMeshObserver. Cette partie du fournisseur de données sera généralement spécifique à la plateforme.

Notifications de modification d’observation

Pour permettre aux applications de répondre aux modifications apportées à la compréhension de l’environnement de l’appareil, le fournisseur de données déclenche des événements de notification comme défini dans l’interface IMixedRealitySpatialAwarenessObservationtHandler<T> .

  • OnObservationAdded()
  • OnObservationRemoved()
  • OnObservationUpdated()

Le code suivant des exemples illustre la levée et l’événement lors de l’ajout SpatialObjectMeshObserver de données de maillage.

// The data to be sent when mesh observation events occur.
// This member variable is initialized as part of the Initialize() method.
private MixedRealitySpatialAwarenessEventData<SpatialAwarenessMeshObject> meshEventData = null;

/// <summary>
/// Sends the observations using the mesh data contained within the configured 3D model.
/// </summary>
private void SendMeshObjects()
{
    if (!sendObservations) { return; }

    if (spatialMeshObject != null)
    {
        MeshFilter[] meshFilters = spatialMeshObject.GetComponentsInChildren<MeshFilter>();
        for (int i = 0; i < meshFilters.Length; i++)
        {
            SpatialAwarenessMeshObject meshObject = SpatialAwarenessMeshObject.Create(
                meshFilters[i].sharedMesh,
                MeshPhysicsLayer,
                $"Spatial Object Mesh {currentMeshId}",
                currentMeshId,
                ObservedObjectParent);

            meshObject.GameObject.transform.localPosition = meshFilters[i].transform.position;
            meshObject.GameObject.transform.localRotation = meshFilters[i].transform.rotation;

            ApplyMeshMaterial(meshObject);

            meshes.Add(currentMeshId, meshObject);

            // Initialize the meshEventData variable with data for the added event.
            meshEventData.Initialize(this, currentMeshId, meshObject);
            // Raise the event via the spatial awareness system.
            SpatialAwarenessSystem?.HandleEvent(meshEventData, OnMeshAdded);

            currentMeshId++;
        }
    }

    sendObservations = false;
}

Notes

La SpatialObjectMeshObserver classe ne déclenche OnObservationUpdated pas d’événements, car le modèle 3D n’est chargé qu’une seule fois. L’implémentation dans la WindowsMixedRealitySpatialMeshObserver classe fournit un exemple de déclenchement d’un OnObservationUpdated événement pour un maillage observé.

Ajouter l’instrumentation Unity Profiler

Les performances sont essentielles dans les applications de réalité mixte. Chaque composant ajoute une certaine quantité de surcharge pour laquelle les applications doivent tenir compte. À cette fin, il est important que tous les fournisseurs de données de sensibilisation spatiale contiennent l’instrumentation Unity Profiler dans la boucle interne et les chemins de code fréquemment utilisés.

Il est recommandé d’implémenter le modèle utilisé par MRTK lors de l’instrumentation de fournisseurs personnalisés.

        private static readonly ProfilerMarker UpdateObserverPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealitySpatialMeshObserver.UpdateObserver");

        /// <summary>
        /// Requests updates from the surface observer.
        /// </summary>
        private void UpdateObserver()
        {
            using (UpdateObserverPerfMarker.Auto())
            {
                // Code to be measured.
            }
        }

Notes

Le nom utilisé pour identifier le marqueur du profileur est arbitraire. MRTK utilise le modèle suivant.

« [product] className.methodName - note facultative »

Il est recommandé que les fournisseurs de données personnalisés suivent un modèle similaire pour simplifier l’identification des composants et méthodes spécifiques lors de l’analyse des traces.

Créer le profil et l’inspecteur

Dans Mixed Reality Toolkit, les fournisseurs de données sont configurés à l’aide de profils.

Définir le profil

Le contenu du profil doit mettre en miroir les propriétés accessibles du fournisseur de données (par exemple, intervalle de mise à jour). Toutes les propriétés configurables par l’utilisateur définies dans chaque interface doivent être contenues avec le profil.

Les classes de base sont encouragées si un nouveau fournisseur de données étend un fournisseur existant. Par exemple, l’extension SpatialObjectMeshObserverProfileMixedRealitySpatialAwarenessMeshObserverProfile permet aux clients de fournir un modèle 3D à utiliser comme données d’environnement.

[CreateAssetMenu(
    menuName = "Mixed Reality Toolkit/Profiles/Spatial Object Mesh Observer Profile",
    fileName = "SpatialObjectMeshObserverProfile",
    order = 100)]
public class SpatialObjectMeshObserverProfile : MixedRealitySpatialAwarenessMeshObserverProfile
{
    [SerializeField]
    [Tooltip("The model containing the desired mesh data.")]
    private GameObject spatialMeshObject = null;

    /// <summary>
    /// The model containing the desired mesh data.
    /// </summary>
    public GameObject SpatialMeshObject => spatialMeshObject;
}

L’attribut CreateAssetMenu peut être appliqué à la classe de profil pour permettre aux clients de créer une instance de profil à l’aide du menu Créer> desressources> Mixed RealityDes profilsde kit de ressources>.

Implémenter l’inspecteur

Les inspecteurs de profil sont l’interface utilisateur permettant de configurer et d’afficher le contenu du profil. Chaque inspecteur de profil doit étendre la BaseMixedRealityToolkitConfigurationProfileInspector classe.

L’attribut CustomEditor informe Unity du type de ressource auquel l’inspecteur s’applique.

[CustomEditor(typeof(SpatialObjectMeshObserverProfile))]
public class SpatialObjectMeshObserverProfileInspector : BaseMixedRealityToolkitConfigurationProfileInspector
{ }

Créer des définitions d’assembly

Mixed Reality Toolkit utilise des fichiers de définition d’assembly (.asmdef) pour spécifier des dépendances entre les composants, ainsi que pour aider Unity à réduire le temps de compilation.

Il est recommandé de créer des fichiers de définition d’assembly pour tous les fournisseurs de données et leurs composants éditeurs.

À l’aide de la structure de dossiers dans l’exemple précédent, il y aurait deux fichiers .asmdef pour le fournisseur de données ContosoSpatialAwareness.

La première définition d’assembly est destinée au fournisseur de données. Pour cet exemple, il est appelé ContosoSpatialAwareness et se trouve dans le dossier ContosoSpatialAwareness de l’exemple. Cette définition d’assembly doit spécifier une dépendance sur Microsoft.MixedReality.Toolkit et les autres assemblys sur lesquels il dépend.

La définition d’assembly ContosoInputEditor spécifie l’inspecteur de profil et tout code spécifique à l’éditeur. Ce fichier doit se trouver dans le dossier racine du code de l’éditeur. Dans cet exemple, le fichier se trouve dans le dossier ContosoSpatialAwareness\Editor . Cette définition d’assembly contient une référence à l’assembly ContosoSpatialAwareness ainsi que :

  • Microsoft.MixedReality.Toolkit
  • Microsoft.MixedReality.Toolkit.Editor.Inspectors
  • Microsoft.MixedReality.Toolkit.Editor.Utilities

Inscrire le fournisseur de données

Une fois créé, le fournisseur de données peut être inscrit auprès du système de sensibilisation spatiale à utiliser dans l’application.

Sélection de l’observateur de maillage d’objet spatial

Empaquetage et distribution

Les fournisseurs de données distribués en tant que composants tiers ont les détails spécifiques de l’empaquetage et de la distribution laissés à la préférence du développeur. Probablement, la solution la plus courante consiste à générer un .unitypackage et à distribuer via unity Asset Store.

Si un fournisseur de données est envoyé et accepté dans le cadre du package Microsoft Mixed Reality Toolkit, l’équipe Microsoft MRTK le packagera et la distribuera dans le cadre des offres MRTK.

Voir aussi