Guia do desenvolvedor do Cloud Anchors para iOS

O SDK do ARCore para iOS interage com o ARKit para fornecer o Cloud Anchor permitindo que você compartilhe âncoras entre dispositivos iOS e Android na mesmo ambiente.

Saiba como usar a API ARCore Cloud Anchor ou o serviço ARCore Cloud Anchor nos seus apps.

Pré-requisitos

  • Xcode versão 13.0 ou mais recente
  • Cocoapods 1.4.0 ou mais recente, se estiver usando o Cocoapods
  • Um dispositivo Apple compatível com o ARKit com o iOS 12.0 ou mais recente (é necessário ter o destino de implantação do iOS 12.0 ou mais recente)

Se você não conhece os Cloud Anchors:

Ativar as Cloud Anchors no seu app

Para usar a API Cloud Anchors, é necessário criar um GARSessionConfiguration e definir a propriedade cloudAnchorMode para ele, conforme descrito em Configurar uma sessão do ARCore no iOS. Usar setConfiguration:error: (GARSession) para definir a configuração.

Você também precisa ativar a API ARCore no seu app.

Hospedar e resolver âncoras

É possível hospedar e resolver âncoras da nuvem com a API ARCore Cloud Anchor. A API inclui métodos de callback para operações concluídas, além de objetos Future que podem ser pesquisados.

Hospedar uma âncora

Hospedar um ARAnchor coloca a âncora em um sistema de coordenadas comum para qualquer espaço físico.

Uma solicitação de host envia dados visuais para um servidor do Google, que mapeia o ARAnchor posição em um sistema de coordenadas que representa o espaço físico atual. Uma solicitação de host bem-sucedida retorna um novo ID do Cloud Anchor, que pode ser compartilhado e usado para resolver a âncora mais tarde.

- (void)addAnchorWithTransform:(matrix_float4x4)transform {
  self.arAnchor = [[ARAnchor alloc] initWithTransform:transform];
  [self.sceneView.session addAnchor:self.arAnchor];

  __weak ExampleViewController *weakSelf = self;
  self.hostFuture = [self.cloudAnchorManager
      hostCloudAnchor:self.arAnchor
           completion:^(NSString *anchorId, GARCloudAnchorState cloudState) {
             [weakSelf handleHostAnchor:anchorId cloudState:cloudState];
           }
                error:nil];
  [self enterState:HelloARStateHosting];
}

Resolver uma âncora

Resolver uma ARAnchor permite que dispositivos Android e iOS em um determinado espaço físico. para adicionar âncoras hospedadas anteriormente a novas cenas.

Uma solicitação de resolução envia um ID de âncora de nuvem a um servidor do Google com dados visuais do frame atual. O servidor tentará fazer a correspondência desses dados visuais com as imagens de onde os Cloud Anchors hospedados atualmente estão mapeados. Quando se resolve o problema, uma nova âncora é adicionada à sessão e retornada.

- (void)resolveAnchorWithIdentifier:(NSString *)identifier {
  GARResolveCloudAnchorFuture *garFuture =
      [self.gSession resolveCloudAnchorWithIdentifier:identifier
                                    completionHandler:completion
                                                error:&error];
}

// Pass the ARFRame to the ARCore session every time there is a frame update.
// This returns a GARFrame that contains a list of updated anchors. If your
// anchor's pose or tracking state changed, your anchor will be in the list.
- (void)cloudAnchorManager:(CloudAnchorManager *)manager didUpdateFrame:(GARFrame *)garFrame {
  for (GARAnchor *garAnchor in garFrame.updatedAnchors) {
    if ([garAnchor isEqual:self.garAnchor] && self.resolvedAnchorNode) {
      self.resolvedAnchorNode.simdTransform = garAnchor.transform;
      self.resolvedAnchorNode.hidden = !garAnchor.hasValidTransform;
    }
  }
}

Padrão de pesquisa GARSession opcional

Se você estiver usando o Metal ou precisar de uma opção de pesquisa e seu app for executado em um mínimo de 30 QPS, use o seguinte padrão para transmitir ARFrames ao GARSession:

-(void)myOwnPersonalUpdateMethod {
  ARFrame *arFrame = arSession.currentFrame;
  NSError *error = nil;
  GARFrame *garFrame = [garSession update:arFrame error:&error];
  // your update code here
}

Cotas da API

A API ARCore tem as seguintes cotas para largura de banda de solicitação:

Tipo da cota Máximo Duração Aplicável a
Número de âncoras Ilimitado N/A Projeto
Solicitações de host de âncora 30 minuto Endereço IP e projeto
Ancorar solicitações resolve 300 minuto Endereço IP e projeto

Problemas conhecidos e soluções alternativas

Existem alguns problemas conhecidos ao trabalhar com o SDK do ARCore para iOS.

As configurações padrão do esquema causam falhas intermitentes no app

As configurações do esquema de captura de frame de GPU e de validação da API Metal são ativadas por padrão, o que às vezes pode causar falhas no app no SDK.

Como diagnosticar uma falha de app

Sempre que você suspeitar que ocorreu uma falha, verifique seu stack trace. Se houver MTLDebugComputeCommandEncoder no stack trace, é provável que isso com as configurações de esquema padrão.

Alternativa

  1. Acesse Product > Scheme > Edit Scheme….

  2. Abra a guia Run.

  3. Clique em Options para conferir as configurações atuais.

  4. Verifique se GPU Frame Capture e Metal API Validation estão desativados.

  5. Compile e execute o app.

Acesse o CHANGELOG do Cocoapods para ver outros problemas conhecidos.

Limitações

O SDK do ARCore para iOS não oferece suporte à chamada de método setWorldOrigin(relativeTransform:) do ARKit.

Considerações sobre desempenho

O uso de memória aumenta quando você ativa a API ARCore. O uso da bateria do dispositivo vai aumentar devido ao uso maior da rede e da CPU.

Próximas etapas