Criar um fornecedor de dados do sistema de sensibilização espacial – MRTK2

  • Artigo

O sistema de Sensibilização Espacial é um sistema extensível para fornecer às aplicações dados sobre ambientes do mundo real. Para adicionar suporte para uma nova plataforma de hardware ou uma nova forma de dados de Sensibilização Espacial, pode ser necessário um fornecedor de dados personalizado.

Este artigo descreve como criar fornecedores de dados personalizados, também denominados Observadores Espaciais, para o sistema de Sensibilização Espacial. O código de exemplo apresentado aqui é da implementação da SpatialObjectMeshObserver classe, que é útil para carregar dados de malha 3D no editor.

Nota

O código fonte completo utilizado neste exemplo pode ser encontrado na Assets/MRTK/Providers/ObjectMeshObserver pasta.

Espaço de nomes e estrutura de pastas

Os fornecedores de dados podem ser distribuídos de uma de duas formas:

  1. Suplementos de terceiros
  2. Parte do Microsoft Mixed Reality Toolkit

O processo de aprovação das submissões de novos fornecedores de dados ao MRTK variará caso a caso e será comunicado no momento da proposta inicial. As propostas podem ser submetidas ao criar um novo problema de tipo de Pedido de Funcionalidade.

Suplemento de terceiros

Espaço de Nomes

Os fornecedores de dados têm de ter um espaço de nomes para mitigar potenciais colisões de nomes. Recomenda-se que o espaço de nomes inclua os seguintes componentes.

  • Nome da empresa que produz o suplemento
  • Área de funcionalidades

Por exemplo, um fornecedor de dados de Sensibilização Espacial criado e enviado pela empresa Contoso pode ser "Contoso.MixedReality.Toolkit.SpatialAwareness".

Estrutura de pastas

Recomenda-se que o código fonte dos fornecedores de dados seja apresentado numa hierarquia de pastas, conforme mostrado na imagem seguinte.

Exemplo de estrutura de pasta

Quando a pasta ContosoSpatialAwareness contém a implementação do fornecedor de dados, a pasta Editor contém o inspector (e qualquer outro código específico do editor do Unity) e a pasta Perfis contém um ou mais objetos scriptable de perfil pré-criados.

Submissão do MRTK

Espaço de Nomes

Se um fornecedor de dados do sistema de deteção espacial estiver a ser submetido para o repositório do Mixed Reality Toolkit, o espaço de nomes tem de começar por Microsoft.MixedReality.Toolkit (ex: Microsoft.MixedReality.Toolkit.SpatialObjectMeshObserver)

e o código deve estar localizado numa pasta abaixo de MRTK/Providers (por exemplo: MRTK/Providers/ObjectMeshObserver).

Estrutura de pastas

Todo o código deve estar localizado numa pasta abaixo de MRTK/Providers (por exemplo: MRTK/Providers/ObjectMeshObserver).

Definir o objeto de dados espaciais

O primeiro passo na criação de um fornecedor de dados de Sensibilização Espacial é determinar o tipo de dados (por exemplo: malhas ou planos) que irá fornecer às aplicações.

Todos os objetos de dados espaciais têm de implementar a IMixedRealitySpatialAwarenessObject interface.

A base Mixed Reality Toolkit fornece os seguintes objetos espaciais que podem ser utilizados ou expandidos em novos fornecedores de dados.

Implementar o fornecedor de dados

Especificar a herança da interface e/ou da classe base

Todos os fornecedores de dados de Sensibilização Espacial têm de implementar a IMixedRealitySpatialAwarenessObserver interface, que especifica a funcionalidade mínima exigida pelo sistema de Sensibilização Espacial. A base MRTK inclui a BaseSpatialObserver classe que fornece uma implementação predefinida desta funcionalidade necessária.

public class SpatialObjectMeshObserver :
    BaseSpatialObserver,
    IMixedRealitySpatialAwarenessMeshObserver,
    IMixedRealityCapabilityCheck
{ }

Nota

A IMixedRealityCapabilityCheck interface é utilizada pela SpatialObjectMeshObserver classe para indicar que fornece suporte para a capacidade SpatialAwarenessMesh.

Aplicar o atributo MixedRealityDataProvider

Um passo fundamental na criação de um fornecedor de dados de Sensibilização Espacial é aplicar o MixedRealityDataProvider atributo à classe. Este passo permite definir o perfil e as plataformas predefinidos para o fornecedor de dados, quando selecionados no perfil de Sensibilização Espacial, bem como Nome, caminho da pasta e muito mais.

[MixedRealityDataProvider(
    typeof(IMixedRealitySpatialAwarenessSystem),
    SupportedPlatforms.WindowsEditor | SupportedPlatforms.MacEditor | SupportedPlatforms.LinuxEditor,
    "Spatial Object Mesh Observer",
    "ObjectMeshObserver/Profiles/DefaultObjectMeshObserverProfile.asset",
    "MixedRealityToolkit.Providers")]
public class SpatialObjectMeshObserver :
    BaseSpatialObserver,
    IMixedRealitySpatialAwarenessMeshObserver,
    IMixedRealityCapabilityCheck
{ }

Implementar os métodos IMixedRealityDataProvider

Assim que a classe tiver sido definida, o próximo passo é fornecer a implementação da IMixedRealityDataProvider interface.

Nota

A BaseSpatialObserver classe, através da BaseService classe, fornece apenas uma implementação vazia para IMixedRealityDataProvider métodos. Os detalhes destes métodos são geralmente específicos do fornecedor de dados.

Os métodos que devem ser implementados pelo fornecedor de dados são:

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

Implementar a lógica do fornecedor de dados

O próximo passo é adicionar a lógica do fornecedor de dados ao implementar a interface de fornecedor de dados específica, por exemplo IMixedRealitySpatialAwarenessMeshObserver. Normalmente, esta parte do fornecedor de dados será específica da plataforma.

Notificações de alteração de observação

Para permitir que as aplicações respondam a alterações na compreensão do ambiente pelo dispositivo, o fornecedor de dados gera eventos de notificação conforme definido na IMixedRealitySpatialAwarenessObservationtHandler<T> interface.

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

O código seguinte dos SpatialObjectMeshObserver exemplos demonstra a criação e o evento quando os dados de malha são adicionados.

// The data to be sent when mesh observation events occur.
// This member variable is initialized as part of the Initialize() method.
private MixedRealitySpatialAwarenessEventData<SpatialAwarenessMeshObject> meshEventData = null;

/// <summary>
/// Sends the observations using the mesh data contained within the configured 3D model.
/// </summary>
private void SendMeshObjects()
{
    if (!sendObservations) { return; }

    if (spatialMeshObject != null)
    {
        MeshFilter[] meshFilters = spatialMeshObject.GetComponentsInChildren<MeshFilter>();
        for (int i = 0; i < meshFilters.Length; i++)
        {
            SpatialAwarenessMeshObject meshObject = SpatialAwarenessMeshObject.Create(
                meshFilters[i].sharedMesh,
                MeshPhysicsLayer,
                $"Spatial Object Mesh {currentMeshId}",
                currentMeshId,
                ObservedObjectParent);

            meshObject.GameObject.transform.localPosition = meshFilters[i].transform.position;
            meshObject.GameObject.transform.localRotation = meshFilters[i].transform.rotation;

            ApplyMeshMaterial(meshObject);

            meshes.Add(currentMeshId, meshObject);

            // Initialize the meshEventData variable with data for the added event.
            meshEventData.Initialize(this, currentMeshId, meshObject);
            // Raise the event via the spatial awareness system.
            SpatialAwarenessSystem?.HandleEvent(meshEventData, OnMeshAdded);

            currentMeshId++;
        }
    }

    sendObservations = false;
}

Nota

A SpatialObjectMeshObserver classe não gera OnObservationUpdated eventos, uma vez que o modelo 3D só é carregado uma vez. A implementação na WindowsMixedRealitySpatialMeshObserver classe fornece um exemplo de criação de um OnObservationUpdated evento para uma malha observada.

Adicionar instrumentação do Unity Profiler

O desempenho é fundamental em aplicações de realidade mista. Cada componente adiciona alguma quantidade de sobrecarga para as aplicações que têm de ter conta. Para tal, é importante que todos os fornecedores de dados de sensibilização espacial contenham instrumentação do Unity Profiler em ciclo interno e caminhos de código frequentemente utilizados.

Recomenda-se implementar o padrão utilizado pelo MRTK ao instrumentar fornecedores personalizados.

        private static readonly ProfilerMarker UpdateObserverPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealitySpatialMeshObserver.UpdateObserver");

        /// <summary>
        /// Requests updates from the surface observer.
        /// </summary>
        private void UpdateObserver()
        {
            using (UpdateObserverPerfMarker.Auto())
            {
                // Code to be measured.
            }
        }

Nota

O nome utilizado para identificar o marcador do gerador de perfis é arbitrário. O MRTK utiliza o seguinte padrão.

"[product] className.methodName - nota opcional"

Recomenda-se que os fornecedores de dados personalizados sigam um padrão semelhante para ajudar a simplificar a identificação de componentes e métodos específicos ao analisar rastreios.

Criar o perfil e o inspetor

No Mixed Reality Toolkit, os fornecedores de dados são configurados com perfis.

Definir o perfil

Os conteúdos do perfil devem espelhar as propriedades acessíveis do fornecedor de dados (por exemplo, intervalo de atualização). Todas as propriedades configuráveis do utilizador definidas em cada interface devem ser contidas no perfil.

As classes base são incentivadas se um novo fornecedor de dados expandir um fornecedor existente. Por exemplo, o SpatialObjectMeshObserverProfile expande o para permitir que os MixedRealitySpatialAwarenessMeshObserverProfile clientes forneçam um modelo 3D para ser utilizado como os dados do ambiente.

[CreateAssetMenu(
    menuName = "Mixed Reality Toolkit/Profiles/Spatial Object Mesh Observer Profile",
    fileName = "SpatialObjectMeshObserverProfile",
    order = 100)]
public class SpatialObjectMeshObserverProfile : MixedRealitySpatialAwarenessMeshObserverProfile
{
    [SerializeField]
    [Tooltip("The model containing the desired mesh data.")]
    private GameObject spatialMeshObject = null;

    /// <summary>
    /// The model containing the desired mesh data.
    /// </summary>
    public GameObject SpatialMeshObject => spatialMeshObject;
}

O CreateAssetMenu atributo pode ser aplicado à classe de perfil para permitir que os clientes criem uma instância de perfil com o menu Criar>Recursos> Mixed RealityPerfis do Toolkit>.

Implementar o inspetor

Os inspetores de perfis são a interface de utilizador para configurar e visualizar conteúdos de perfil. Cada inspetor de perfis deve expandir a BaseMixedRealityToolkitConfigurationProfileInspector classe.

O CustomEditor atributo informa o Unity do tipo de recurso a que o inspector se aplica.

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

Criar definições de assemblagem

Mixed Reality Toolkit utiliza ficheiros de definição de assemblagem (.asmdef) para especificar dependências entre componentes, bem como para ajudar o Unity a reduzir o tempo de compilação.

Recomenda-se que os ficheiros de definição de assemblagem sejam criados para todos os fornecedores de dados e respetivos componentes de editor.

Ao utilizar a estrutura de pastas no exemplo anterior, haveria dois ficheiros .asmdef para o fornecedor de dados ContosoSpatialAwareness.

A primeira definição de assemblagem destina-se ao fornecedor de dados. Para este exemplo, será denominado Deteção ContosoSpatial e estará localizado na pasta ContosoSpatialAwareness do exemplo. Esta definição de assemblagem tem de especificar uma dependência em Microsoft.MixedReality.Toolkit e em quaisquer outras assemblagens de que dependa.

A definição de assemblagem ContosoInputEditor especificará o inspetor de perfis e qualquer código específico do editor. Este ficheiro tem de estar localizado na pasta raiz do código do editor. Neste exemplo, o ficheiro estará localizado na pasta ContosoSpatialAwareness\Editor . Esta definição de assemblagem irá conter uma referência à assemblagem ContosoSpatialAwareness, bem como:

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

Registar o fornecedor de dados

Depois de criado, o fornecedor de dados pode ser registado no sistema de Sensibilização Espacial para ser utilizado na aplicação.

Selecionar o observador de malha de objeto espacial

Empacotamento e distribuição

Os fornecedores de dados distribuídos como componentes de terceiros têm os detalhes específicos de empacotamento e distribuição deixados à preferência do programador. Provavelmente, a solução mais comum será gerar um .unitypackage e distribuir através do Unity Asset Store.

Se um fornecedor de dados for submetido e aceite como parte do pacote Microsoft Mixed Reality Toolkit, a equipa do Microsoft MRTK irá empacotá-lo e distribuí-lo como parte das ofertas do MRTK.

Ver também