Een gegevensprovider voor ruimtelijk bewustzijnssysteem maken — MRTK2

  • Artikel

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, ook wel Spatial Observers genoemd, maakt 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.

Notitie

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 oorspronkelijke voorstel gecommuniceerd. Voorstellen kunnen worden ingediend door een nieuw probleem met het type functieaanvraag te maken.

Invoegtoepassing van derden

Naamruimte

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 eventuele andere specifieke code van de Unity-editor) en de map Profiles een of meer vooraf gemaakte profielscriptobjecten.

MRTK-inzending

Naamruimte

Als 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 in een map onder MRTK/Providers bevinden (bijvoorbeeld MRTK/Providers/ObjectMeshObserver).

Mapstructuur

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

Het ruimtelijke gegevensobject definiëren

De eerste stap bij het maken van een gegevensprovider voor spatial awareness 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 providers van spatial awareness-gegevens 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
{ }

Notitie

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, indien geselecteerd in het spatial awareness-profiel, evenals 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 bieden van de implementatie van de IMixedRealityDataProvider interface.

Notitie

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

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.

Wijzigingsmeldingen voor observatie

Om toepassingen in staat te stellen te reageren op wijzigingen in het inzicht van het apparaat in de omgeving, genereert de gegevensprovider meldingen zoals gedefinieerd in de IMixedRealitySpatialAwarenessObservationtHandler<T> interface.

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

De volgende code uit de SpatialObjectMeshObserver voorbeelden demonstreert het genereren en 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;
}

Notitie

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. Hiervoor is het belangrijk dat alle gegevensproviders voor ruimtelijk bewustzijn 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.
            }
        }

Notitie

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 te vereenvoudigen bij het analyseren van traceringen.

Het profiel en de inspector 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 weerspiegelen (bijvoorbeeld: update-interval). 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 kan 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> menuCreate 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
{ }

Assembly-definitie(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.

Met behulp van de mapstructuur in het eerdere voorbeeld zijn er twee ASMDEF-bestanden voor de gegevensprovider ContosoSpatialAwareness.

De eerste assembly-definitie is voor de gegevensprovider. In dit voorbeeld heet het ContosoSpatialAwareness en bevindt deze 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.

In de definitie van de ContosoInputEditor-assembly worden de profielcontrole en eventuele editorspecifieke code opgegeven. 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:

  • Microsoft.MixedReality.Toolkit
  • Microsoft.MixedReality.Toolkit.Editor.Inspectors
  • 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 waarnemer van het ruimtelijk object mesh 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 het genereren van een .unitypackage en het 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 inpakken en distribueren als onderdeel van de MRTK-aanbiedingen.

Zie ook