Como criar e localizar âncoras usando as Âncoras Espaciais do Azure no Objective-C
Â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 Objective-C 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ê:
- Leia a Visão geral de Âncoras Espaciais do Azure.
- Concluído um dos Inícios Rápidos de 5 minutos.
- Conhecimento básico sobre o Objective-C.
- Conhecimento básico sobre o ARKit.
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.
ASACloudSpatialAnchorSession *_cloudSession;
// In your view handler
_cloudSession = [[ASACloudSpatialAnchorSession alloc] init];
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 Microsoft Entra. 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ê avança além do desenvolvimento, é altamente recomendável migrar para um mecanismo de autenticação que seja de nível de produção, que dê suporte a tokens de acesso ou à autenticação de usuário do Microsoft Entra. 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.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
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.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) args.accessToken = myToken;
[deferral complete];
}];
}
autenticação do Microsoft Entra
As Âncoras Espaciais do Azure também permitem que os aplicativos se autentiquem com tokens do Microsoft Entra ID (Active Directory). Por exemplo, você pode usar tokens do Microsoft Entra para se integrar ao serviço Âncoras Espaciais do Azure. Se uma empresa mantiver usuários no Microsoft Entra ID, você poderá fornecer um token de usuário do Microsoft Entra no SDK do Âncoras Espaciais do Azure. Isso permite que você se autentique diretamente no serviço Âncoras Espaciais do Azure para uma conta que faz parte do mesmo locatário do Microsoft Entra.
_cloudSession.configuration.authenticationToken = @"MyAuthenticationToken";
Assim como acontece com tokens de acesso, se um token do Microsoft Entra 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.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
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.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) 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:_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
UserFeedbackpara 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
ReadyForCreateProgressouRecommendedForCreateProgress. Depois queReadyForCreateProgressestiver acima de 1, teremos dados suficientes para salvar uma âncora espacial de nuvem, embora recomendemos aguardar até queRecommendedForCreateProgressesteja acima de 1 para fazer isso.
Saiba mais sobre o método de protocolo sessionUpdated.
- (void)sessionUpdated:(ASACloudSpatialAnchorSession *)cloudSession :(ASASessionUpdatedEventArgs *)args {
ASASessionStatus *status = [args status];
if (status.userFeedback == ASASessionUserFeedbackNone) return;
_feedback = [NSString
stringWithFormat:@"Feedback: %@ - Recommend Create=%.0f%%",
FeedbackToString(status.userFeedback),
status.recommendedForCreateProgress * 100.f];
}
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
NSArray<ARHitTestResult *> *hits = [_sceneView.session.currentFrame hitTest:CGPointMake(0.5, 0.5) types:ARHitTestResultTypeEstimatedHorizontalPlane];
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
ARAnchor *localAnchor = [[ARAnchor alloc] initWithTransform:hits[0].worldTransform];
[_sceneView.session addAnchor: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.
ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
cloudAnchor.localAnchor = localAnchor;
[_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Save Failed:%@", error.localizedDescription];
return;
}
_feedback = [NSString stringWithFormat:@"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 getSessionStatusWithCompletionHandler.
[_cloudSession getSessionStatusWithCompletionHandler:^(ASASessionStatus *value, NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Session status error:%@", error.localizedDescription];
return;
}
if (value.recommendedForCreateProgress < 1.0f) 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.
ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
cloudAnchor.localAnchor = localAnchor;
cloudAnchor.appProperties = @{ @"model-type" : @"frame", @"label" : @"my latest picture" };
[_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// ...
});
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.
ASACloudSpatialAnchor *anchor = /* locate your anchor */;
[anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
[_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
if (error) _feedback = [NSString stringWithFormat:@"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:^(SCCCloudSpatialAnchor *anchor, NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Getting Properties Failed:%@", error.localizedDescription];
return;
}
if (anchor) {
[anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
[_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
// ...
}];
}
}];
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.
int secondsInAWeek = 60 * 60 * 24 * 7;
NSDate *oneWeekFromNow = [[NSDate alloc] initWithTimeIntervalSinceNow: (NSTimeInterval) 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.
ASAAnchorLocateCriteria *criteria = [ASAAnchorLocateCriteria new];
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.
- (void)anchorLocated:(ASACloudSpatialAnchorSession *)cloudSession :(ASAAnchorLocatedEventArgs *)args {
ASALocateAnchorStatus status = [args status];
switch (status) {
case ASALocateAnchorStatusLocated: {
ASACloudSpatialAnchor *foundAnchor = [args anchor];
// Go add your anchor to the scene...
}
break;
case ASALocateAnchorStatusAlreadyTracked:
// This anchor has already been reported and is being tracked
break;
case ASALocateAnchorStatusNotLocatedAnchorDoesNotExist:
// 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 ASALocateAnchorStatusNotLocated:
// 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 deleteAnchor.
[_cloudSession deleteAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// 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 = NULL;
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.