Guia do desenvolvedor do Cloud Anchors para iOS

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

Aprenda a usar a API ARCore Cloud Anchor ou o serviço ARCore Cloud Anchor nos seus próprios apps.

Pré-requisitos

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

Se você nunca usou o Cloud Anchors:

Ativar o Cloud Anchors no seu app

Para usar a API Cloud Anchors, você precisa criar um GARSessionConfiguration e definir a propriedade cloudAnchorMode para ela, conforme descrito em Configurar uma sessão do ARCore no iOS. Use setConfiguration:error: (GARSession) para definir a configuração.

Você também precisa ativar a API ARCore para seu aplicativo.

Hospedar e resolver âncoras

É possível hospedar e resolver âncoras do Cloud com a API ARCore Cloud Anchor. A API inclui métodos de callback para operações concluídas, bem como 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 a posição de ARAnchor 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 um ARAnchor permite que dispositivos Android e iOS em um determinado espaço físico adicionem âncoras hospedadas anteriormente a novas cenas.

Uma solicitação de resolução envia ao servidor do Google um ID de âncora na nuvem com dados visuais do frame atual. O servidor vai tentar associar esses dados visuais às imagens de onde as âncoras do Cloud hospedadas atualmente estão mapeadas. Quando a resolução é bem-sucedida, 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 o app for executado a 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áxima Duração Válido para
Número de âncoras Ilimitado N/A Projeto
Solicitações de host âncora 30 minuto Endereço IP e projeto
Solicitações resolve de âncora 300 minuto Endereço IP e projeto

Problemas conhecidos e soluções alternativas

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

As configurações de esquema padrão causam falhas intermitentes no aplicativo

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

Diagnosticar uma falha no app

Sempre que você suspeitar que ocorreu uma falha, observe seu stack trace. Se MTLDebugComputeCommandEncoder aparecer no stack trace, provavelmente isso se deve às configurações de esquema padrão.

Alternativa

  1. Acesse Product > Scheme > Edit Scheme….

  2. Abra a guia Run.

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

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

  5. Compile e execute o app.

Consulte 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 performance

O uso da memória aumenta quando você ativa a API ARCore. É esperado que o uso da bateria do dispositivo aumente devido ao maior uso da rede e da CPU.

Próximas etapas