Información general del SDK de introducción a la escenaScene understanding SDK overview

La descripción de la escena transforma los datos del sensor de entorno no estructurado que captura el dispositivo de realidad mixta y los convierte en una representación abstracta eficaz.Scene understanding transforms the unstructured environment sensor data that your Mixed Reality device captures and converts it into a powerful abstract representation. El SDK actúa como la capa de comunicación entre la aplicación y la escena que comprende el tiempo de ejecución.The SDK acts as the communication layer between your application and the Scene Understanding runtime. Está destinado a imitar construcciones estándar existentes, como gráficos de escenas 3D para representaciones 3D, y rectángulos 2D y paneles para aplicaciones 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. Aunque las construcciones que comprenden los imitadores se asignarán a marcos concretos, en general SceneUnderstanding es independiente del marco de trabajo, lo que permite la interoperabilidad entre diversos marcos que interactúan con él.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. A medida que la comprensión de la escena evolucione el rol del SDK, se asegurará de que las nuevas representaciones y capacidades sigan expuestas dentro de un marco unificado.As Scene Understanding evolves the role of the SDK is to ensure new representations and capabilities continue to be exposed within a unified framework. En este documento, en primer lugar, introduciremos conceptos de alto nivel que le ayudarán a familiarizarse con el uso o el entorno de desarrollo y, a continuación, proporcionar documentación más detallada sobre clases y construcciones específicas.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.

¿Dónde obtengo el SDK?Where do I get the SDK?

El SDK de SceneUnderstanding se descarga a través de NuGet.The SceneUnderstanding SDK is downloadable via NuGet.

SDK de SceneUnderstandingSceneUnderstanding SDK

Nota: la versión más reciente depende de los paquetes de versión preliminar y debe habilitar los paquetes de versión preliminar para verlo.Note: the latest release depends on preview packages and you'll need to enable pre-release packages to see it.

En el caso de la versión 0.5.2022-RC y versiones posteriores, la información sobre la escena es compatible con proyecciones de lenguaje para C# y C++ que permiten a las aplicaciones desarrollar aplicaciones para las plataformas 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 partir de esta versión, SceneUnderstanding es compatible con la compatibilidad del editor de Unity con el SceneObserver, que se usa únicamente para comunicarse con HoloLens2.As of this version, SceneUnderstanding supports unity in-editor support barring the SceneObserver, which is used solely for communicating with HoloLens2.

SceneUnderstanding requiere Windows SDK versión 18362 o posterior.SceneUnderstanding requires Windows SDK version 18362 or higher.

Si usa el SDK en un proyecto de Unity, use NuGet para Unity para instalar el paquete en el proyecto.If you're using the SDK in a Unity project, use NuGet for Unity to install the package into your project.

Información conceptualConceptual Overview

La escenaThe Scene

El dispositivo de realidad mixta integra constantemente información sobre lo que ve en su entorno.Your mixed reality device is constantly integrating information about what it sees in your environment. La comprensión de la escena canaliza todos estos orígenes de datos y genera una sola abstracción unida.Scene Understanding funnels all of these data sources and produces one single cohesive abstraction. La comprensión de escenas genera escenas, que son una composición de SceneObjects que representan una instancia de un solo elemento (por ejemplo, un muro/techo/piso). Los propios objetos de la escena son una composición de [SceneComponents, que representan partes más granulares que componen este 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. Algunos ejemplos de componentes son cuatro y mallas, pero en el futuro podrían representar cuadros de límite, mallas de colisión, metadatos, etc.Examples of components are quads and meshes, but in the future could represent bounding boxes, collision meshes, metadata etc.

El proceso de conversión de los datos del sensor sin formato en una escena es una operación potencialmente costosa que podría tardar unos segundos en espacios medios (~ 10x10m) hasta minutos para espacios grandes (~ 50x50m) y, por lo tanto, no es algo que el dispositivo está calculando sin solicitud de aplicación.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. En su lugar, la generación de escenas la desencadena la aplicación a petición.Instead, Scene generation is triggered by your application on demand. La clase SceneObserver tiene métodos estáticos que pueden calcular o deserializar una escena, que puede enumerar o interactuar con.The SceneObserver class has static methods that can Compute or Deserialize a scene, which you can then enumerate/interact with. La acción de "proceso" se ejecuta a petición y se ejecuta en la CPU, pero en un proceso independiente (el controlador de realidad mixta).The "Compute" action is executed on-demand and executes on the CPU but in a separate process (the Mixed Reality Driver). Sin embargo, mientras se realiza el proceso en otro proceso, los datos de la escena resultantes se almacenan y mantienen en la aplicación en el objeto de la escena.However, while we do compute in another process the resulting Scene data is stored and maintained in your application in the Scene object.

A continuación se muestra un diagrama que ilustra este flujo de proceso y muestra ejemplos de dos aplicaciones que interconectan con el entorno de tiempo de ejecución de la escena.Below is a diagram that illustrates this process flow and shows examples of two applications interfacing with the Scene Understanding runtime.

Diagrama del proceso

En el lado izquierdo hay un diagrama del tiempo de ejecución de la realidad mixta, que siempre está activado y en ejecución en su propio proceso.On the left-hand side is a diagram of the mixed reality runtime, which is always on and running in its own process. Este tiempo de ejecución es responsable de realizar el seguimiento de los dispositivos, la asignación espacial y otras operaciones que la comprensión de la escena usa para entender y explicar el mundo.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. En el lado derecho del diagrama, se muestran dos aplicaciones teóricas que hacen uso de la comprensión de la escena.On the right side of the diagram, we show two theoretical applications that make use of Scene Understanding. La primera interfaz de la aplicación con MRTK, que usa el SDK de información de escenas internamente, la segunda aplicación calcula y usa dos instancias de escena independientes.The first application interfaces with MRTK, which uses the Scene Understanding SDK internally, the second app computes and uses two separate scene instances. Las tres escenas de este diagrama generan instancias distintas de las escenas, el controlador no realiza un seguimiento del estado global que se comparte entre las aplicaciones y los objetos de escena de una escena no se encuentran en otro.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 comprensión de la escena proporciona un mecanismo para realizar el seguimiento con el tiempo, pero esto se hace con el SDK.Scene Understanding does provide a mechanism to track over time, but this is done using the SDK. El código de seguimiento ya se está ejecutando en el SDK en el proceso de la aplicación.Tracking code is already running in the SDK in your app's process.

Dado que cada escena almacena sus datos en el espacio de memoria de la aplicación, puede suponer que todas las funciones del objeto de escena o de sus datos internos siempre se ejecutan en el proceso de la aplicación.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

Para trabajar con la comprensión de la escena, puede ser útil conocer y entender cómo representa los componentes el tiempo de ejecución de forma lógica y física.To work with Scene Understanding, it may be valuable to know and understand how the runtime represents components logically and physically. La escena representa los datos con un diseño específico que se eligió para ser sencillo al tiempo que se mantiene una estructura subyacente que se pliable para satisfacer los requisitos futuros sin necesidad de revisiones importantes.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. Para ello, la escena almacena todos los componentes (bloques de creación de todos los objetos de escena) en una lista plana y define la jerarquía y la composición a través de referencias en las que determinados componentes hacen referencia a otros.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.

A continuación se presenta un ejemplo de una estructura en su forma plana y lógica.Below we present an example of a structure in both its flat and logical form.

Diseño lógicoLogical LayoutDiseño físicoPhysical Layout
    EscenaScene
    • 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

En esta ilustración se resalta la diferencia entre el diseño físico y lógico de la escena.This illustration highlights the difference between the physical and logical layout of the Scene. A la izquierda, vemos el diseño jerárquico de los datos que la aplicación ve al enumerar la escena.On the left, we see the hierarchical layout of the data that your application sees when enumerating the scene. A la derecha, vemos que la escena se compone de 12 componentes distintos a los que se puede tener acceso individualmente si es necesario.On the right, we see that the scene is comprised of 12 distinct components that are accessible individually if necessary. Al procesar una nueva escena, esperamos que las aplicaciones recorran esta jerarquía de manera lógica; sin embargo, al realizar un seguimiento entre las actualizaciones de la escena, algunas aplicaciones solo pueden estar interesadas en determinados componentes que se comparten entre dos escenas.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.

Introducción a la APIAPI overview

En la sección siguiente se proporciona información general de alto nivel sobre las construcciones de comprensión de la escena.The following section provides a high-level overview of the constructs in Scene Understanding. Al leer esta sección se proporciona una descripción de cómo se representan las escenas y para qué se usan los distintos componentes.Reading this section will give you an understanding of how scenes are represented, and what the various components do/are used for. En la siguiente sección se proporcionan ejemplos de código concretos e información adicional con el glosario en esta información general.The next section will provide concrete code examples and additional details that are glossed over in this overview.

Todos los tipos que se describen a continuación residen en el Microsoft.MixedReality.SceneUnderstanding espacio de nombres.All of the types described below reside in the Microsoft.MixedReality.SceneUnderstanding namespace.

SceneComponentsSceneComponents

Ahora que comprende el diseño lógico de escenas, ahora podemos presentar el concepto de SceneComponents y cómo se usan para crear la jerarquía.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 son las descomposiciones más pormenorizadas de SceneUnderstanding que representan una sola cosa principal, por ejemplo, una malla o un cuadro de límite cuádruple o de rectángulo.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 son elementos que se pueden actualizar de forma independiente y a los que puede hacer referencia otro SceneComponents, por lo que tienen una única propiedad global como un identificador único, lo que permite este tipo de mecanismo de seguimiento o referencia.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. Los identificadores se usan para la composición lógica de la jerarquía de escenas, así como para la persistencia de objetos (la acción de actualizar una escena en relación con otra).Ids are used for the logical composition of scene hierarchy as well as object persistence (the act of updating one scene relative to another.)

Si está tratando cada escena recién calculada como DISTINCT y simplemente enumerando todos los datos que contiene, los identificadores son en gran medida transparentes para usted.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. Sin embargo, si tiene previsto realizar un seguimiento de los componentes de varias actualizaciones, usará los identificadores para indexar y buscar SceneComponents entre los objetos de la escena.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 es un SceneComponent que representa una instancia de una "cosa", por ejemplo, una pared, una planta, un límite superior, etc. expresado por su propiedad 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. Los SceneObjects son geométricos y, por tanto, tienen funciones y propiedades que representan su ubicación en el espacio, pero no contienen ninguna estructura geométrica o lógica.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. En su lugar, SceneObjects hace referencia a otros SceneComponents, específicamente SceneQuads y SceneMeshes, que proporcionan las representaciones variadas que admite el sistema.Instead, SceneObjects reference other SceneComponents, specifically SceneQuads, and SceneMeshes, which provide the varied representations that are supported by the system. Cuando se calcula una nueva escena, es probable que la aplicación Enumere los SceneObjects de la escena para procesar lo que le interesa.When a new scene is computed, your application will most likely enumerate the Scene's SceneObjects to process what it's interested in.

SceneObjects puede tener cualquiera de las siguientes opciones:SceneObjects can have any one of the following:

SceneObjectKindSceneObjectKind DescriptionDescription
FondoBackgroundSe sabe que el SceneObject no es uno de los otros tipos reconocidos de objeto de escena.The SceneObject is known to be not one of the other recognized kinds of scene object. Esta clase no se debe confundir con Unknown, donde se sabe que el fondo no es mural, piso, techo, etc. Aunque Unknown no se ha categorizado todavía.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.
ParedWallUna pared física.A physical wall. Se supone que las paredes son estructuras de entorno inmóviles.Walls are assumed to be immovable environmental structures.
FloorFloorLas plantas son superficies en las que se puede recorrer.Floors are any surfaces on which one can walk. Nota: las escaleras no se encuentran en el suelo.Note: stairs aren't floors. Tenga en cuenta también que las plantas suponen cualquier superficie que se puede examinar y, por lo tanto, no hay ninguna suposición explícita de un piso singular.Also note, that floors assume any walkable surface and therefore there's no explicit assumption of a singular floor. Estructuras de varios niveles, rampas, etc... debe clasificarse como Floor.Multi-level structures, ramps etc.... should all classify as floor.
CeilingCeilingLa superficie superior de una habitación.The upper surface of a room.
PlataformaPlatformUna superficie plana grande en la que se pueden colocar hologramas.A large flat surface on which you could place holograms. Tienden a representar tablas, contrapartes y otras superficies horizontales grandes.These tend to represent tables, countertops, and other large horizontal surfaces.
WorldWorldEtiqueta reservada para los datos geométricos que es independiente de la etiqueta.A reserved label for geometric data that is agnostic to labeling. La malla generada al establecer la marca de actualización EnableWorldMesh se clasificaría como World.The mesh generated by setting the EnableWorldMesh update flag would be classified as world.
DesconocidoUnknownEste objeto de escena todavía se puede clasificar y asignar a un tipo.This scene object has yet to be classified and assigned a kind. No se debe confundir con el fondo, ya que este objeto podría ser cualquier cosa, el sistema no se ha puesto todavía con una clasificación suficientemente alta para ella.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 es un SceneComponent que se aproxima a la geometría de objetos geométricos arbitrarios mediante una lista de triángulos.A SceneMesh is a SceneComponent that approximates the geometry of arbitrary geometric objects using a triangle list. SceneMeshes se usan en varios contextos diferentes, pueden representar componentes de la estructura de celda estanca o como WorldMesh, que representa la malla de asignación espacial sin enlazar asociada a la escena.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. Los datos de índice y vértices que se proporcionan con cada malla usan el mismo diseño conocido que los búferes de vértices y de índices que se usan para representar mallas de triángulo en todas las API de representación modernas.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. En la comprensión de escenas, las mallas usan índices de 32 bits y es posible que necesiten dividirse en fragmentos para determinados motores de representación.In Scene Understanding, meshes use 32-bit indices and may need to be broken up into chunks for certain rendering engines.

Orden de bobinado y sistemas de coordenadasWinding Order and Coordinate Systems

Se espera que todas las mallas generadas por el conocimiento de la escena devuelvan mallas en un sistema de coordenadas de Right-Handed con el orden de bobinado hacia la derecha.All meshes produced by Scene Understanding are expected to return meshes in a Right-Handed coordinate system using clockwise winding order.

Nota: las compilaciones del sistema operativo anteriores a. 191105 pueden tener un error conocido en el que las mallas "mundiales" devolvían en Counter-Clockwise orden de bobinado, que se ha corregido posteriormente.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 es un SceneComponent que representa superficies 2D que ocupan el mundo 3D.A SceneQuad is a SceneComponent that represents 2d surfaces that occupy the 3d world. SceneQuads se puede usar de forma similar a los planos ARKit ARPlaneAnchor o ARCore, pero ofrecen más funcionalidad de alto nivel que los lienzos 2D que usarán las aplicaciones planas o la experiencia de usuario aumentada.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. se proporcionan API específicas de 2D para cuádruples que facilitan el uso de la ubicación y el diseño, y el desarrollo (con la excepción de la representación) con cuatros se siente más parecido al trabajo con lienzos 2D que las mallas 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 define una superficie rectangular limitada en 2D.SceneQuads define a bounded rectangular surface in 2d. Sin embargo, los SceneQuads representan superficies con formas arbitrarias y potencialmente complejas (por ejemplo, una tabla con forma de anillo). Para representar la forma compleja de la superficie de una cuádruple, puede usar la API GetSurfaceMask para representar la forma de la superficie en un búfer de imagen que proporcione.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. Si el SceneObject que tiene el cuádruple también tiene una malla, los triángulos de la malla deben ser equivalentes a esta imagen representada, ambos representan la geometría real de la superficie, ya sea en coordenadas 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.

Detalles y referencia del SDK de la escenaScene understanding SDK details and reference

La siguiente sección le ayudará a familiarizarse con los conceptos básicos de SceneUnderstanding.The following section will help get you familiar with the basics of SceneUnderstanding. En esta sección se proporcionan los conceptos básicos, momento en el que debe tener suficiente contexto para examinar las aplicaciones de ejemplo para ver cómo se usa SceneUnderstanding de forma holística.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.

InicializaciónInitialization

El primer paso para trabajar con SceneUnderstanding es que la aplicación pueda obtener referencias a un objeto de escena.The first step to working with SceneUnderstanding is for your application to gain reference to a Scene object. Esto puede realizarse de una de estas dos formas: el controlador puede calcular una escena, o bien se puede deserializar una escena existente calculada en el pasado.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. Esto último es útil para trabajar con SceneUnderstanding durante el desarrollo, donde las aplicaciones y experiencias se pueden crear rápidamente con un dispositivo de realidad mixta.The latter is useful for working with SceneUnderstanding during development, where applications and experiences can be prototyped quickly without a mixed reality device.

Las escenas se calculan mediante una SceneObserver.Scenes are computed using a SceneObserver. Antes de crear una escena, la aplicación debe consultar el dispositivo para asegurarse de que admite SceneUnderstanding, así como para solicitar acceso de usuario para obtener información que necesita 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();

Si no se llama a RequestAccessAsync (), se producirá un error al calcular una nueva escena.If RequestAccessAsync() is not called, computing a new Scene will fail. A continuación, calcularemos una nueva escena que se basa en torno al casco de realidad mixta y que tiene un radio de 10 metros.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();

Inicialización de datos (también conocida como.Initialization from Data (also known as. la ruta de acceso del equipo)the PC Path)

Aunque se pueden calcular escenas para su consumo directo, también se pueden calcular en forma serializada para su uso posterior.While Scenes can be computed for direct consumption, they can also be computed in serialized form for later use. Esto ha demostrado ser útil para el desarrollo, ya que permite a los desarrolladores trabajar y probar la comprensión de la escena sin necesidad de 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. El acto de serializar una escena es casi idéntico al cálculo, los datos se devuelven a la aplicación en lugar de deserializarse localmente mediante el 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. Después, puede deserializarlo usted mismo o guardarlo para su 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

Enumeración SceneObjectSceneObject Enumeration

Ahora que la aplicación tiene una escena, la aplicación examinará e interactuará con SceneObjects.Now that your application has a scene, your application will be looking at and interacting with SceneObjects. Esto se hace mediante el acceso a la propiedad 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;
    }
}

Actualización de componentes y rebúsqueda de componentesComponent update and refinding components

Hay otra función que recupera los componentes de la escena denominada *FindComponent _.There's another function that retrieves components in the Scene called *FindComponent _. Esta función es útil cuando se actualizan objetos de seguimiento y se encuentran en escenas posteriores.This function is useful when updating tracking objects and finding them in later scenes. El siguiente código calculará una nueva escena en relación con una escena anterior y, a continuación, buscará el piso en la nueva escena.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
}

Acceso a mallas y cuádruples de objetos de escenaAccessing Meshes and Quads from Scene Objects

Una vez que se ha detectado SceneObjects, es más probable que la aplicación tenga acceso a los datos contenidos en las cuádruples o mallas de las que se compone.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. Se tiene acceso a estos datos con las propiedades de cuádruples y mallas .This data is accessed with the Quads and Meshes properties. En el código siguiente se enumeran todos los cuádruples y mallas de nuestro objeto 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
}

Observe que es el SceneObject que tiene la transformación relativa al origen de la escena.Notice that it's the SceneObject that has the transform that is relative to the Scene origin. Esto se debe a que SceneObject representa una instancia de una "Thing" y es localizable en el espacio, las cuádruples y las mallas representan geometría que se transforma con respecto a su elemento primario.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. Es posible que SceneObjects independientes haga referencia al mismo SceneMesh/SceneQuad SceneComponents, y también es posible que una SceneObject tenga más de una 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.

Trabajar con transformacionesDealing with Transforms

La comprensión de la escena ha realizado un intento deliberado de alinearse con representaciones de escenas 3D tradicionales al tratar con transformaciones.Scene Understanding has made a deliberate attempt to align with traditional 3D scene representations when dealing with transforms. Por lo tanto, cada escena se limita a un sistema de coordenadas único, de forma muy similar a la mayoría de las representaciones comunes del entorno 3D.Each Scene is therefore confined to a single coordinate system much like most common 3D environmental representations. Cada SceneObjects proporciona su ubicación relativa a ese sistema de coordenadas.SceneObjects each provide their location relative to that coordinate system. Si la aplicación está tratando con escenas que amplían el límite de lo que proporciona un único origen, puede delimitar SceneObjects a SpatialAnchors, o generar varias escenas y combinarlas juntas, pero para simplificar, se supone que las escenas estancas existen en su propio origen localizado por un NodeId definido por 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.

El siguiente código de Unity, por ejemplo, muestra cómo usar las API de Windows y la percepción de Windows para alinear los sistemas de coordenadas.The following Unity code, for example, shows how to use Windows Perception and Unity APIs to align coordinate systems together. Consulte SpatialCoordinateSystem y SpatialGraphInteropPreview para obtener más información sobre las API de percepción de Windows y los objetos nativos de realidad mixta en Unity para obtener más información sobre cómo obtener una SpatialCoordinateSystem que se corresponda con el origen mundial de 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;
}

Cada SceneObject una tiene una transformación, que se aplica a ese objeto.Each SceneObject has a transform, which is then applied to that object. En Unity convertiremos en coordenadas correctas y asignaremos transformaciones locales de la manera siguiente: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);
        

CuádrupleQuad

Las Quad se diseñaron para ayudar en escenarios de selección de ubicación 2D y deben considerarse como extensiones para los elementos de la experiencia de usuario de lienzo 2D.Quads were designed to help 2D placement scenarios and should be thought of as extensions to 2D canvas UX elements. Aunque cuádruples son componentes de SceneObjects y se pueden representar en 3D, las propias API en sí suponen que los cuatro son estructuras 2D.While Quads are components of SceneObjects and can be rendered in 3D, the Quad APIs themselves assume Quads are 2D structures. Ofrecen información como extensión, forma y proporcionan API para la selección de ubicación.They offer information such as extent, shape, and provide APIs for placement.

Las Quad tienen extensiones rectangulares, pero representan superficies 2D con forma arbitraria.Quads have rectangular extents, but they represent arbitrarily shaped 2D surfaces. Para habilitar la selección de ubicación en estas superficies 2D que interactúan con las utilidades de los cuatro entornos en 3D para que esta interacción sea posible.To enable placement on these 2D surfaces that interact with the 3D environment quads offer utilities to make this interaction possible. Actualmente, la comprensión de la escena proporciona dos funciones, _ FindCentermostPlacement* y GetSurfaceMask.Currently Scene Understanding provides two such functions, _ FindCentermostPlacement* and GetSurfaceMask. FindCentermostPlacement es una API de alto nivel que busca una posición en la cuádruple donde se puede colocar un objeto e intenta encontrar la mejor ubicación para el objeto, lo que garantiza que el cuadro de límite que proporcione permanecerá en la superficie subyacente.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

Las coordenadas de la salida son relativas a la cuádruple en "espacio cuádruple" con la esquina superior izquierda (x = 0, y = 0), del mismo modo que lo haría con otros tipos de rectángulo de 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. No olvide tener esto en cuenta al trabajar con los orígenes de sus propios objetos.Be sure to take this into account when working with the origins of your own objects.

En el ejemplo siguiente se muestra cómo buscar la ubicación centermost colocar y delimitar un holograma a la cuádruple.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)
            }
        }
    }
}

Los pasos 1-4 son muy dependientes de la implementación o el marco de trabajo en particular, pero los temas deben ser similares.Steps 1-4 are highly dependent on your particular framework/implementation, but the themes should be similar. Es importante tener en cuenta que la cuádruple simplemente representa un plano 2D enlazado que está localizado en el espacio.It's important to note that the Quad simply represents a bounded 2D plane that is localized in space. Teniendo el motor o el marco de trabajo de saber dónde está el cuádruple y la raíz de los objetos en relación con la cuádruple, los hologramas se ubicarán correctamente con respecto al mundo real.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.

En mallaMesh

Las mallas representan representaciones geométricas de objetos o entornos.Meshes represent geometric representations of objects or environments. De forma similar a la asignación espacial, los datos del índice de malla y del vértice que se proporcionan con cada malla de superficie espacial usan el mismo diseño conocido que los búferes de vértices y de índices que se usan para representar mallas de triángulo en todas las API de representación modernas.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. Las posiciones de los vértices se proporcionan en el sistema de coordenadas de Scene .Vertex positions are provided in the coordinate system of the Scene. Las API específicas que se usan para hacer referencia a estos datos son las siguientes:The specific APIs used to reference this data are as follows:

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

El código siguiente proporciona un ejemplo de generación de una lista de triángulos a partir de la estructura de malla: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);

Los búferes de índice/vértices se deben >= los recuentos de índice o vértices, pero de lo contrario se puede cambiar el tamaño de forma arbitraria, lo que permite la reutilización de memoria eficaz.The index/vertex buffers must be >= the index/vertex counts, but otherwise can be arbitrarily sized allowing for efficient memory reuse.

ColliderMeshColliderMesh

Los objetos de escena proporcionan acceso a los datos de malla y de la malla de Colisionador a través de las propiedades meshes y ColliderMeshes.Scene objects provide access to mesh and collider mesh data via the Meshes and ColliderMeshes properties. Estas mallas siempre coinciden, lo que significa que el índice i-ésima de la propiedad meshes representa la misma geometría que el índice i de la propiedad 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. Si el objeto en tiempo de ejecución es compatible con las mallas de Colisionador, se garantiza que obtendrá el polígono más bajo, la mayor aproximación de orden y se recomienda usar ColliderMeshes siempre que la aplicación use colisionadores.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. Si el sistema no admite colisiones, el objeto de malla devuelto en ColliderMeshes será el mismo objeto que la malla que reduce las restricciones de 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.

Desarrollo con conocimiento de escenasDeveloping with scene understanding

En este punto, debe comprender los principales bloques de creación de la escena que comprende el tiempo de ejecución y el SDK.At this point, you should understand the core building blocks of the scene understanding runtime and SDK. La mayor parte de la eficacia y la complejidad radica en los patrones de acceso, la interacción con Marcos 3D y las herramientas que se pueden escribir sobre estas API para realizar tareas más avanzadas, como la planeación espacial, el análisis de habitación, la navegación, la física, etc.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. Esperamos que se capturen en ejemplos que deberían ser de esperar en la dirección adecuada para que los escenarios se muestren.We hope to capture these in samples that should hopefully guide you in the proper direction to make your scenarios shine. Si hay ejemplos o escenarios que no abordamos, háganoslo saber y vamos a intentar documentar o crear prototipos de lo que necesita.If there are samples or scenarios we aren't addressing, let us know and we'll try to document/prototype what you need.

¿Dónde puedo obtener código de ejemplo?Where can I get sample code?

En la página de la Página de ejemplo de Unity puede encontrar el código de ejemplo de la escena para Unity.Scene Understanding sample code for Unity can be found on our Unity Sample Page page. Esta aplicación le permitirá comunicarse con el dispositivo y representar los distintos objetos de la escena, o bien le permitirá cargar una escena serializada en su equipo y le permitirá experimentar la comprensión de la escena sin 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.

¿Dónde puedo obtener escenas de ejemplo?Where can I get sample scenes?

Si tiene un HoloLens2, puede guardar cualquier escena que haya capturado guardando el resultado de ComputeSerializedAsync en un archivo y deserializarlo por su comodidad.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.

Si no tiene un dispositivo HoloLens2 pero desea jugar con la comprensión de la escena, deberá descargar una escena capturada previamente.If you don't have a HoloLens2 device but want to play with Scene Understanding, you'll need to download a pre-captured scene. El ejemplo de comprensión de la escena se incluye actualmente con escenas serializadas que se pueden descargar y usar por su comodidad.The Scene Understanding sample currently ships with serialized scenes that can be downloaded and used at your own convenience. Puede encontrarlos aquí:You can find them here:

Escenas de ejemplo de la escenaScene Understanding Sample Scenes

Consulta tambiénSee also