Delen via

Een gegevensprovider voor ruimtelijk bewustzijn maken — MRTK2

Het Spatial Awareness-systeem is een uitbreidbaar systeem om toepassingen te voorzien van gegevens over omgevingen in de echte wereld. Als u ondersteuning wilt toevoegen voor een nieuw hardwareplatform of een nieuwe vorm van spatial awareness-gegevens, is mogelijk een aangepaste gegevensprovider vereist.

In dit artikel wordt beschreven hoe u aangepaste gegevensproviders maakt, ook wel Spatial Observers genoemd, voor het spatial awareness-systeem. De voorbeeldcode die hier wordt weergegeven, is afkomstig van de SpatialObjectMeshObserverklasse-implementatie die handig is voor het laden van 3D-mesh-gegevens in de editor.

Opmerking

De volledige broncode die in dit voorbeeld wordt gebruikt, vindt u in de Assets/MRTK/Providers/ObjectMeshObserver map.

Naamruimte en mapstructuur

Gegevensproviders kunnen op twee manieren worden gedistribueerd:

  1. Invoegtoepassingen van derden
  2. Onderdeel van Microsoft Mixed Reality Toolkit

Het goedkeuringsproces voor het indienen van nieuwe gegevensproviders bij MRTK varieert per geval en wordt op het moment van het eerste voorstel meegedeeld. Voorstellen kunnen worden ingediend door een nieuw probleem met het type functieaanvraag te maken.

Invoegtoepassing van derden

Namespace

Gegevensproviders moeten een naamruimte hebben om mogelijke naamconflicten te beperken. Het wordt aanbevolen dat de naamruimte de volgende onderdelen bevat.

  • Bedrijfsnaam die de invoegtoepassing produceert
  • Functiegebied

Een gegevensprovider voor Spatial Awareness die is gemaakt en verzonden door het bedrijf Contoso kan bijvoorbeeld 'Contoso.MixedReality.Toolkit.SpatialAwareness' zijn.

Mapstructuur

Het wordt aanbevolen om de broncode voor gegevensproviders in te delen in een maphiërarchie, zoals wordt weergegeven in de volgende afbeelding.

Voorbeeld van mapstructuur

Waar de map ContosoSpatialAwareness de implementatie van de gegevensprovider bevat, bevat de map Editor de inspector (en een andere unity-editorspecifieke code) en bevat de map Profiles een of meer vooraf gemaakte profielscriptobjecten.

MRTK-inzending

Namespace

Als er een gegevensprovider voor ruimtelijk bewustzijn wordt verzonden naar de opslagplaats Mixed Reality Toolkit, moet de naamruimte beginnen met Microsoft.MixedReality.Toolkit (bijvoorbeeld: Microsoft.MixedReality.Toolkit.SpatialObjectMeshObserver)

en de code moet zich bevinden in een map onder MRTK/Providers (bijvoorbeeld MRTK/Providers/ObjectMeshObserver).

Mapstructuur

Alle code moet zich bevinden in een map onder MRTK/Providers (bijvoorbeeld MRTK/Providers/ObjectMeshObserver).

Het object ruimtelijke gegevens definiëren

De eerste stap bij het maken van een spatial awareness-gegevensprovider is het bepalen van het type gegevens (bijvoorbeeld meshes of vlakken) dat aan toepassingen wordt verstrekt.

Alle objecten met ruimtelijke gegevens moeten de IMixedRealitySpatialAwarenessObject interface implementeren.

De Mixed Reality Toolkit-basis biedt de volgende ruimtelijke objecten die kunnen worden gebruikt of uitgebreid in nieuwe gegevensproviders.

De gegevensprovider implementeren

Overname van interface en/of basisklasse opgeven

Alle spatial awareness-gegevensproviders moeten de IMixedRealitySpatialAwarenessObserver interface implementeren, die de minimale functionaliteit specificeert die vereist is voor het spatial awareness-systeem. De MRTK-basis bevat de BaseSpatialObserver klasse die een standaard implementatie van deze vereiste functionaliteit biedt.

public class SpatialObjectMeshObserver :
    BaseSpatialObserver,
    IMixedRealitySpatialAwarenessMeshObserver,
    IMixedRealityCapabilityCheck
{ }

Opmerking

De IMixedRealityCapabilityCheck interface wordt door de SpatialObjectMeshObserver klasse gebruikt om aan te geven dat deze ondersteuning biedt voor de mogelijkheid SpatialAwarenessMesh.

Het kenmerk MixedRealityDataProvider toepassen

Een belangrijke stap bij het maken van een spatial awareness-gegevensprovider is het toepassen van het MixedRealityDataProvider kenmerk op de klasse. Met deze stap kunt u het standaardprofiel en platform(en) instellen voor de gegevensprovider, wanneer deze is geselecteerd in het spatial awareness-profiel, naam, mappad en meer.

[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
{ }

De IMixedRealityDataProvider-methoden implementeren

Zodra de klasse is gedefinieerd, is de volgende stap het opgeven van de implementatie van de IMixedRealityDataProvider interface.

Opmerking

De BaseSpatialObserver klasse biedt via de BaseService klasse alleen een lege implementatie voor IMixedRealityDataProvider methoden. De details van deze methoden zijn over het algemeen gegevensproviderspecifiek.

De methoden die door de gegevensprovider moeten worden geïmplementeerd, zijn:

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

De logica van de gegevensprovider implementeren

De volgende stap is het toevoegen van de logica van de gegevensprovider door de specifieke interface van de gegevensprovider te implementeren, bijvoorbeeld IMixedRealitySpatialAwarenessMeshObserver. Dit gedeelte van de gegevensprovider is doorgaans platformspecifiek.

Meldingen voor wijziging van observatie

Om toepassingen toe te staan te reageren op wijzigingen in het begrip van de omgeving van het apparaat, genereert de gegevensprovider meldingsevenementen zoals gedefinieerd in de IMixedRealitySpatialAwarenessObservationtHandler<T> interface.

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

In de volgende code uit de SpatialObjectMeshObserver voorbeelden ziet u het verhogen en de gebeurtenis wanneer mesh-gegevens worden toegevoegd.

// 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;
}

Opmerking

De SpatialObjectMeshObserver klasse genereert OnObservationUpdated geen gebeurtenissen omdat het 3D-model slechts eenmaal wordt geladen. De implementatie in de WindowsMixedRealitySpatialMeshObserver klasse biedt een voorbeeld van het verhogen van een OnObservationUpdated gebeurtenis voor een waargenomen mesh.

Unity Profiler-instrumentatie toevoegen

Prestaties zijn essentieel in mixed reality-toepassingen. Elk onderdeel voegt een bepaalde hoeveelheid overhead toe waarvoor toepassingen rekening moeten houden. Hiertoe is het belangrijk dat alle providers van ruimtelijke bewustzijnsgegevens Unity Profiler-instrumentatie bevatten in de interne lus en vaak gebruikte codepaden.

Het wordt aanbevolen om het patroon te implementeren dat door MRTK wordt gebruikt bij het instrumenteren van aangepaste providers.

        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.
            }
        }

Opmerking

De naam die wordt gebruikt om de profilermarkering te identificeren, is willekeurig. MRTK gebruikt het volgende patroon.

"[product] className.methodName - optionele opmerking"

Het wordt aanbevolen dat aangepaste gegevensproviders een vergelijkbaar patroon volgen om de identificatie van specifieke onderdelen en methoden bij het analyseren van traceringen te vereenvoudigen.

Het profiel en de controle maken

In Mixed Reality Toolkit worden gegevensproviders geconfigureerd met behulp van profielen.

Het profiel definiëren

De profielinhoud moet de toegankelijke eigenschappen van de gegevensprovider spiegelen (bijvoorbeeld bijwerkinterval). Alle door de gebruiker configureerbare eigenschappen die in elke interface zijn gedefinieerd, moeten deel uitmaken van het profiel.

Basisklassen worden aangemoedigd als een nieuwe gegevensprovider een bestaande provider uitbreidt. De breidt bijvoorbeeld SpatialObjectMeshObserverProfile de MixedRealitySpatialAwarenessMeshObserverProfile uit om klanten in staat te stellen een 3D-model te leveren dat als de omgevingsgegevens moet worden gebruikt.

[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;
}

Het CreateAssetMenu kenmerk kan worden toegepast op de profielklasse, zodat klanten een profielexemplaren kunnen maken met behulp van het menu Create>Assets>Mixed Reality Toolkit>Profiles.

De inspector implementeren

Profielcontrole is de gebruikersinterface voor het configureren en weergeven van profielinhoud. Elke profielcontrole moet de BaseMixedRealityToolkitConfigurationProfileInspector klasse uitbreiden.

Het CustomEditor kenmerk informeert Unity over het type asset waarop de inspector van toepassing is.

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

Assemblydefinitie(s) maken

Mixed Reality Toolkit gebruikt assemblydefinitiebestanden (.asmdef) om afhankelijkheden tussen onderdelen op te geven en unity te helpen bij het verkorten van de compilatietijd.

Het wordt aanbevolen om assemblydefinitiebestanden te maken voor alle gegevensproviders en hun editoronderdelen.

Als u de mapstructuur in het vorige voorbeeld gebruikt, zijn er twee .asmdef-bestanden voor de gegevensprovider ContosoSpatialAwareness.

De eerste assemblydefinitie is voor de gegevensprovider. In dit voorbeeld wordt dit contosoSpatialAwareness genoemd en bevindt zich in de map ContosoSpatialAwareness van het voorbeeld. Deze assemblydefinitie moet een afhankelijkheid opgeven van Microsoft.MixedReality.Toolkit en andere assembly's waarvan deze afhankelijk is.

De definitie van de ContosoInputEditor-assembly geeft de profielcontrole en eventuele editorspecifieke code op. Dit bestand moet zich in de hoofdmap van de editorcode bevinden. In dit voorbeeld bevindt het bestand zich in de map ContosoSpatialAwareness\Editor. Deze assemblydefinitie bevat een verwijzing naar de ContosoSpatialAwareness-assembly en naar:

  • Microsoft.MixedReality.Toolkit
  • Microsoft.MixedReality.Toolkit. Editor. Inspecteurs
  • Microsoft.MixedReality.Toolkit. Editor. Utilities

De gegevensprovider registreren

Zodra de gegevensprovider is gemaakt, kan deze worden geregistreerd bij het spatial awareness-systeem dat in de toepassing moet worden gebruikt.

De ruimtelijke object mesh-waarnemer selecteren

Verpakking en distributie

Gegevensproviders die worden gedistribueerd als onderdelen van derden, hebben de specifieke details van de verpakking en distributie overgelaten aan de voorkeur van de ontwikkelaar. De meest voorkomende oplossing is waarschijnlijk om een .unitypackage te genereren en te distribueren via de Unity Asset Store.

Als een gegevensprovider wordt ingediend en geaccepteerd als onderdeel van het Microsoft Mixed Reality Toolkit-pakket, zal het Microsoft MRTK-team deze verpakken en distribueren als onderdeel van de MRTK-aanbiedingen.

Zie ook