Dela via

Skapa en systemdataleverantör för rumslig medvetenhet – MRTK2

  • Artikel

Spatial Awareness-systemet är ett utökningsbart system för att förse program med data om verkliga miljöer. Om du vill lägga till stöd för en ny maskinvaruplattform eller en ny form av Spatial Awareness-data kan en anpassad dataprovider krävas.

I den här artikeln beskrivs hur du skapar anpassade dataprovidrar, även kallade spatiala observatörer, för systemet för rumslig medvetenhet. Exempelkoden som visas här är från SpatialObjectMeshObserver klassimplementeringen som är användbar för att läsa in 3D-nätdata i redigeringsprogrammet.

Anteckning

Den fullständiga källkoden som används i det här exemplet finns i Assets/MRTK/Providers/ObjectMeshObserver mappen .

Namnområde och mappstruktur

Dataleverantörer kan distribueras på något av två sätt:

  1. Tillägg från tredje part
  2. En del av Microsoft Mixed Reality Toolkit

Godkännandeprocessen för inlämning av nya dataleverantörer till MRTK kommer att variera från fall till fall och kommer att meddelas vid tidpunkten för det ursprungliga förslaget. Förslag kan skickas genom att skapa ett nytt problem av typen Funktionsbegäran.

Tillägg från tredje part

Namnområde

Dataprovidrar måste ha ett namnområde för att minimera potentiella namnkollisioner. Vi rekommenderar att namnområdet innehåller följande komponenter.

  • Företagsnamn som producerar tillägget
  • Funktionsområde

En Spatial Awareness-dataprovider som skapats och levererats av Contoso-företaget kan till exempel vara "Contoso.MixedReality.Toolkit.SpatialAwareness".

Mappstrukturen

Vi rekommenderar att källkoden för dataproviders placeras i en mapphierarki enligt följande bild.

Exempel på mappstruktur

Om mappen ContosoSpatialAwareness innehåller implementeringen av dataprovidern innehåller mappen Redigerare inspektören (och annan specifik kod för Unity-redigeraren) och mappen Profiler innehåller ett eller flera färdiga objekt som kan skrivas i profilen.

MRTK-inlämning

Namnområde

Om en dataprovider för rumslig medvetenhet skickas till Mixed Reality Toolkit-lagringsplatsenmåste namnområdet börja med Microsoft.MixedReality.Toolkit (t.ex. Microsoft.MixedReality.Toolkit.SpatialObjectMeshObserver)

och koden ska finnas i en mapp under MRTK/Providers (till exempel MRTK/Providers/ObjectMeshObserver).

Mappstrukturen

All kod ska finnas i en mapp under MRTK/Providers (till exempel MRTK/Providers/ObjectMeshObserver).

Definiera det rumsliga dataobjektet

Det första steget i att skapa en Spatial Awareness-dataleverantör är att bestämma vilken typ av data (t.ex. nät eller plan) som den ska tillhandahålla till program.

Alla rumsliga dataobjekt måste implementera IMixedRealitySpatialAwarenessObject gränssnittet.

Den Mixed Reality Toolkit-grunden tillhandahåller följande rumsliga objekt som kan användas eller utökas i nya dataprovidrar.

Implementera dataprovidern

Ange arv av gränssnitt och/eller basklass

Alla dataprovidrar för rumslig medvetenhet måste implementera IMixedRealitySpatialAwarenessObserver gränssnittet, som anger den minsta funktionalitet som krävs av systemet för rumslig medvetenhet. MRTK-grunden innehåller BaseSpatialObserver klassen som tillhandahåller en standardimplementering av den här nödvändiga funktionen.

public class SpatialObjectMeshObserver :
    BaseSpatialObserver,
    IMixedRealitySpatialAwarenessMeshObserver,
    IMixedRealityCapabilityCheck
{ }

Anteckning

Gränssnittet IMixedRealityCapabilityCheck används av SpatialObjectMeshObserver klassen för att ange att det ger stöd för SpatialAwarenessMesh-funktionen.

Använda attributet MixedRealityDataProvider

Ett viktigt steg i att skapa en Spatial Awareness-dataprovider är att tillämpa MixedRealityDataProvider attributet på klassen . Med det här steget kan du ange standardprofilen och plattformarna för dataprovidern, när de väljs i profilen Rumslig medvetenhet samt Namn, mappsökväg med mera.

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

Implementera metoderna IMixedRealityDataProvider

När klassen har definierats är nästa steg att tillhandahålla implementeringen av IMixedRealityDataProvider gränssnittet.

Anteckning

Klassen BaseSpatialObserver , via BaseService -klassen, tillhandahåller endast en tom implementering för IMixedRealityDataProvider metoder. Informationen om dessa metoder är vanligtvis dataleverantörsspecifika.

De metoder som ska implementeras av dataprovidern är:

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

Implementera dataproviderlogik

Nästa steg är att lägga till logiken för dataprovidern genom att implementera det specifika dataprovidergränssnittet, till exempel IMixedRealitySpatialAwarenessMeshObserver. Den här delen av dataleverantören är vanligtvis plattformsspecifik.

Meddelanden om observationsändring

För att program ska kunna svara på ändringar i enhetens förståelse av miljön genererar dataleverantören meddelandehändelser enligt definitionen i IMixedRealitySpatialAwarenessObservationtHandler<T> gränssnittet.

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

Följande kod från exemplen SpatialObjectMeshObserver visar höjning och händelse när nätdata läggs till.

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

Anteckning

Klassen SpatialObjectMeshObserver genererar OnObservationUpdated inte händelser eftersom 3D-modellen bara läses in en gång. Implementeringen i WindowsMixedRealitySpatialMeshObserver klassen är ett exempel på hur du skapar en OnObservationUpdated händelse för ett observerat nät.

Lägg till Unity Profiler-instrumentation

Prestanda är avgörande i program för mixad verklighet. Varje komponent lägger till en viss mängd omkostnader som program måste ta hänsyn till. Därför är det viktigt att alla dataproviders för rumslig medvetenhet innehåller Unity Profiler-instrumentation i den inre loopen och ofta använda kodsökvägar.

Vi rekommenderar att du implementerar det mönster som används av MRTK när du instrumenterar anpassade providrar.

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

Anteckning

Namnet som används för att identifiera profilerarmarkören är godtyckligt. MRTK använder följande mönster.

"[product] className.methodName – valfri anteckning"

Vi rekommenderar att anpassade dataprovidrar följer ett liknande mönster för att förenkla identifieringen av specifika komponenter och metoder vid analys av spårningar.

Skapa profilen och kontrollanten

I Mixed Reality Toolkit konfigureras dataprovidrar med hjälp av profiler.

Definiera profilen

Profilinnehållet bör spegla dataleverantörens tillgängliga egenskaper (till exempel uppdateringsintervall). Alla användarkonfigurerbara egenskaper som definierats i varje gränssnitt ska finnas i profilen.

Basklasser uppmuntras om en ny dataprovider utökar en befintlig provider. Till exempel SpatialObjectMeshObserverProfile utökar MixedRealitySpatialAwarenessMeshObserverProfile för att göra det möjligt för kunder att tillhandahålla en 3D-modell som ska användas som miljödata.

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

Attributet CreateAssetMenu kan tillämpas på profilklassen så att kunder kan skapa en profilinstans med hjälp av menyn Skapa>tillgångar>Mixed Reality Toolkit-profiler>.

Implementera inspektören

Profilkontrollanter är användargränssnittet för att konfigurera och visa profilinnehåll. Varje profilkontroll bör utöka BaseMixedRealityToolkitConfigurationProfileInspector klassen.

Attributet CustomEditor informerar Unity om vilken typ av tillgång som kontrollanten gäller för.

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

Skapa sammansättningsdefinitioner

Mixed Reality Toolkit använder sammansättningsdefinitionsfiler (.asmdef) för att ange beroenden mellan komponenter samt för att hjälpa Unity att minska kompileringstiden.

Vi rekommenderar att sammansättningsdefinitionsfiler skapas för alla dataleverantörer och deras redigerarkomponenter.

Med hjälp av mappstrukturen i det tidigare exemplet skulle det finnas två .asmdef-filer för ContosoSpatialAwareness-dataprovidern.

Den första sammansättningsdefinitionen gäller för dataprovidern. I det här exemplet kallas det ContosoSpatialAwareness och finns i exemplets contosoSpatialAwareness-mapp . Den här sammansättningsdefinitionen måste ange ett beroende för Microsoft.MixedReality.Toolkit och andra sammansättningar som den är beroende av.

Sammansättningsdefinitionen ContosoInputEditor anger profilkontrollen och eventuell redigeringsspecifik kod. Den här filen måste finnas i rotmappen i redigeringskoden. I det här exemplet finns filen i mappen ContosoSpatialAwareness\Editor . Den här sammansättningsdefinitionen innehåller en referens till ContosoSpatialAwareness-sammansättningen samt:

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

Registrera dataprovidern

När dataprovidern har skapats kan den registreras med det spatiala medvetenhetssystemet som ska användas i programmet.

Välja den spatiala objektnätsobservatören

Paketering och distribution

Dataleverantörer som distribueras som komponenter från tredje part har specifik information om paketering och distribution som utvecklare föredrar. Förmodligen är den vanligaste lösningen att generera ett .unitypackage och distribuera via Unity Asset Store.

Om en dataleverantör skickas in och godkänns som en del av Microsoft Mixed Reality Toolkit-paketet paketeras och distribueras Microsoft MRTK-teamet som en del av MRTK-erbjudandena.

Se även