Como criar e localizar âncoras usando as Âncoras Espaciais do Azure no Swift

Âncoras Espaciais do Azure permitem que você compartilhe âncoras no mundo entre diferentes dispositivos. É compatível com vários ambientes de desenvolvimento diferentes. Neste artigo, nós nos aprofundaremos em como usar o SDK das Âncoras Espaciais do Azure no Swift para:

  • Configurar e gerenciar corretamente uma sessão das Âncoras Espaciais do Azure.
  • Criar e definir propriedades em âncoras locais.
  • Fazer upload delas na nuvem.
  • Localizar e excluir âncoras espaciais na nuvem.

Pré-requisitos

Para concluir este guia, verifique se você:

Multiplataforma

Inicializar a sessão

O ponto de entrada principal para o SDK é a classe que representa sua sessão. Normalmente, você vai declarar um campo na classe que gerencia sua exibição e a sessão do RA nativo.

Saiba mais sobre a classe ASACloudSpatialAnchorSession.

    var _cloudSession : ASACloudSpatialAnchorSession? = nil
    // In your view handler
    _cloudSession = ASACloudSpatialAnchorSession()

Configurar a autenticação

Para acessar o serviço, você precisa fornecer uma chave de conta, um token de acesso ou um token de autenticação do Azure Active Directory. Leia também mais sobre isso na página sobre o conceito de autenticação.

Chaves de conta

Chaves de conta são uma credencial que permite que o aplicativo seja autenticado no serviço Âncoras Espaciais do Azure. A finalidade pretendida das chaves de conta é ajudar você com uma rápida introdução. Especialmente durante a fase de desenvolvimento da integração do aplicativo às Âncoras Espaciais do Azure. Assim, você pode usar chaves de conta inserindo-as em seus aplicativos cliente durante o desenvolvimento. À medida que você progride para além do desenvolvimento, é altamente recomendável migrar para um mecanismo de autenticação que seja de nível de produção, com suporte de tokens de acesso ou da autenticação de usuário do Azure Active Directory. Para obter uma chave de conta para desenvolvimento, visite a sua conta das Âncoras Espaciais do Azure e navegue até a guia "Chaves".

Saiba mais sobre a classe ASASessionConfiguration.

    _cloudSession!.configuration.accountKey = "MyAccountKey"

Tokens de acesso

Tokens de acesso são um método mais robusto para autenticar com Âncoras Espaciais do Azure. Isso é válido especialmente à medida que você prepara seu aplicativo para uma implantação de produção. O resumo dessa abordagem é configurar um serviço de back-end com o qual seu aplicativo cliente possa se autenticar com segurança. O serviço de back-end interage com o AAD em runtime e com o serviço de token de Âncoras Espaciais do Azure para solicitar um token de acesso. Esse token é então entregue ao aplicativo cliente e usado no SDK para autenticar com as Âncoras Espaciais do Azure.

    _cloudSession!.configuration.accessToken = "MyAccessToken"

Se um token de acesso não estiver definido, você deverá manipular o evento TokenRequired ou implementar o método tokenRequired no protocolo delegado.

Você pode manipular o evento de maneira síncrona definindo a propriedade nos argumentos do evento.

Saiba mais sobre o método de protocolo tokenRequired.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        args.accessToken = "MyAccessToken"
    }

Se precisar executar o trabalho assíncrono em seu manipulador, você poderá adiar a configuração do token solicitando um objeto deferral e depois concluindo-o, como no exemplo a seguir.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        let deferral = args.getDeferral()
        myGetTokenAsync( withCompletionHandler: { (myToken: String?) in
            if (myToken != nil) {
                args.accessToken = myToken
            }
            deferral?.complete()
        })
    }

Autenticação do Azure Active Directory

As Âncoras Espaciais do Azure também permitem que os aplicativos se autentiquem com tokens de usuário do Azure AD (Active Directory). Por exemplo, você pode usar tokens do Azure AD para integrar com Âncoras Espaciais do Azure. Se uma empresa mantém usuários no Azure AD, você pode fornecer um token de usuário do Azure AD no SDK de Âncoras Espaciais do Azure. Fazer isso permite que você autentique diretamente no serviço de Âncoras Espaciais do Azure para uma conta que faz parte do mesmo locatário do Azure AD.

    _cloudSession!.configuration.authenticationToken = "MyAuthenticationToken"

Assim como os tokens de acesso, se um token do Azure AD não estiver definido, você deverá manipular o evento TokenRequired ou implementar o método tokenRequired no protocolo delegado.

Você pode manipular o evento de maneira síncrona definindo a propriedade nos argumentos do evento.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        args.authenticationToken = "MyAuthenticationToken"
    }

Se precisar executar o trabalho assíncrono em seu manipulador, você poderá adiar a configuração do token solicitando um objeto deferral e depois concluindo-o, como no exemplo a seguir.

    internal func tokenRequired(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASATokenRequiredEventArgs!) {
        let deferral = args.getDeferral()
        myGetTokenAsync( withCompletionHandler: { (myToken: String?) in
            if (myToken != nil) {
                args.authenticationToken = myToken
            }
            deferral?.complete()
        })
    }

Configurar a biblioteca

Invoque Start() para habilitar sua sessão a processar os dados do ambiente.

Para manipular eventos gerados pela sua sessão, defina a propriedade delegate de sua sessão para um objeto, como o modo de exibição. Esse objeto deve implementar o protocolo SSCCloudSpatialAnchorSessionDelegate.

Saiba mais sobre o método start.

    _cloudSession!.session = self.sceneView.session;
    _cloudSession!.delegate = self;
    _cloudSession!.start()

Fornecer quadros para a sessão

A sessão de âncora espacial funciona pelo mapeamento do espaço em torno do usuário. Fazer isso ajuda a determinar o local em que se encontram as âncoras. As plataformas móveis (iOS e Android) exigem uma chamada nativa ao feed da câmera para obter quadros da biblioteca RA da plataforma. Por outro lado, o HoloLens examina constantemente o ambiente e, portanto, não há necessidade de uma chamada específica como em plataformas móveis.

Saiba mais sobre o método processFrame.

    _cloudSession?.processFrame(self.sceneView.session.currentFrame)

Fornecer comentários ao usuário

Você pode escrever um código para processar o evento atualizado da sessão. Esse evento é acionado toda vez que a sessão aprimora a compreensão do ambiente em que você está. Essa ação permite que você:

  • Use a classe UserFeedback para fornecer comentários ao usuário à medida que o dispositivo for movido e a sessão atualizar a compreensão do ambiente. Para fazer isso,
  • Determine em que ponto há dados espaciais controlados suficientes para criar âncoras espaciais. Determine isso com ReadyForCreateProgress ou RecommendedForCreateProgress. Depois que ReadyForCreateProgress estiver acima de 1, teremos dados suficientes para salvar uma âncora espacial de nuvem, embora recomendemos aguardar até que RecommendedForCreateProgress esteja acima de 1 para fazer isso.

Saiba mais sobre o método de protocolo sessionUpdated.

    internal func sessionUpdated(_ cloudSession:ASACloudSpatialAnchorSession!, _ args:ASASessionUpdatedEventArgs!) {
        let status = args.status!
        if (status.userFeedback.isEmpty) {
            return
        }
        _feedback = "Feedback: \(FeedbackToString(userFeedback:status.userFeedback)) - Recommend Create=\(status.recommendedForCreateProgress * 100)"
    }

Criar uma âncora espacial de nuvem

Para criar uma âncora espacial de nuvem, primeiro crie uma âncora no sistema RA da plataforma e, em seguida, crie um equivalente na nuvem. Use o método CreateAnchorAsync().

Saiba mais sobre a classe ASACloudSpatialAnchor.

    // Create a local anchor, perhaps by hit-testing and creating an ARAnchor
    var localAnchor : ARAnchor? = nil
    let hits = self.sceneView.session.currentFrame?.hitTest(CGPoint(x:0.5, y:0.5), types: ARHitTestResult.ResultType.estimatedHorizontalPlane)
    if (hits!.count == 0) return
    // The hitTest method sorts the resulting list by increasing distance from the camera
    // The first hit result will usually be the most relevant when responding to user input
    localAnchor = ARAnchor(transform:hits![0].worldTransform)
    self.sceneView.session.add(anchor: _localAnchor!)

    // If the user is placing some application content in their environment,
    // you might show content at this anchor for a while, then save when
    // the user confirms placement.
    var cloudAnchor : ASACloudSpatialAnchor? = nil
    cloudAnchor = ASACloudSpatialAnchor()
    cloudAnchor!.localAnchor = localAnchor
    _cloudSession?.createAnchor(cloudAnchor!, withCompletionHandler: { (error: Error?) in
        if (error != nil) {
            _feedback = "Save Failed:\(error!.localizedDescription)"
            return
        }
        _feedback = "Created a cloud anchor with ID=\(cloudAnchor!.identifier!)"
    })

Conforme descrito anteriormente, você precisará ter dados do ambiente suficientes capturados antes de tentar criar uma âncora espacial de nuvem. Isso significa que ReadyForCreateProgress precisa estar acima de 1, embora recomendemos aguardar até que RecommendedForCreateProgress esteja acima de 1 para fazer isso.

Saiba mais sobre o método getStatusWithCompletionHandler.

    _cloudSession?.getStatusWithCompletionHandler( { (value:ASASessionStatus, error:Error?) in
        if (error != nil) {
            _feedback = "Session status error:\(error!.localizedDescription)"
            return
        }
        if (value!.recommendedForCreateProgress <> 1.0) {
            return
        }
        // Issue the creation request ...
    })

Definir propriedades

Você pode optar por adicionar algumas propriedades ao salvar suas âncoras espaciais de nuvem. Como o tipo de objeto que está sendo salvo ou as propriedades básicas, como se elas devem ser habilitadas para interação. Fazer isso pode ser útil na descoberta: você pode renderizar imediatamente o objeto para o usuário, por exemplo, um quadro de imagem com o conteúdo em branco. Em seguida, um download diferente em segundo plano obtém detalhes de estado adicionais, por exemplo, a imagem a ser exibida no quadro.

Saiba mais sobre a propriedade appProperties.

    var cloudAnchor : ASACloudSpatialAnchor? = nil
    cloudAnchor = ASACloudSpatialAnchor()
    cloudAnchor!.localAnchor = localAnchor
    cloudAnchor!.appProperties = [ "model-type" : "frame", "label" : "my latest picture" ]
    _cloudSession?.createAnchor(cloudAnchor!, withCompletionHandler: { (error: Error?) in
        // ...
    })

Atualizar as propriedades

Para atualizar as propriedades em uma âncora, use o método UpdateAnchorProperties(). Se dois ou mais dispositivos tentarem atualizar as propriedades para a mesma âncora ao mesmo tempo, usaremos um modelo de simultaneidade otimista. Ou seja, a primeira gravação ganhará. Todas as outras gravações receberão um erro de "Simultaneidade": uma atualização das propriedades será necessária antes que seja possível tentar novamente.

Saiba mais sobre o método updateAnchorProperties.

    var anchor : ASACloudSpatialAnchor? = /* locate your anchor */;
    anchor!.appProperties["last-user-access"] = "just now"
    _cloudSession?.updateAnchorProperties(anchor!, withCompletionHandler: { (error:Error?) in
        if (error != nil) {
            _feedback = "Updating Properties Failed:\(error!.localizedDescription)"
        }
    })

Não é possível atualizar o local de uma âncora após ela ter sido criada no serviço: você precisa criar uma âncora e excluir a antiga para acompanhar uma nova posição.

Se você não precisar localizar uma âncora para atualizar as propriedades dela, poderá usar o método GetAnchorPropertiesAsync(), que retorna um objeto CloudSpatialAnchor com propriedades.

Saiba mais sobre o método getAnchorProperties.

    _cloudSession?.getAnchorProperties("anchorId", withCompletionHandler: { (anchor:SCCCloudSpatialAnchor?, error:Error?) in
        if (error != nil) {
            _feedback = "Getting Properties Failed:\(error!.localizedDescription)"
        }
        if (anchor != nil) {
            anchor!.appProperties["last-user-access"] = "just now"
            _cloudSession?.updateAnchorProperties(anchor!, withCompletionHandler: { (error:Error?) in
                // ...
            })
        }
    })

Definir a validade

Também é possível configurar sua âncora para expirar automaticamente em uma determinada data no futuro. Quando uma âncora expirar, ela não será mais localizada nem atualizada. A expiração só pode ser definida quando a âncora é criada, antes de salvá-la na nuvem. Não é possível atualizar a expiração posteriormente. Se nenhuma expiração for definida durante a criação da âncora, a âncora só expirará quando excluída manualmente.

Saiba mais sobre a propriedade expiration.

    let secondsInAWeek = 60.0 * 60.0 * 24.0 * 7.0
    let oneWeekFromNow = Date(timeIntervalSinceNow: secondsInAWeek)
    cloudAnchor!.expiration = oneWeekFromNow

Localizar uma âncora espacial de nuvem

Ser capaz de localizar uma âncora espacial de nuvem salva anteriormente é um dos principais motivos para usar as Âncoras Espaciais do Azure. Para isso, estamos usando "Observadores". Você só pode usar um Observador por vez; não há suporte para vários Observadores. Há várias maneiras diferentes (também conhecidas como Estratégias de Localização de Âncora) para um Observador localizar uma âncora espacial de nuvem. Você pode usar uma estratégia em um observador por vez.

  • Localizar âncoras por identificador.
  • Localizar âncoras conectadas a uma âncora localizada anteriormente. Saiba mais sobre as relações entre âncoras aqui.
  • Localizar âncora usando a Relocalização grosseira.

Observação

Cada vez que você localizar uma âncora, as Âncoras Espaciais do Azure tentarão usar os dados do ambiente coletados para aumentar as informações visuais na âncora. Se você tiver problemas para localizar uma âncora, poderá ser útil criar uma âncora e, em seguida, localizá-la várias vezes de diferentes ângulos e condições de iluminação.

Se estiver localizando âncoras espaciais de nuvem por identificador, você poderá armazenar o identificador da âncora espacial de nuvem no serviço de back-end do seu aplicativo e torná-lo acessível para todos os dispositivos que puderem se autenticar a ele corretamente. Para ver um exemplo disso, confira Tutorial: Compartilhar âncoras espaciais entre dispositivos.

Crie uma instância de um objeto AnchorLocateCriteria, defina os identificadores que está procurando e invoque o método CreateWatcher na sessão fornecendo seu AnchorLocateCriteria.

Saiba mais sobre o método createWatcher.

    let criteria = ASAAnchorLocateCriteria()!
    criteria.identifiers = [ "id1", "id2", "id3" ]
    _cloudSession!.createWatcher(criteria)

Depois que o observador for criado, o evento AnchorLocated será acionado para cada âncora solicitada. Esse evento é acionado quando uma âncora é localizada ou se a âncora não puder ser localizada. Se essa situação ocorrer, o motivo será indicado no status. Após todas as âncoras de um observador serem processadas, sejam elas encontradas ou não, o evento LocateAnchorsCompleted será acionado. Há um limite de 35 identificadores por observador.

Saiba mais sobre o método de protocolo anchorLocated.

    internal func anchorLocated(_ cloudSession: ASACloudSpatialAnchorSession!, _ args: ASAAnchorLocatedEventArgs!) {
        let status = args.status
        switch (status) {
        case ASALocateAnchorStatus.located:
            let foundAnchor = args.anchor
            // Go add your anchor to the scene...
            break
        case ASALocateAnchorStatus.alreadyTracked:
            // This anchor has already been reported and is being tracked
            break
        case ASALocateAnchorStatus.notLocatedAnchorDoesNotExist:
            // The anchor was deleted or never existed in the first place
            // Drop it, or show UI to ask user to anchor the content anew
            break
        case ASALocateAnchorStatus.notLocated:
            // The anchor hasn't been found given the location data
            // The user might in the wrong location, or maybe more data will help
            // Show UI to tell user to keep looking around
            break
        }
    }

Excluir âncoras

Excluir âncoras quando elas não forem mais usadas é uma boa prática para incluir no início do seu processo e práticas de desenvolvimento para manter os recursos do Azure limpos.

Saiba mais sobre o método delete.

    _cloudSession?.delete(cloudAnchor!, withCompletionHandler: { (error: Error?) in
        // Perform any processing you may want when delete finishes
    })

Pausar, redefinir ou interromper a sessão

Para interromper a sessão temporariamente, você pode invocar Stop(). Isso interromperá inspetores e o processamento de ambiente, mesmo se você invocar ProcessFrame(). Em seguida, você pode invocar Start() para retomar o processamento. Ao retomar, os dados de ambiente já capturados na sessão são mantidos.

Saiba mais sobre o método stop.

    _cloudSession!.stop()

Para redefinir os dados de ambiente que foram capturados em sua sessão, você pode invocar Reset().

Saiba mais sobre o método reset.

    _cloudSession!.reset()

Para realizar a limpeza corretamente após uma sessão, libere todas as referências.

    _cloudSession = nil

Próximas etapas

Neste guia, você aprendeu sobre como criar e localizar âncoras usando o SDK das Âncoras Espaciais do Azure. Para saber mais sobre os relacionamentos de âncora, vá para o próximo guia.