Общие сведения о пакете SDK для сценыScene understanding SDK overview

Понятие "сцена" преобразует неструктурированные данные датчика среды, записанные устройством смешанной реальности, и преобразует их в эффективное абстрактное представление.Scene understanding transforms the unstructured environment sensor data that your Mixed Reality device captures and converts it into a powerful abstract representation. Пакет SDK выступает в качестве коммуникационного уровня между приложением и сцены среды выполнения.The SDK acts as the communication layer between your application and the Scene Understanding runtime. Он предназначен для имитации существующих стандартных конструкций, таких как графики трехмерных сцен для трехмерных представлений, и двумерных прямоугольников и панелей для двумерных приложений.It's aimed to mimic existing standard constructs, such as 3D scene graphs for 3D representations, and 2D rectangles and panels for 2D applications. Хотя сцены конструкций понимают, что имитирует сопоставление с конкретными платформами, в целом Сценеундерстандинг является независимым от платформы и обеспечивает взаимодействие между различными средами, которые взаимодействуют с ним.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. По мере того, как в сцене понимается развитие роли пакета SDK, мы видим, что новые представления и возможности по-прежнему будут доступны в единой инфраструктуре.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 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.

Где получить пакет SDK?Where do I get the SDK?

Пакет SDK для Сценеундерстандинг загружается через NuGet.The SceneUnderstanding SDK is downloadable via NuGet.

Пакет SDK для СценеундерстандингSceneUnderstanding SDK

Примечание. последний выпуск зависит от предварительных версий пакетов, и для его просмотра необходимо включить пакеты предварительной версии.Note: the latest release depends on preview packages and you'll need to enable pre-release packages to see it.

Для версии 0.5.2022-RC и более поздних версий сцены понимает поддержку языковых проекций для C# и C++, позволяя приложениям разрабатывать приложения для платформ Win32 или 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. Начиная с этой версии, Сценеундерстандинг поддерживает поддержку Unity в редакторе, позволяя отменять Сценеобсервер, который используется исключительно для взаимодействия с HoloLens2.As of this version, SceneUnderstanding supports unity in-editor support barring the SceneObserver, which is used solely for communicating with HoloLens2.

Для Сценеундерстандинг требуется Windows SDK версии 18362 или более поздней.SceneUnderstanding requires Windows SDK version 18362 or higher.

Если вы используете пакет SDK в проекте Unity, используйте NuGet для Unity , чтобы установить пакет в проект.If you're using the SDK in a Unity project, use NuGet for Unity to install the package into your project.

Общие сведения об основных понятияхConceptual Overview

СценаThe Scene

Устройство Mixed Reality постоянно интегрирует информацию о том, что она видит в вашей среде.Your mixed reality device is constantly integrating information about what it sees in your environment. При понимании сцены создаются все эти источники данных и создается одна единая абстракция.Scene Understanding funnels all of these data sources and produces one single cohesive abstraction. Понятие сцены создает сцены, представляющие собой композицию сценеобжектс , которая представляет экземпляр одной вещи (например, стены, потолка или этажа). Сами объекты сцены представляют собой композицию [Сценекомпонентс, представляющую более детализированные элементы, составляющие этот Сценеобжект.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. Примерами компонентов являются четыре и сетчатые сети, но в будущем они могут представлять ограничивающие рамки, конфликты сеток, метаданные и т. д.Examples of components are quads and meshes, but in the future could represent bounding boxes, collision meshes, metadata etc.

Процесс преобразования необработанных данных датчика в сцену является потенциально дорогостоящей операцией, которая может занять секунды для средних пробелов (~ 10x10m) в минутах для больших пробелов (~ 50x50m) и, следовательно, не будет вычисляться устройством без запроса приложения.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. Вместо этого создание сцены активируется вашим приложением по запросу.Instead, Scene generation is triggered by your application on demand. Класс Сценеобсервер содержит статические методы, которые могут вычислять или десериализовать сцену, которые затем можно перечислить или взаимодействовать с.The SceneObserver class has static methods that can Compute or Deserialize a scene, which you can then enumerate/interact with. Действие "вычисление" выполняется по требованию и выполняется в ЦП, но в отдельном процессе (драйвер Mixed Reality).The "Compute" action is executed on-demand and executes on the CPU but in a separate process (the Mixed Reality Driver). Однако, пока мы выполняем вычисление в другом процессе, полученные данные сцены сохраняются и обслуживаются в приложении в объекте сцены.However, while we do compute in another process the resulting Scene data is stored and maintained in your application in the Scene object.

Ниже приведена схема, на которой показан этот поток процесса, и приведены примеры двух приложений, взаимодействующих с сценой выполнения.Below is a diagram that illustrates this process flow and shows examples of two applications interfacing with the Scene Understanding runtime.

Схема процесса

В левой части находится схема среды выполнения Mixed Reality, которая всегда включена и выполняется в собственном процессе.On the left-hand side is a diagram of the mixed reality runtime, which is always on and running in its own process. Эта среда выполнения отвечает за выполнение отслеживания устройств, пространственное сопоставление и другие операции, которые используются в сцене для понимания и причины вокруг всего мира.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. В правой части схемы показаны два теоретических приложения, которые используют понимание сцены.On the right side of the diagram, we show two theoretical applications that make use of Scene Understanding. Первое приложение взаимодействует с МРТК, которое использует для внутренних целей пакет SDK, второе приложение выполняет вычисление и использует два отдельных экземпляра сцены.The first application interfaces with MRTK, which uses the Scene Understanding SDK internally, the second app computes and uses two separate scene instances. Все три сцены на этой схеме создают отдельные экземпляры сцен, драйвер не отслеживает глобальное состояние, которое совместно используется приложениями, а объекты сцены в одной сцене не находятся в другой.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. Понятие "сцена" обеспечивает механизм для мониторинга со временем, но это делается с помощью пакета SDK.Scene Understanding does provide a mechanism to track over time, but this is done using the SDK. Код отслеживания уже выполняется в пакете SDK в процессе приложения.Tracking code is already running in the SDK in your app's process.

Поскольку каждый монтажный кадр хранит данные в памяти приложения, можно предположить, что все функции объекта сцены или внутренние данные всегда выполняются в процессе приложения.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

Для работы с представлением сцены может быть полезно знать и понять, как среда выполнения представляет компоненты логически и физически.To work with Scene Understanding, it may be valuable to know and understand how the runtime represents components logically and physically. Сцена представляет данные с определенным макетом, который был выбран для простоты при сохранении базовой структуры, плиабле в соответствии с будущими требованиями, не требуя значительных изменений.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. Сцена делает это, сохраняя все компоненты (стандартные блоки для всех объектов сцены) в плоском списке и определяя иерархию и композицию с помощью ссылок, где определенные компоненты ссылаются на другие.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.

Ниже представлен пример структуры как в плоской, так и в логической форме.Below we present an example of a structure in both its flat and logical form.

Логический макетLogical LayoutФизический макетPhysical Layout
    СценаScene
    • 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

На этом рисунке показана разница между физическим и логическим макетом сцены.This illustration highlights the difference between the physical and logical layout of the Scene. Слева мы видим иерархический макет данных, отображаемых приложением при перечислении сцены.On the left, we see the hierarchical layout of the data that your application sees when enumerating the scene. Справа видно, что сцена состоит из 12 отдельных компонентов, доступных по отдельности.On the right, we see that the scene is comprised of 12 distinct components that are accessible individually if necessary. При обработке новой сцены мы предполагаем, что приложения будут логически проходить эту иерархию, однако при отслеживании обновлений сцены некоторые приложения могут заинтересовать только те компоненты, которые являются общими для двух сцен.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.

Обзор APIAPI overview

В следующем разделе представлен общий обзор конструкций в представлении сцены.The following section provides a high-level overview of the constructs in Scene Understanding. В этом разделе вы узнаете, как представлено представление сцены, а также о том, для чего используются различные компоненты.Reading this section will give you an understanding of how scenes are represented, and what the various components do/are used for. В следующем разделе приводятся конкретные примеры кода и дополнительные сведения, которые будут включены в этот обзор.The next section will provide concrete code examples and additional details that are glossed over in this overview.

Все приведенные ниже типы находятся в Microsoft.MixedReality.SceneUnderstanding пространстве имен.All of the types described below reside in the Microsoft.MixedReality.SceneUnderstanding namespace.

сценекомпонентсSceneComponents

Теперь, когда вы понимаете логическую структуру сцен, теперь можно представить концепцию Сценекомпонентс и то, как они используются для создания иерархии.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 are the most granular decompositions in SceneUnderstanding representing a single core thing, for example, a mesh or a quad or a bounding box. Сценекомпонентс — это вещи, которые могут обновляться независимо друг от друга и на которые могут ссылаться другие Сценекомпонентс, поэтому у них есть одно глобальное свойство с уникальным ИДЕНТИФИКАТОРом, разрешающее этот тип механизма отслеживания и создания ссылок.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. Идентификаторы используются для логической композиции иерархии сцены, а также для сохранения объектов (действия по обновлению одной сцены относительно другой).Ids are used for the logical composition of scene hierarchy as well as object persistence (the act of updating one scene relative to another.)

Если вы обрабатываете все недавно вычисленные сцены как отличающиеся и просто перечисляете все данные внутри него, идентификаторы в значительной степени прозрачны.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. Однако если вы планируете отслеживание компонентов по нескольким обновлениям, вы будете использовать идентификаторы для индексирования и поиска Сценекомпонентс между объектами сцены.However, if you're planning to track components over several updates you'll use the Ids to index and find SceneComponents between Scene objects.

сценеобжектсSceneObjects

Сценеобжект — это Сценекомпонент, представляющий экземпляр "вещи", например стены, этаж, потолк и т. д. выражается по свойству 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 are geometric, and therefore have functions and properties that represent their location in space, however they don't contain any geometric or logical structure. Вместо этого Сценеобжектс ссылаться на другие Сценекомпонентс, в частности Сценекуадс и Сценемешес, которые предоставляют различные представления, поддерживаемые системой.Instead, SceneObjects reference other SceneComponents, specifically SceneQuads, and SceneMeshes, which provide the varied representations that are supported by the system. При вычислении новой сцены приложение, скорее всего, будет перечислять Сценеобжектс сцены, чтобы обработать его интерес.When a new scene is computed, your application will most likely enumerate the Scene's SceneObjects to process what it's interested in.

Сценеобжектс может иметь одно из следующих:SceneObjects can have any one of the following:

сценеобжекткиндSceneObjectKind ОписаниеDescription
Историческая справкаBackgroundИзвестно, что Сценеобжект не является одним из других распознаваемых видов объекта сцены.The SceneObject is known to be not one of the other recognized kinds of scene object. Этот класс не следует путать с неизвестным, где фон может не быть стенным, этажным, вытолоком и т. д. Хотя неизвестно, еще не классифицировано.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.
БрандмауэрWallФизическая стенка.A physical wall. Предполагается, что стены являются неперемещаемыми структурами окружающей среды.Walls are assumed to be immovable environmental structures.
ЭтажFloorПолs — это любые поверхности, на которых может пройти один проход.Floors are any surfaces on which one can walk. Примечание. лестница не является пол.Note: stairs aren't floors. Кроме того, обратите внимание, что в этом этаже предполагается любая неанализируемойная поверхность и, следовательно, нет явного предположений о единственном этаже.Also note, that floors assume any walkable surface and therefore there's no explicit assumption of a singular floor. Многоуровневые структуры, пандуси и т. д. Все категории должны классифицироваться как пол.Multi-level structures, ramps etc.... should all classify as floor.
CeilingCeilingВерхняя поверхность комнаты.The upper surface of a room.
ПлатформаPlatformКрупная плоская поверхность, на которую можно поместить голограммы.A large flat surface on which you could place holograms. Они обычно представляют таблицы, каунтертопс и другие крупные горизонтальные поверхности.These tend to represent tables, countertops, and other large horizontal surfaces.
WorldWorldЗарезервированная метка для геометрических данных, не зависящая от меток.A reserved label for geometric data that is agnostic to labeling. Сетка, созданная путем установки флага обновления Енаблеворлдмеш, будет классифицироваться как мир.The mesh generated by setting the EnableWorldMesh update flag would be classified as world.
НеизвестноUnknownЭтот объект сцены еще не классифицирован и ему назначен тип.This scene object has yet to be classified and assigned a kind. Это не следует путать с фоном, так как этот объект может быть любым, система просто не поступила с достаточной классификацией.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

Сценемеш — это Сценекомпонент, который приблизительно отражает геометрию произвольных геометрических объектов с помощью списка треугольников.A SceneMesh is a SceneComponent that approximates the geometry of arbitrary geometric objects using a triangle list. Сценемешес используются в нескольких разных контекстах, они могут представлять компоненты структуры ячеек ватертигхт или Ворлдмеш, представляющие неограниченную сетку пространственных сопоставлений, связанную с сценой.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. Данные индекса и вершины, предоставляемые в каждой сетке, используют тот же привычный макет, что и буферы вершин и индексов , которые используются для отрисовки сеток треугольников во всех современных API-интерфейсах отрисовки.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. В понимании сцены сетки используют 32-разрядные индексы и могут быть разбиты на фрагменты для определенных механизмов визуализации.In Scene Understanding, meshes use 32-bit indices and may need to be broken up into chunks for certain rendering engines.

Порядок поворота и системы координатWinding Order and Coordinate Systems

Все сетки, созданные при понимании сцены, должны возвращать сетки в Right-Handedной системе координат, используя порядок поворота по часовой стрелке.All meshes produced by Scene Understanding are expected to return meshes in a Right-Handed coordinate system using clockwise winding order.

Примечание. сборки ОС, выпущенные до. 191105, могут иметь известную ошибку, когда "мировые" сетки возвращались в Counter-Clockwise порядке обмотки, которая впоследствии была исправлена.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.

сценекуадSceneQuad

Сценекуад — это Сценекомпонент, представляющий двумерные поверхности, занимающие трехмерный мир.A SceneQuad is a SceneComponent that represents 2d surfaces that occupy the 3d world. Сценекуадс можно использовать аналогично ARKit Арпланеанчор или Аркоре плоскости, но они предлагают более высокоуровневые функции в виде двумерных холстов для использования в неструктурированных приложениях или дополненного UX.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. для четырех массивов предусмотрены двумерные API, которые делают размещение и разметку простыми в использовании, а разработка (за исключением отрисовки) с четырьмя областями должна быть более похожей на работу с плоскими холстами, чем с трехмерными сетками.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.

Сценекуад, фигураSceneQuad shape

Сценекуадс определить ограниченную прямоугольную поверхность в 2D.SceneQuads define a bounded rectangular surface in 2d. Однако Сценекуадс представляют поверхности с произвольными и потенциально сложными фигурами (например, с помощью кольцевой таблицы). Чтобы представить сложную форму, вы можете использовать API Жетсурфацемаск, чтобы отобразить форму поверхности в буфере изображения, который вы задаете.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. Если Сценеобжект, у которых имеется четырехъядерный объект, также есть сетка, то треугольники сетки должны быть эквивалентны этому визуализированному изображению. они представляют реальную геометрию поверхности в виде 2D-или трехмерных координат.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.

Сцены сведения о пакете SDK и справочникеScene understanding SDK details and reference

Следующий раздел поможет вам ознакомиться с основами Сценеундерстандинг.The following section will help get you familiar with the basics of SceneUnderstanding. В этом разделе приводятся основные сведения, в которых вы должны получить достаточно контекста для просмотра примеров приложений, чтобы увидеть, как Сценеундерстандинг используется глобально.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.

ИнициализацияInitialization

Первым шагом для работы с Сценеундерстандинг является получение ссылки на объект сцены в приложении.The first step to working with SceneUnderstanding is for your application to gain reference to a Scene object. Это можно сделать одним из двух способов: сцена может вычисляться драйвером, или существующая сцена, которая была вычислена в прошлом, может быть десериализована.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. Последнее полезно для работы с Сценеундерстандинг во время разработки, где приложения и опыт можно быстро создавать с помощью прототипа без устройства смешанной реальности.The latter is useful for working with SceneUnderstanding during development, where applications and experiences can be prototyped quickly without a mixed reality device.

Сцены вычисляются с помощью Сценеобсервер.Scenes are computed using a SceneObserver. Перед созданием сцены приложение должно запросить устройство, чтобы убедиться, что оно поддерживает Сценеундерстандинг, а также запросить доступ пользователей для получения информации, которая необходима Сценеундерстандинг.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();

Если не вызывается Рекуестакцессасинк (), то Вычисление новой сцены завершится ошибкой.If RequestAccessAsync() is not called, computing a new Scene will fail. Далее мы вычислим новую сцену, которая находится в корне вокруг гарнитуры смешанной реальности и имеет 10-измерительный радиус.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();

Инициализация из данных (также известных как.Initialization from Data (also known as. Путь к компьютеру)the PC Path)

В то время как сцены можно вычислять для прямого потребления, их также можно вычислить в сериализованной форме для последующего использования.While Scenes can be computed for direct consumption, they can also be computed in serialized form for later use. Это было признано полезным для разработки, так как оно позволяет разработчикам работать и тестировать сцены без необходимости использования устройства.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. Процесс сериализации сцены практически идентичен его вычислению, поэтому данные возвращаются в приложение, а не десериализуется локально с помощью пакета 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. Вы можете выполнить десериализацию самостоятельно или сохранить его для будущего использования.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

Перечисление СценеобжектSceneObject Enumeration

Теперь, когда приложение содержит сцену, приложение будет искать и взаимодействовать с Сценеобжектс.Now that your application has a scene, your application will be looking at and interacting with 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;
    }
}

Обновление компонентов и их поискComponent update and refinding components

Существует другая функция, которая извлекает компоненты в сцене с именем *финдкомпонент _.There's another function that retrieves components in the Scene called *FindComponent _. Эта функция полезна при обновлении объектов отслеживания и их поиске в последующих сценах.This function is useful when updating tracking objects and finding them in later scenes. Следующий код вычислит новую сцену относительно предыдущей сцены, а затем найдет этаж в новой сцене.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
}

Доступ к сеткам и четырем из объектов сценыAccessing Meshes and Quads from Scene Objects

После обнаружения Сценеобжектс приложение, скорее всего, захочет получить доступ к данным, содержащимся в потерях или в Объединенных в них сетках.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. Доступ к этим данным осуществляется с помощью свойств « *четыре* » и « *сетки* ».This data is accessed with the Quads and Meshes properties. Следующий код будет перечислять все четыре и сетки нашего объекта 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
}

Обратите внимание, что это Сценеобжект, который имеет преобразование относительно начала сцены.Notice that it's the SceneObject that has the transform that is relative to the Scene origin. Это обусловлено тем, что Сценеобжект представляет экземпляр "вещь" и размещаемые в пространстве, четыре части и сетки представляют геометрию, которая преобразуется относительно родительской.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. Можно использовать отдельный Сценеобжектс для ссылки на один и тот же Сценемеш или Сценекуад Сценекомпонентс, и возможно, что у Сценеобжект есть более одного Сценемеш/Сценекуад.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.

Работа с преобразованиямиDealing with Transforms

Понимание сцены предоставило намеренную попытку выполнить согласование с традиционными представлениями трехмерной сцены при работе с преобразованиями.Scene Understanding has made a deliberate attempt to align with traditional 3D scene representations when dealing with transforms. Таким образом, каждая сцена ограничена одной системой координат, похожей на наиболее распространенные трехмерные представления среды.Each Scene is therefore confined to a single coordinate system much like most common 3D environmental representations. Сценеобжектс каждый из них предоставляет свое расположение относительно этой системы координат.SceneObjects each provide their location relative to that coordinate system. Если ваше приложение работает с сценами, которые дотягивают ограничение на один источник, можно привязать Сценеобжектс к Спатиаланчорс или создать несколько сцен и объединить их вместе, но для простоты предполагается, что ватертигхт сцены существуют в собственном источнике, локализованном одним NodeId, определенным в сцене. Оригинспатиалграфнодеид.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.

В следующем коде Unity, например, показано, как использовать восприятие Windows и API Unity для совмещения систем координат.The following Unity code, for example, shows how to use Windows Perception and Unity APIs to align coordinate systems together. Дополнительные сведения о получении Спатиалкурдинатесистем, которые соответствуют источнику мира Unity, см. в статьях спатиалкурдинатесистем и спатиалграфинтероппревиев . подробные сведения о API восприятия Windows и собственные объекты смешанной реальности в 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;
}

Каждый SceneObject из них имеет преобразование, которое затем применяется к этому объекту.Each SceneObject has a transform, which is then applied to that object. В Unity преобразуются в правильные координаты и назначаются локальные преобразования следующим образом: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);
        

ЧетырехъядерныйQuad

Четыре из них были разработаны для упрощения сценариев размещения и должны рассматриваться как расширения для элементов UX в двумерных холстах.Quads were designed to help 2D placement scenarios and should be thought of as extensions to 2D canvas UX elements. Хотя четыре компонента являются компонентами Сценеобжектс и могут быть визуализированы в трехмерном виде, четыре интерфейса API предполагают, что четыре структуры являются 2D-структурами.While Quads are components of SceneObjects and can be rendered in 3D, the Quad APIs themselves assume Quads are 2D structures. Они предлагают такие сведения, как экстент, форма и предоставление API для размещения.They offer information such as extent, shape, and provide APIs for placement.

Четыре имеют прямоугольные экстенты, но они представляют собой произвольные геоповерхности.Quads have rectangular extents, but they represent arbitrarily shaped 2D surfaces. Чтобы включить размещение на этих 2D-поверхностях, взаимодействующих с четырьмя трехмерными средами, можно использовать служебные программы для обеспечения этого взаимодействия.To enable placement on these 2D surfaces that interact with the 3D environment quads offer utilities to make this interaction possible. В настоящее время понятие сцены предоставляет две такие функции: _ финдцентермостплацемент* и жетсурфацемаск.Currently Scene Understanding provides two such functions, _ FindCentermostPlacement* and GetSurfaceMask. Финдцентермостплацемент — это высокоуровневый API-интерфейс, который определяет положение, в котором можно поместить объект, и пытается найти лучшее место для объекта, гарантируя, что ограничивающий прямоугольник будет оставаться на базовой поверхности.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.

Примечание

Координаты выходных данных задаются относительно четырех в ««Quad» места с верхним левым углом (x = 0, y = 0), точно так же, как и с другими типами Rect 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. Не забудьте принять это в учетную запись при работе с источниками собственных объектов.Be sure to take this into account when working with the origins of your own objects.

В следующем примере показано, как найти центермост место и привязать голограмму к четырем.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)
            }
        }
    }
}

Шаги 1-4 сильно зависят от конкретной платформы или реализации, но темы должны быть похожи.Steps 1-4 are highly dependent on your particular framework/implementation, but the themes should be similar. Важно отметить, что четыре просто представляют ограниченную двухмерную плоскость, локализованную в пространстве.It's important to note that the Quad simply represents a bounded 2D plane that is localized in space. Если ваш модуль или платформа знает, где четыре – и в корне объекты находятся относительно четырех, то голограммы будут правильно располагаться в соответствии с реальным миром.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.

СеткаMesh

Сетки представляют геометрические представления объектов или сред.Meshes represent geometric representations of objects or environments. Подобно пространственному сопоставлению, индекс сетки и данные вершин, предоставляемые каждой сетке пространственных областей, используют тот же привычный макет, что и буферы вершин и индексов, которые используются для отрисовки сеток треугольников во всех современных API-интерфейсах отрисовки.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. Позиции вершин предоставляются в системе координат Scene .Vertex positions are provided in the coordinate system of the Scene. Ниже перечислены конкретные API-интерфейсы, используемые для ссылки на эти данные.The specific APIs used to reference this data are as follows:

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

В следующем коде приведен пример создания списка треугольников из структуры сетки.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);

Буферы индексов и вершин должны быть >= число индексов или вершин, но в противном случае можно произвольно изменять размер, допуская эффективное повторное использование памяти.The index/vertex buffers must be >= the index/vertex counts, but otherwise can be arbitrarily sized allowing for efficient memory reuse.

коллидермешColliderMesh

Объекты сцены обеспечивают доступ к сетке и данным в виде сетки через сетки и свойства Коллидермешес.Scene objects provide access to mesh and collider mesh data via the Meshes and ColliderMeshes properties. Эти сетки всегда будут соответствовать друг другу, то есть индекс и'с свойства "сетки" представляет ту же геометрию, что и индекс и'с свойства Коллидермешес.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. Если среда выполнения или объект поддерживает сетчатые конфликты, гарантированно получается наименьший многоугольник, приближение с наибольшим порядковым номером, и рекомендуется использовать Коллидермешес везде, где приложение будет использовать конфликты.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. Если система не поддерживает конфликты, объект сетки, возвращаемый в Коллидермешес, будет таким же, как и сетка, уменьшающая ограничения памяти.If the system does not support colliders the Mesh object returned in ColliderMeshes will be the same object as the mesh reducing memory constraints.

Общие сведения о разработке с использованием сценыDeveloping with scene understanding

На этом этапе вы должны понимать основные строительные блоки сцены, посвященные среде выполнения и пакету SDK.At this point, you should understand the core building blocks of the scene understanding runtime and SDK. Многие возможности и сложность основаны на шаблонах доступа, взаимодействии с трехмерными платформами и средствах, которые могут быть написаны поверх этих API для выполнения более сложных задач, таких как пространственное планирование, анализ комнаты, навигация, физика и т. д.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. Мы надеемся, что они записываются в примеры, которые будут надеяться вам в правильном направлении.We hope to capture these in samples that should hopefully guide you in the proper direction to make your scenarios shine. Если есть примеры или сценарии, которые мы не будем адресовать, сообщите нам, и мы попытаемся попытаться документировать или обменять нужные объекты.If there are samples or scenarios we aren't addressing, let us know and we'll try to document/prototype what you need.

Где можно получить пример кода?Where can I get sample code?

Пример кода для Unity, посвященный примеру, можно найти на странице образца страницы Unity .Scene Understanding sample code for Unity can be found on our Unity Sample Page page. Это приложение позволит вам взаимодействовать с устройством и визуализировать различные объекты сцены, или же оно позволит загрузить сериализованный монтажный кадр на ПК и позволит вам работать с сценами без устройства.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.

Где можно получить образцы сцен?Where can I get sample scenes?

Если у вас есть HoloLens2, можно сохранить любую сцену, которая была захвачена, сохранив выходные данные Компутесериализедасинк в файл и десериализовать ее в удобном для вас виде.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.

Если у вас нет устройства HoloLens2, но вы хотите играть со сведениями о сцене, вам потребуется скачать предварительно сохраненную сцену.If you don't have a HoloLens2 device but want to play with Scene Understanding, you'll need to download a pre-captured scene. В настоящее время пример использования сцены поставляются с серийными монтажными кадрами, которые можно скачать и использовать для удобства.The Scene Understanding sample currently ships with serialized scenes that can be downloaded and used at your own convenience. Их можно найти здесь:You can find them here:

Пример сцен для понимания сценыScene Understanding Sample Scenes

См. также статьюSee also