Panoramica dell'SDK per la comprensione della scenaScene understanding SDK overview

La comprensione della scena trasforma i dati dei sensori di ambiente non strutturati che il dispositivo della realtà mista acquisisce e li converte in una rappresentazione astratta potente.Scene understanding transforms the unstructured environment sensor data that your Mixed Reality device captures and converts it into a powerful abstract representation. L'SDK funge da livello di comunicazione tra l'applicazione e la scena che comprende il Runtime.The SDK acts as the communication layer between your application and the Scene Understanding runtime. Ha lo scopo di simulare costrutti standard esistenti, ad esempio grafici della scena 3D per le rappresentazioni 3D e rettangoli e pannelli 2D per le applicazioni 2D.It's aimed to mimic existing standard constructs, such as 3D scene graphs for 3D representations, and 2D rectangles and panels for 2D applications. Mentre la scena dei costrutti che comprendono le simulazioni verrà mappata a Framework concreti, in generale SceneUnderstanding è un Framework agnostico che consente l'interoperabilità tra diversi Framework che interagiscono con essa.While the constructs Scene Understanding mimics will map to concrete frameworks, in general SceneUnderstanding is framework agnostic allowing for interoperability between varied frameworks that interact with it. Poiché la comprensione della scena evolve il ruolo dell'SDK è garantire che le nuove rappresentazioni e funzionalità continuino a essere esposte in un framework unificato.As Scene Understanding evolves the role of the SDK is to ensure new representations and capabilities continue to be exposed within a unified framework. In questo documento si introdurranno innanzitutto concetti di alto livello che consentiranno di acquisire familiarità con l'ambiente di sviluppo o l'utilizzo e quindi fornire una documentazione più dettagliata per classi e costrutti specifici.In this document, we will first introduce high-level concepts that will help you get familiar with the development environment/usage and then provide more detailed documentation for specific classes and constructs.

Dove è possibile ottenere l'SDK?Where do I get the SDK?

SceneUnderstanding SDK è scaricabile tramite NuGet.The SceneUnderstanding SDK is downloadable via NuGet.

SDK di SceneUnderstandingSceneUnderstanding SDK

Nota: la versione più recente dipende dai pacchetti di anteprima ed è necessario abilitare i pacchetti in versione non definitiva per visualizzarli.Note: the latest release depends on preview packages and you'll need to enable pre-release packages to see it.

Per la versione 0.5.2022-RC e versioni successive, la comprensione della scena supporta le proiezioni di linguaggio per C# e C++ che consentono alle applicazioni di sviluppare applicazioni per piattaforme Win32 o UWP.For version 0.5.2022-rc and later, Scene Understanding supports language projections for C# and C++ allowing applications to develop applications for Win32 or UWP platforms. A partire da questa versione, SceneUnderstanding supporta Unity support in-Editor, che blocca SceneObserver, usato esclusivamente per la comunicazione con HoloLens2.As of this version, SceneUnderstanding supports unity in-editor support barring the SceneObserver, which is used solely for communicating with HoloLens2.

SceneUnderstanding richiede Windows SDK versione 18362 o successiva.SceneUnderstanding requires Windows SDK version 18362 or higher.

Se si usa l'SDK in un progetto Unity, usare NuGet per Unity per installare il pacchetto nel progetto.If you're using the SDK in a Unity project, use NuGet for Unity to install the package into your project.

Panoramica dei concettiConceptual Overview

ScenaThe Scene

Il dispositivo di realtà mista sta integrando costantemente le informazioni relative a ciò che viene visualizzato nell'ambiente in uso.Your mixed reality device is constantly integrating information about what it sees in your environment. La comprensione della scena incanala tutte queste origini dati e produce un'unica astrazione coesiva.Scene Understanding funnels all of these data sources and produces one single cohesive abstraction. La comprensione della scena genera scene, ovvero una composizione di SceneObjects che rappresenta un'istanza di un singolo elemento, ad esempio una parete/soffitto/piano. Gli oggetti scena stessi sono una composizione di [SceneComponents, che rappresenta parti più granulari che compongono questo SceneObject.Scene Understanding generates Scenes, which are a composition of SceneObjects that represent an instance of a single thing, (for example, a wall/ceiling/floor.) Scene Objects themselves are a composition of [SceneComponents, which represent more granular pieces that make up this SceneObject. Esempi di componenti sono i quad e i mesh, ma in futuro potrebbero rappresentare i rettangoli di delimitazione, le mesh dei conflitti, i metadati e così via.Examples of components are quads and meshes, but in the future could represent bounding boxes, collision meshes, metadata etc.

Il processo di conversione dei dati dei sensori non elaborati in una scena è un'operazione potenzialmente costosa che può richiedere secondi per spazi medi (~ 10x10m) a minuti per spazi di grandi dimensioni (~ 50x50m) e pertanto non è un elemento che viene calcolato dal dispositivo senza richiesta di applicazione.The process of converting the raw sensor data into a Scene is a potentially expensive operation that could take seconds for medium spaces (~10x10m) to minutes for large spaces (~50x50m) and therefore it is not something that is being computed by the device without application request. La generazione della scena viene invece attivata dall'applicazione su richiesta.Instead, Scene generation is triggered by your application on demand. La classe SceneObserver dispone di metodi statici che consentono di calcolare o deserializzare una scena, con cui è possibile enumerare/interagire.The SceneObserver class has static methods that can Compute or Deserialize a scene, which you can then enumerate/interact with. L'azione "calcolo" viene eseguita su richiesta ed eseguita sulla CPU, ma in un processo separato (il driver della realtà mista).The "Compute" action is executed on-demand and executes on the CPU but in a separate process (the Mixed Reality Driver). Tuttavia, mentre si esegue il calcolo in un altro processo, i dati della scena risultanti vengono archiviati e conservati nell'applicazione nell'oggetto scena.However, while we do compute in another process the resulting Scene data is stored and maintained in your application in the Scene object.

Di seguito è riportato un diagramma che illustra il flusso del processo e Mostra esempi di due applicazioni che si confrontano con la scena Understanding Runtime.Below is a diagram that illustrates this process flow and shows examples of two applications interfacing with the Scene Understanding runtime.

Diagramma di processo

Sul lato sinistro è presente un diagramma del runtime di realtà mista, che è sempre attivo e in esecuzione nel proprio processo.On the left-hand side is a diagram of the mixed reality runtime, which is always on and running in its own process. Questo runtime è responsabile dell'esecuzione del rilevamento dei dispositivi, del mapping spaziale e di altre operazioni che la comprensione della scena USA per comprendere e ragionare in tutto il mondo.This runtime is responsible for performing device tracking, spatial mapping, and other operations that Scene Understanding uses to understand and reason about the world around you. Sul lato destro del diagramma sono illustrate due applicazioni teoriche che fanno uso della comprensione della scena.On the right side of the diagram, we show two theoretical applications that make use of Scene Understanding. La prima interfaccia dell'applicazione con MRTK, che usa la scena Understanding SDK internamente, la seconda app calcola e usa due istanze separate della scena.The first application interfaces with MRTK, which uses the Scene Understanding SDK internally, the second app computes and uses two separate scene instances. Tutte e tre le scene in questo diagramma generano istanze distinte delle scene, il driver non tiene traccia dello stato globale condiviso tra le applicazioni e gli oggetti scena in un'unica scena non è stato trovato in un altro.All three Scenes in this diagram generate distinct instances of the scenes, the driver isn't tracking global state that is shared between applications and Scene Objects in one scene aren't found in another. La comprensione della scena fornisce un meccanismo per tenere traccia nel tempo, ma questa operazione viene eseguita tramite l'SDK.Scene Understanding does provide a mechanism to track over time, but this is done using the SDK. Il codice di rilevamento è già in esecuzione nell'SDK nel processo dell'app.Tracking code is already running in the SDK in your app's process.

Poiché ogni scena archivia i dati nello spazio di memoria dell'applicazione, si può presupporre che tutte le funzioni dell'oggetto scene o dei dati interni vengano sempre eseguite nel processo dell'applicazione.Because each Scene stores it's data in your application's memory space, you can assume that all function of the Scene object or it's internal data is always executed in your application's process.

LayoutLayout

Per lavorare con la comprensione della scena, può essere utile conoscere e comprendere il modo in cui il runtime rappresenta i componenti in modo logico e fisico.To work with Scene Understanding, it may be valuable to know and understand how the runtime represents components logically and physically. La scena rappresenta i dati con un layout specifico che è stato scelto per essere semplice mantenendo una struttura sottostante flessibile per soddisfare i requisiti futuri senza che siano necessarie revisioni principali.The Scene represents data with a specific layout that was chosen to be simple while maintaining an underlying structure that is pliable to meet future requirements without needing major revisions. Questa operazione viene eseguita archiviando tutti i componenti (elementi di base per tutti gli oggetti della scena) in un elenco semplice e definendo la gerarchia e la composizione tramite riferimenti in cui componenti specifici fanno riferimento ad altri.The Scene does this by storing all Components (building blocks for all Scene Objects) in a flat list and defining hierarchy and composition through references where specific components reference others.

Di seguito viene presentato un esempio di una struttura sia nel formato flat che nella forma logica.Below we present an example of a structure in both its flat and logical form.

Layout logicoLogical LayoutLayout fisicoPhysical Layout
    SceneScene
    • SceneObject_1SceneObject_1
      • SceneMesh_1SceneMesh_1
      • SceneQuad_1SceneQuad_1
      • SceneQuad_2SceneQuad_2
    • SceneObject_2SceneObject_2
      • SceneQuad_1SceneQuad_1
      • SceneQuad_3SceneQuad_3
    • SceneObject_3SceneObject_3
      • SceneMesh_3SceneMesh_3
  • SceneObject_1SceneObject_1
  • SceneObject_2SceneObject_2
  • SceneObject_3SceneObject_3
  • SceneQuad_1SceneQuad_1
  • SceneQuad_2SceneQuad_2
  • SceneQuad_3SceneQuad_3
  • SceneMesh_1SceneMesh_1
  • SceneMesh_2SceneMesh_2

In questa illustrazione viene evidenziata la differenza tra il layout fisico e logico della scena.This illustration highlights the difference between the physical and logical layout of the Scene. A sinistra viene visualizzato il layout gerarchico dei dati visualizzati dall'applicazione durante l'enumerazione della scena.On the left, we see the hierarchical layout of the data that your application sees when enumerating the scene. A destra si noterà che la scena è costituita da 12 componenti distinti, se necessario, accessibili singolarmente.On the right, we see that the scene is comprised of 12 distinct components that are accessible individually if necessary. Quando si elabora una nuova scena, si prevede che le applicazioni analizzino logicamente questa gerarchia. Tuttavia, durante il rilevamento tra gli aggiornamenti della scena, alcune applicazioni potrebbero essere interessate solo a specifici componenti condivisi tra due scene.When processing a new scene, we expect applications to walk this hierarchy logically, however when tracking between scene updates, some applications may only be interested in targeting specific components that are shared between two scenes.

Panoramica delle APIAPI overview

Nella sezione seguente viene fornita una panoramica di alto livello dei costrutti nella comprensione della scena.The following section provides a high-level overview of the constructs in Scene Understanding. Leggendo questa sezione si apprenderà a comprendere come vengono rappresentate le scene e quali sono i vari componenti usati per.Reading this section will give you an understanding of how scenes are represented, and what the various components do/are used for. La sezione successiva fornirà esempi di codice concreti e dettagli aggiuntivi che verranno descritti in questa panoramica.The next section will provide concrete code examples and additional details that are glossed over in this overview.

Tutti i tipi descritti di seguito si trovano nello Microsoft.MixedReality.SceneUnderstanding spazio dei nomi.All of the types described below reside in the Microsoft.MixedReality.SceneUnderstanding namespace.

SceneComponentsSceneComponents

Dopo aver compreso il layout logico delle scene, è ora possibile presentare il concetto di SceneComponents e il modo in cui vengono usate per comporre la gerarchia.Now that you understand the logical layout of scenes we can now present the concept of SceneComponents and how they're used to compose hierarchy. SceneComponents sono le scomposizione più granulari in SceneUnderstanding che rappresentano una singola cosa principale, ad esempio una mesh o un quad o un rettangolo di delimitazione.SceneComponents are the most granular decompositions in SceneUnderstanding representing a single core thing, for example, a mesh or a quad or a bounding box. SceneComponents sono elementi che possono essere aggiornati in modo indipendente ed è possibile farvi riferimento da altri SceneComponents, di conseguenza hanno un'unica proprietà globale un ID univoco, che consente questo tipo di meccanismo di rilevamento/riferimento.SceneComponents are things that can update independently and can be referenced by other SceneComponents, hence they have a single global property a unique ID, that allow for this type of tracking/referencing mechanism. Gli ID vengono usati per la composizione logica della gerarchia della scena e per la persistenza degli oggetti, ovvero l'operazione di aggiornamento di una scena rispetto a un'altra.Ids are used for the logical composition of scene hierarchy as well as object persistence (the act of updating one scene relative to another.)

Se si tratta di una nuova scena calcolata come distinta e si sta semplicemente enumerando tutti i dati al suo interno, gli ID sono in gran parte trasparenti.If you're treating every newly computed scene as being distinct, and simply enumerating all data within it then Ids are largely transparent to you. Tuttavia, se si prevede di tenere traccia dei componenti in diversi aggiornamenti, si useranno gli ID per indicizzare e trovare SceneComponents tra gli oggetti scena.However, if you're planning to track components over several updates you'll use the Ids to index and find SceneComponents between Scene objects.

SceneObjectsSceneObjects

Un SceneObject è un SceneComponent che rappresenta un'istanza di un elemento "Thing", ad esempio un muro, un piano, un soffitto e così via... espressa dalla relativa proprietà Kind.A SceneObject is a SceneComponent that represents an instance of a "thing" for example, a wall, a floor, a ceiling, etc.... expressed by their Kind property. SceneObjects sono geometriche e quindi hanno funzioni e proprietà che rappresentano la loro posizione nello spazio, ma non contengono alcuna struttura geometrica o logica.SceneObjects are geometric, and therefore have functions and properties that represent their location in space, however they don't contain any geometric or logical structure. SceneObjects, invece, fanno riferimento ad altri SceneComponents, in particolare SceneQuads e SceneMeshes, che forniscono le varie rappresentazioni supportate dal sistema.Instead, SceneObjects reference other SceneComponents, specifically SceneQuads, and SceneMeshes, which provide the varied representations that are supported by the system. Quando viene calcolata una nuova scena, l'applicazione enumera in modo più probabile la SceneObjects della scena per elaborare gli elementi interessati.When a new scene is computed, your application will most likely enumerate the Scene's SceneObjects to process what it's interested in.

SceneObjects può avere uno dei seguenti elementi:SceneObjects can have any one of the following:

SceneObjectKindSceneObjectKind DescrizioneDescription
SfondoBackgroundIl SceneObject non è noto come uno degli altri tipi di oggetto scena riconosciuti.The SceneObject is known to be not one of the other recognized kinds of scene object. Questa classe non deve essere confusa con uno sconosciuto, in cui lo sfondo non è a parete/piano/soffitto e così via... mentre Unknown non è ancora stato categorizzato.This class shouldn't be confused with Unknown where Background is known not to be wall/floor/ceiling etc.... while unknown isn't yet categorized.
PareteWallUna parete fisica.A physical wall. Si presuppone che i muri siano strutture ambientali non mobili.Walls are assumed to be immovable environmental structures.
PianoFloorI piani sono superfici in cui è possibile spostarsi.Floors are any surfaces on which one can walk. Nota: le scale non sono piani.Note: stairs aren't floors. Si noti inoltre che le pavimentazioni presuppongono una superficie a cui è possibile spostarsi e pertanto non esiste alcun presupposto esplicito di un pavimento singolare.Also note, that floors assume any walkable surface and therefore there's no explicit assumption of a singular floor. Strutture a più livelli, rampe e così via... deve essere classificata come floor.Multi-level structures, ramps etc.... should all classify as floor.
CeilingCeilingSuperficie superiore di una stanza.The upper surface of a room.
PiattaformaPlatformUna superficie piana grande su cui posizionare gli ologrammi.A large flat surface on which you could place holograms. Che tendono a rappresentare tabelle, piani di ridimensionamento e altre superfici orizzontali di grandi dimensioni.These tend to represent tables, countertops, and other large horizontal surfaces.
WorldWorldEtichetta riservata per i dati geometrici indipendenti dall'assegnazione di etichette.A reserved label for geometric data that is agnostic to labeling. La mesh generata impostando il flag di aggiornamento EnableWorldMesh verrebbe classificato come World.The mesh generated by setting the EnableWorldMesh update flag would be classified as world.
SconosciutoUnknownQuesto oggetto scena deve ancora essere classificato e assegnato un tipo.This scene object has yet to be classified and assigned a kind. Questa operazione non deve essere confusa con background, perché questo oggetto può essere qualsiasi cosa, il sistema non ha ancora una classificazione sufficientemente sicura.This shouldn't be confused with Background, as this object could be anything, the system has just not come up with a strong enough classification for it yet.

SceneMeshSceneMesh

Un SceneMesh è un SceneComponent che approssima la geometria degli oggetti geometrici arbitrari usando un elenco di triangolo.A SceneMesh is a SceneComponent that approximates the geometry of arbitrary geometric objects using a triangle list. SceneMeshes vengono usati in diversi contesti, possono rappresentare i componenti della struttura di celle stagne o come WorldMesh, che rappresenta la mesh di mapping spaziale senza limiti associata alla scena.SceneMeshes are used in several different contexts, they can represent components of the watertight cell structure or as the WorldMesh, which represents the unbounded spatial mapping mesh associated with the Scene. I dati relativi a indici e vertici forniti con ogni mesh utilizzano lo stesso layout familiare dei buffer di vertice e di indice utilizzati per il rendering di mesh triangolari in tutte le moderne API di rendering.The index and vertex data provided with each mesh uses the same familiar layout as the vertex and index buffers that are used for rendering triangle meshes in all modern rendering APIs. Nella comprensione della scena, le maglie usano indici a 32 bit e potrebbero dover essere suddivise in blocchi per determinati motori di rendering.In Scene Understanding, meshes use 32-bit indices and may need to be broken up into chunks for certain rendering engines.

Ordine di avvolgimento e sistemi di coordinateWinding Order and Coordinate Systems

Tutte le mesh prodotte dalla comprensione della scena dovrebbero restituire mesh in un sistema di coordinate Right-Handed usando l'ordine di avvolgimento in senso orario.All meshes produced by Scene Understanding are expected to return meshes in a Right-Handed coordinate system using clockwise winding order.

Nota: le compilazioni del sistema operativo precedenti a. 191105 possono avere un bug noto in cui le mesh "World" stavano restituendo in Counter-Clockwise ordine di avvolgimento, che in seguito è stato risolto.Note: OS builds prior to .191105 may have a known bug where "World" meshes were returning in Counter-Clockwise winding order, which has subsequently been fixed.

SceneQuadSceneQuad

Un SceneQuad è un SceneComponent che rappresenta le superfici 2D che occupano il mondo 3D.A SceneQuad is a SceneComponent that represents 2d surfaces that occupy the 3d world. SceneQuads può essere usato in modo analogo ai piani ARKit ARPlaneAnchor o ARCore, ma offre funzionalità più avanzate come Canvas 2D da usare con le app flat o UX potenziato.SceneQuads can be used similarly to ARKit ARPlaneAnchor or ARCore Planes but they offer more high-level functionality as 2d canvases to be used by flat apps, or augmented UX. sono disponibili API specifiche 2D per i quad che semplificano l'uso del posizionamento e del layout e lo sviluppo (ad eccezione del rendering) con i quad dovrebbe essere più simile all'utilizzo di Canvas 2D rispetto alle mesh 3D.2D specific APIs are provided for quads that make placement and layout simple to use, and developing (with the exception of rendering) with quads should feel more akin to working with 2d canvases than 3d meshes.

Forma SceneQuadSceneQuad shape

SceneQuads definire una superficie rettangolare delimitata in 2D.SceneQuads define a bounded rectangular surface in 2d. Tuttavia, SceneQuads rappresentano le superfici con forme arbitrarie e potenzialmente complesse, ad esempio una tabella con forma di anello. Per rappresentare la forma complessa della superficie di un quad, è possibile usare l'API GetSurfaceMask per eseguire il rendering della forma della superficie in un buffer di immagine fornito.However, SceneQuads are representing surfaces with arbitrary and potentially complex shapes (e.g. a donut shaped table.) To represent the complex shape of the surface of a quad you may use the GetSurfaceMask API to render the shape of the surface onto an image buffer you provide. Se anche il SceneObject con il quad ha una mesh, i triangoli di mesh devono essere equivalenti a questa immagine sottoposta a rendering, entrambi rappresentano la geometria reale della superficie, in coordinate 2D o 3D.If the SceneObject that has the quad also has a mesh, the mesh triangles should be equivalent to this rendered image, they both represent real geometry of the surface, either in 2d or 3d coordinates.

Informazioni dettagliate e informazioni di riferimento sull'SDK della scenaScene understanding SDK details and reference

La sezione seguente consente di acquisire familiarità con le nozioni di base di SceneUnderstanding.The following section will help get you familiar with the basics of SceneUnderstanding. In questa sezione vengono fornite le nozioni di base, a questo punto è necessario disporre di un contesto sufficiente per esplorare le applicazioni di esempio per vedere come SceneUnderstanding viene usato in modo olistico.This section should provide you with the basics, at which point you should have enough context to browse through the sample applications to see how SceneUnderstanding is used holistically.

InizializzazioneInitialization

Il primo passaggio per lavorare con SceneUnderstanding è che l'applicazione ottenga un riferimento a un oggetto scena.The first step to working with SceneUnderstanding is for your application to gain reference to a Scene object. Questa operazione può essere eseguita in uno dei due modi seguenti, una scena può essere calcolata dal driver o una scena esistente calcolata in passato può essere deserializzata.This can be done in one of two ways, a Scene can either be computed by the driver, or an existing Scene that was computed in the past can be de-serialized. Quest'ultimo è utile per lavorare con SceneUnderstanding durante lo sviluppo, in cui le applicazioni e le esperienze possono essere prototipate rapidamente senza un dispositivo di realtà mista.The latter is useful for working with SceneUnderstanding during development, where applications and experiences can be prototyped quickly without a mixed reality device.

Le scene vengono calcolate usando un SceneObserver.Scenes are computed using a SceneObserver. Prima di creare una scena, l'applicazione deve eseguire una query sul dispositivo per assicurarsi che supporti SceneUnderstanding, oltre a richiedere l'accesso utente per le informazioni necessarie a SceneUnderstanding.Before creating a Scene, your application should query your device to ensure that it supports SceneUnderstanding, as well as to request user access for information that SceneUnderstanding needs.

if (!SceneObserver.IsSupported())
{
    // Handle the error
}

// This call should grant the access we need.
await SceneObserver.RequestAccessAsync();

Se RequestAccessAsync () non viene chiamato, il calcolo di una nuova scena avrà esito negativo.If RequestAccessAsync() is not called, computing a new Scene will fail. Successivamente, verrà calcolata una nuova scena che è radicata intorno all'auricolare della realtà mista e ha un raggio di 10 metri.Next we will compute a new scene that's rooted around the Mixed Reality headset and has a 10-meter radius.

// Create Query settings for the scene update
SceneQuerySettings querySettings;

querySettings.EnableSceneObjectQuads = true;                                       // Requests that the scene updates quads.
querySettings.EnableSceneObjectMeshes = true;                                      // Requests that the scene updates watertight mesh data.
querySettings.EnableOnlyObservedSceneObjects = false;                              // Do not explicitly turn off quad inference.
querySettings.EnableWorldMesh = true;                                              // Requests a static version of the spatial mapping mesh.
querySettings.RequestedMeshLevelOfDetail = SceneMeshLevelOfDetail.Fine;            // Requests the finest LOD of the static spatial mapping mesh.

// Initialize a new Scene
Scene myScene = SceneObserver.ComputeAsync(querySettings, 10.0f).GetAwaiter().GetResult();

Inizializzazione dai dati, nota anche come.Initialization from Data (also known as. Percorso PC)the PC Path)

Mentre le scene possono essere calcolate per il consumo diretto, possono anche essere calcolate in formato serializzato per un uso successivo.While Scenes can be computed for direct consumption, they can also be computed in serialized form for later use. Questo è risultato utile per lo sviluppo in quanto consente agli sviluppatori di lavorare e testare la comprensione della scena senza la necessità di un dispositivo.This has proven to be useful for development as it allows developers to work in and test Scene Understanding without the need for a device. L'azione di serializzazione di una scena è quasi identica a quella di elaborazione. i dati vengono restituiti all'applicazione anziché essere deserializzati localmente dall'SDK.The act of serializing a scene is nearly identical to computing it, the data is returned to your application instead of being deserialized locally by the SDK. Sarà quindi possibile deserializzarlo manualmente o salvarlo per un uso futuro.You may then deserialize it yourself or save it for future use.

// Create Query settings for the scene update
SceneQuerySettings querySettings;

// Compute a scene but serialized as a byte array
SceneBuffer newSceneBuffer = SceneObserver.ComputeSerializedAsync(querySettings, 10.0f).GetAwaiter().GetResult();

// If we want to use it immediately we can de-serialize the scene ourselves
byte[] newSceneData = new byte[newSceneBuffer.Size];
newSceneBuffer.GetData(newSceneData);
Scene mySceneDeSerialized = Scene.Deserialize(newSceneData);

// Save newSceneData for later

Enumerazione SceneObjectSceneObject Enumeration

Ora che l'applicazione ha una scena, l'applicazione verrà esaminata e interagirà con SceneObjects.Now that your application has a scene, your application will be looking at and interacting with SceneObjects. Questa operazione viene eseguita accedendo alla proprietà SceneObjects :This is done by accessing the SceneObjects property:

SceneObject firstFloor = null;

// Find the first floor object
foreach (var sceneObject in myScene.SceneObjects)
{
    if (sceneObject.Kind == SceneObjectKind.Floor)
    {
        firstFloor = sceneObject;
        break;
    }
}

Componenti di aggiornamento e riricerca dei componentiComponent update and refinding components

Esiste un'altra funzione che recupera i componenti nella scena denominata *findComponent _.There's another function that retrieves components in the Scene called *FindComponent _. Questa funzione è utile quando si aggiornano gli oggetti di rilevamento e li si trova nelle scene successive.This function is useful when updating tracking objects and finding them in later scenes. Il codice seguente consente di calcolare una nuova scena rispetto a una scena precedente e quindi di trovare il piano nella nuova scena.The following code will compute a new scene relative to a previous scene and then find the floor in the new scene.

// Compute a new scene, and tell the system that we want to compute relative to the previous scene
Scene myNextScene = SceneObserver.ComputeAsync(querySettings, 10.0f, myScene).GetAwaiter().GetResult();

// Use the Id for the floor we found last time, and find it again
firstFloor = (SceneObject)myNextScene.FindComponent(firstFloor.Id);

if (firstFloor != null)
{
    // We found it again, we can now update the transforms of all objects we attached to this floor transform
}

Accesso a mesh e quad da oggetti sceneAccessing Meshes and Quads from Scene Objects

Una volta rilevate SceneObjects, è probabile che l'applicazione acceda ai dati contenuti nei Quad/mesh di cui è composta.Once SceneObjects have been found your application will most likely want to access the data that is contained in the quads/meshes that it is composed of. Questi dati sono accessibili con le proprietà Quad e mesh .This data is accessed with the Quads and Meshes properties. Il codice seguente enumera tutti i quad e le maglie dell'oggetto Floor.The following code will enumerate all quads and meshes of our floor object.


// Get the transform for the SceneObject
System.Numerics.Matrix4x4 objectToSceneOrigin = firstFloor.GetLocationAsMatrix();

// Enumerate quads
foreach (var quad in firstFloor.Quads)
{
    // Process quads
}

// Enumerate meshes
foreach (var mesh in firstFloor.Meshes)
{
    // Process meshes
}

Si noti che si tratta del SceneObject con la trasformazione rispetto all'origine della scena.Notice that it's the SceneObject that has the transform that is relative to the Scene origin. Ciò è dovuto al fatto che SceneObject rappresenta un'istanza di una "cosa" ed è locatable nello spazio, i quad e le mesh rappresentano la geometria che viene trasformata in relazione all'elemento padre.This is because the SceneObject represents an instance of a "thing" and is locatable in space, the quads, and meshes represent geometry that is transformed relative to their parent. È possibile che SceneObjects separate facciano riferimento allo stesso SceneMesh/SceneQuad SceneComponents ed è anche possibile che un SceneObject disponga di più di un SceneMesh/SceneQuad.It's possible for separate SceneObjects to reference the same SceneMesh/SceneQuad SceneComponents, and it's also possible that a SceneObject has more than one SceneMesh/SceneQuad.

Gestione delle trasformazioniDealing with Transforms

La comprensione della scena ha effettuato un tentativo intenzionale di allinearsi alle rappresentazioni tradizionali della scena 3D quando si gestiscono le trasformazioni.Scene Understanding has made a deliberate attempt to align with traditional 3D scene representations when dealing with transforms. Ogni scena è quindi confinata a un singolo sistema di coordinate, in modo analogo alla maggior parte delle rappresentazioni ambientali 3D.Each Scene is therefore confined to a single coordinate system much like most common 3D environmental representations. SceneObjects forniscono il percorso relativo al sistema di coordinate.SceneObjects each provide their location relative to that coordinate system. Se l'applicazione sta affrontando scenari che estendono il limite di una singola origine, può ancorare SceneObjects a SpatialAnchors o generare diverse scene e unirle, ma per semplicità si presuppone che esistano scene ermetiche nella propria origine localizzata da un NodeId definito da scene. OriginSpatialGraphNodeId.If your application is dealing with Scenes that stretch the limit of what a single origin provides it can anchor SceneObjects to SpatialAnchors, or generate several scenes and merge them together, but for simplicity we assume that watertight scenes exist in their own origin that's localized by one NodeId defined by Scene.OriginSpatialGraphNodeId.

Il codice Unity seguente, ad esempio, Mostra come usare la percezione di Windows e le API Unity per allineare i sistemi di coordinate.The following Unity code, for example, shows how to use Windows Perception and Unity APIs to align coordinate systems together. Vedere SpatialCoordinateSystem e SpatialGraphInteropPreview per informazioni dettagliate sulle API di percezione di Windows e sugli oggetti nativi della realtà mista in Unity per informazioni dettagliate su come ottenere un SpatialCoordinateSystem che corrisponda all'origine mondiale di Unity.See SpatialCoordinateSystem and SpatialGraphInteropPreview for details on the Windows Perception APIs, and Mixed Reality native objects in Unity for details on obtaining a SpatialCoordinateSystem that corresponds to Unity's world origin.

private System.Numerics.Matrix4x4? GetSceneToUnityTransformAsMatrix4x4(SceneUnderstanding.Scene scene)
{

      System.Numerics.Matrix4x4? sceneToUnityTransform = System.Numerics.Matrix4x4.Identity;

      Windows.Perception.Spatial.SpatialCoordinateSystem sceneCoordinateSystem = Microsoft.Windows.Perception.Spatial.Preview.SpatialGraphInteropPreview.CreateCoordinateSystemForNode(scene.OriginSpatialGraphNodeId);
      HolograhicFrameData holoFrameData =  Marshal.PtrToStructure<HolograhicFrameData>(UnityEngine.XR.XRDevice.GetNativePtr());
      Windows.Perception.Spatial.SpatialCoordinateSystem unityCoordinateSystem = Microsoft.Windows.Perception.Spatial.SpatialCoordinateSystem.FromNativePtr(holoFrameData.ISpatialCoordinateSystemPtr);

      sceneToUnityTransform = sceneCoordinateSystem.TryGetTransformTo(unityCoordinateSystem);

      if(sceneToUnityTransform != null)
      {
          sceneToUnityTransform = ConvertRightHandedMatrix4x4ToLeftHanded(sceneToUnityTransform.Value);
      }
      else
      {
          return null;
      }

    return sceneToUnityTransform;
}

Ogni SceneObject ha una trasformazione, che viene quindi applicata a tale oggetto.Each SceneObject has a transform, which is then applied to that object. In Unity si converte in coordinate corrette e si assegnano trasformazioni locali come segue:In Unity we convert to right handed coordinates and assign local transforms as so:

private System.Numerics.Matrix4x4 ConvertRightHandedMatrix4x4ToLeftHanded(System.Numerics.Matrix4x4 matrix)
{
    matrix.M13 = -matrix.M13;
    matrix.M23 = -matrix.M23;
    matrix.M43 = -matrix.M43;

    matrix.M31 = -matrix.M31;
    matrix.M32 = -matrix.M32;
    matrix.M34 = -matrix.M34;

    return matrix;
}

 private void SetUnityTransformFromMatrix4x4(Transform targetTransform, System.Numerics.Matrix4x4 matrix, bool updateLocalTransformOnly = false)
 {
    if(targetTransform == null)
    {
        return;
    }

    Vector3 unityTranslation;
    Quaternion unityQuat;
    Vector3 unityScale;

    System.Numerics.Vector3 vector3;
    System.Numerics.Quaternion quaternion;
    System.Numerics.Vector3 scale;

    System.Numerics.Matrix4x4.Decompose(matrix, out scale, out quaternion, out vector3);

    unityTranslation = new Vector3(vector3.X, vector3.Y, vector3.Z);
    unityQuat        = new Quaternion(quaternion.X, quaternion.Y, quaternion.Z, quaternion.W);
    unityScale       = new Vector3(scale.X, scale.Y, scale.Z);

    if(updateLocalTransformOnly)
    {
        targetTransform.localPosition = unityTranslation;
        targetTransform.localRotation = unityQuat;
    }
    else
    {
        targetTransform.SetPositionAndRotation(unityTranslation, unityQuat);
    }
}

// Assume we have an SU object called suObject and a unity equivalent unityObject

System.Numerics.Matrix4x4 converted4x4LocationMatrix = ConvertRightHandedMatrix4x4ToLeftHanded(suObject.GetLocationAsMatrix());
SetUnityTransformFromMatrix4x4(unityObject.transform, converted4x4LocationMatrix, true);
        

QuadQuad

I quad sono stati progettati per aiutare gli scenari di selezione host 2D e dovrebbero essere considerati estensioni per gli elementi UX di Canvas 2D.Quads were designed to help 2D placement scenarios and should be thought of as extensions to 2D canvas UX elements. Mentre i quad sono componenti di SceneObjects e possono essere sottoposti a rendering in 3D, le API quadre presuppongono quad sono strutture 2D.While Quads are components of SceneObjects and can be rendered in 3D, the Quad APIs themselves assume Quads are 2D structures. Offrono informazioni come extent, Shape e forniscono API per la selezione host.They offer information such as extent, shape, and provide APIs for placement.

I quad hanno extent rettangolari, ma rappresentano superfici 2D a forma arbitraria.Quads have rectangular extents, but they represent arbitrarily shaped 2D surfaces. Per abilitare la selezione host in queste superfici 2D che interagiscono con i quad dell'ambiente 3D offrono utilità per rendere possibile questa interazione.To enable placement on these 2D surfaces that interact with the 3D environment quads offer utilities to make this interaction possible. Attualmente la comprensione della scena fornisce due funzioni di questo tipo: _ FindCentermostPlacement* e GetSurfaceMask.Currently Scene Understanding provides two such functions, _ FindCentermostPlacement* and GetSurfaceMask. FindCentermostPlacement è un'API di alto livello che individua una posizione nel quad in cui è possibile posizionare un oggetto e tenterà di individuare la posizione migliore per l'oggetto, garantendo che il rettangolo di delimitazione fornito rimarrà sulla superficie sottostante.FindCentermostPlacement is a high-level API that locates a position on the quad where an object can be placed and will try to find the best location for your object guaranteeing that the bounding box you provide will stay on the underlying surface.

Nota

Le coordinate dell'output sono relative al quad in "Quad Space" con l'angolo superiore sinistro (x = 0, y = 0), esattamente come per gli altri tipi Rect di Windows.The coordinates of the output are relative to the quad in "quad space" with the top left corner being (x = 0, y = 0), just as it would be with other windows Rect types. Assicurarsi di tenere conto di questo quando si lavora con le origini dei propri oggetti.Be sure to take this into account when working with the origins of your own objects.

Nell'esempio seguente viene illustrato come trovare la posizione posizionabile effettuare e come ancorare un ologramma al quad.The following example shows how to find the centermost placeable location and anchor a hologram to the quad.

// This code assumes you already have a "Root" object that attaches the Scene's Origin.

// Find the first quad
foreach (var sceneObject in myScene.SceneObjects)
{
    // Find a wall
    if (sceneObject.Kind == SceneObjectKind.Wall)
    {
        // Get the quad
        var quads = sceneObject.Quads;
        if (quads.Count > 0)
        {
            // Find a good location for a 1mx1m object  
            System.Numerics.Vector2 location;
            if (quads[0].FindCentermostPlacement(new System.Numerics.Vector2(1.0f, 1.0f), out location))
            {
                // We found one, anchor something to the transform
                // Step 1: Create a new game object for the quad itself as a child of the scene root
                // Step 2: Set the local transform from quads[0].Position and quads[0].Orientation
                // Step 3: Create your hologram and set it as a child of the quad's game object
                // Step 4: Set the hologram's local transform to a translation (location.x, location.y, 0)
            }
        }
    }
}

I passaggi 1-4 dipendono in modo estremamente da un particolare Framework/implementazione, ma i temi dovrebbero essere simili.Steps 1-4 are highly dependent on your particular framework/implementation, but the themes should be similar. È importante notare che il quad rappresenta semplicemente un piano 2D con binding localizzato nello spazio.It's important to note that the Quad simply represents a bounded 2D plane that is localized in space. Se il motore/Framework sa dove si trova il quad e si radicano gli oggetti rispetto al quad, gli ologrammi saranno posizionati correttamente rispetto al mondo reale.By having your engine/framework know where the quad is and rooting your objects relative to the quad, your holograms will be located correctly with respect to the real world.

MeshMesh

Le mesh rappresentano rappresentazioni geometriche di oggetti o ambienti.Meshes represent geometric representations of objects or environments. In modo analogo al mapping spaziale, i dati relativi a indici mesh e vertici forniti con ogni mesh di superficie spaziale utilizzano lo stesso layout familiare dei vertex buffer e degli indici utilizzati per il rendering di mesh triangolari in tutte le moderne API per il rendering.Much like spatial mapping, mesh index and vertex data provided with each spatial surface mesh uses the same familiar layout as the vertex and index buffers that are used for rendering triangle meshes in all modern rendering APIs. Le posizioni dei vertici sono disponibili nel sistema di coordinate di Scene .Vertex positions are provided in the coordinate system of the Scene. Le API specifiche usate per fare riferimento a questi dati sono le seguenti:The specific APIs used to reference this data are as follows:

void GetTriangleIndices(int[] indices);
void GetVertices(System.Numerics.Vector3[] vertices);

Il codice seguente fornisce un esempio di generazione di un elenco di triangolo dalla struttura mesh:The following code provides an example of generating a triangle list from the mesh structure:

uint[] indices = new uint[mesh.TriangleIndexCount];
System.Numerics.Vector3[] positions = new System.Numerics.Vector3[mesh.VertexCount];

mesh.GetTriangleIndices(indices);
mesh.GetVertexPositions(positions);

I buffer di indice/vertice devono essere >= i conteggi di indice/vertice, ma in caso contrario possono essere dimensionati arbitrariamente, consentendo un utilizzo efficiente della memoria.The index/vertex buffers must be >= the index/vertex counts, but otherwise can be arbitrarily sized allowing for efficient memory reuse.

ColliderMeshColliderMesh

Gli oggetti scena consentono di accedere ai dati mesh mesh e Collider mesh tramite le proprietà mesh e ColliderMeshes.Scene objects provide access to mesh and collider mesh data via the Meshes and ColliderMeshes properties. Queste mesh corrisponderanno sempre, ovvero l'indice volto della della proprietà Meshes rappresenta la stessa geometria dell'indice volto della della proprietà ColliderMeshes.These meshes will always match, meaning that the i'th index of the Meshes property represents the same geometry as the i'th index of the ColliderMeshes property. Se il runtime/oggetto supporta le mesh di Collider, si ha la certezza di ottenere il poligono più basso, l'approssimazione dell'ordine più elevato ed è consigliabile usare ColliderMeshes laddove l'applicazione userà i Collider.If the runtime/object supports collider meshes, you are guaranteed to get the lowest polygon, highest order approximation and it's good practice to use ColliderMeshes wherever your application would use colliders. Se il sistema non supporta i Collider, l'oggetto mesh restituito in ColliderMeshes sarà lo stesso oggetto della mesh che riduce i vincoli di memoria.If the system does not support colliders the Mesh object returned in ColliderMeshes will be the same object as the mesh reducing memory constraints.

Sviluppo con comprensione della scenaDeveloping with scene understanding

A questo punto, è necessario comprendere i componenti di base della scena Understanding Runtime and SDK.At this point, you should understand the core building blocks of the scene understanding runtime and SDK. La maggior parte della potenza e della complessità si basa sui modelli di accesso, sull'interazione con i framework 3D e sugli strumenti che possono essere scritti su queste API per eseguire attività più avanzate, come la pianificazione spaziale, l'analisi delle stanze, la navigazione, la fisica e così via.The bulk of the power and complexity lies in access patterns, interaction with 3D frameworks, and tools that can be written on top of these APIs to do more advanced tasks like spatial planning, room analysis, navigation, physics, and so on. Ci auguriamo che questi esempi vengano acquisiti in esempi che dovrebbero guidare l'utente nella direzione corretta per rendere più brillanti gli scenari.We hope to capture these in samples that should hopefully guide you in the proper direction to make your scenarios shine. Se sono presenti esempi o scenari che non sono stati indirizzati, è possibile inviarli e provare a documentare/prototipare gli elementi necessari.If there are samples or scenarios we aren't addressing, let us know and we'll try to document/prototype what you need.

Dove è possibile ottenere il codice di esempio?Where can I get sample code?

Scenario per informazioni sul codice di esempio per Unity, vedere la pagina di esempio Unity .Scene Understanding sample code for Unity can be found on our Unity Sample Page page. Questa applicazione consente di comunicare con il dispositivo ed eseguire il rendering dei vari oggetti scena, oppure di caricare una scena serializzata nel PC e di sperimentare la comprensione della scena senza un dispositivo.This application will allow you to communicate with your device and render the various scene objects, or, it will allow you to load a serialized scene on your PC and allow you to experience Scene Understanding without a device.

Dove è possibile ottenere scene di esempio?Where can I get sample scenes?

Se si dispone di un HoloLens2, è possibile salvare qualsiasi scena acquisita salvando l'output di ComputeSerializedAsync in file e deserializzarlo in base alla propria convenienza.If you have a HoloLens2, you can save any scene you've captured by saving the output of ComputeSerializedAsync to file and deserializing it at your own convenience.

Se non si ha un dispositivo HoloLens2 ma si vuole giocare con la comprensione della scena, è necessario scaricare una scena pre-acquisita.If you don't have a HoloLens2 device but want to play with Scene Understanding, you'll need to download a pre-captured scene. L'esempio di comprensione della scena è attualmente fornito con scene serializzate che possono essere scaricate e usate con facilità.The Scene Understanding sample currently ships with serialized scenes that can be downloaded and used at your own convenience. È possibile trovarli qui:You can find them here:

Scene di esempio sulla comprensione della scenaScene Understanding Sample Scenes

Vedere ancheSee also