Mega 추적 과정 제어

이 문서는 다양한 애플리케이션 시나리오의 요구를 충족하기 위해 Mega 추적 과정의 각 기능과 파라미터를 제어하는 방법을 설명합니다.

시작하기 전에

내 위치 기능을 사용할 수 있나요?를 확인해 위치 라이브러리가 올바르게 생성되고 지도가 추가되었는지 확인합니다.

tracker의 동작 흐름

버전 >= 4003
버전 4.7 - 4002

tracker의 동작 흐름은 다음과 같습니다.

flowchart LR
  subgraph startup_graph[시작]
    direction TB
    sstart((session 시작))
    create[네이티브 생성]
    load(target 로드)
    init_g[[초기화]]
  end
  
  subgraph init_graph[초기화]
    direction TB
    init_{6DoF 초기화 성공<br>또는 non-6DoF}
    init[[로컬 추적 초기화 과정]]
    localization_g[[초기 위치 지정]]
  end

  subgraph localization_graph[초기 위치 지정]
    direction TB
    localize__{위치 지정이 켜져 있고<br>요청 간격을 초과함}
    localize[클라우드 위치 지정]
    localize_{block에 위치됨 그리고<br>block이 로드됨}
    tracking_g[[추적]]
  end
  
  subgraph tracking_graph[추적]
    direction TB
    tracking[[지속 추적]]
  
    localizet_{위치 지정이 켜져 있고<br>요청 간격을 초과함}
    localize2[클라우드 위치 지정]
    localize2_{block에 위치됨 그리고<br>block이 로드됨}
    localization_g2[[초기 위치 지정]]
  end

  subgraph stopping_graph[중지]
    direction TB
    unload(target 해제)
    dispose[네이티브 소멸]
    sstop([session 중지])
  end

  sstart --> create --> load --> init_g
  init --> init_ --> |Yes| localization_g
  localize --> localize_ --> |Yes| tracking_g
  localize_ --> |No| localize__ --> |Yes| localize
  unload --> dispose --> sstop
  init_ --> |No| init

  tracking --> localizet_ --> |Yes| localize2 --> localize2_ --> |Yes| tracking
  localizet_ --> |No| tracking
  localize2_ --> |No| localization_g2

  startup_graph --> init_graph
  init_graph --> localization_graph
  localization_graph --> tracking_graph
  tracking_graph --> localization_graph
  tracking_graph --> stopping_graph

흐름은 대략 다음 단계로 나눌 수 있습니다.

시작:
- session이 시작되면 네이티브 계층의 tracker가 생성됩니다.
- target의 Start() 이후 해당 tracker에 로드됩니다.
초기화:
- 6DoF frame source를 사용할 때는 로컬 추적 초기화 과정으로 들어갑니다.
- non-6DoF frame source를 사용할 때는 초기화 단계를 건너뛰고 바로 초기 위치 지정 단계로 들어갑니다.
- 이 과정은 장면 복잡도와 기기 성능에 따라 시간이 걸릴 수 있으며, 보통 frame source 하위에서 사용하는 알고리즘과도 관련이 있습니다.
- 기본 설정에서는 이 단계의 내용이 표시되지 않으며, ActiveController 컴포넌트 옵션으로 이 동작을 제어할 수 있습니다.
초기 위치 지정:
- 위치 지정이 켜져 있고 요청 간격을 초과하면 tracker가 클라우드에 위치 지정 요청을 보냅니다.
  - 위치 지정에 성공하고, 위치 서비스가 반환한 id에 해당하는 block이 이미 로드되어 있으면 추적 단계로 들어갑니다. block이 아직 로드되지 않았다면 block 로드가 끝날 때까지 기다리고 다음 위치 지정 요청을 기다립니다.
  - 위치 지정에 실패하면 tracker는 다음 위치 지정 요청을 기다립니다.
- 이 과정은 장면의 위치 지정 용이성, 데이터 수집 및 매핑 품질, 네트워크 상태에 따라 시간이 걸릴 수 있습니다.
- 기본 설정에서는 이 단계의 내용이 표시되지 않으며, ActiveController 컴포넌트 옵션으로 이 동작을 제어할 수 있습니다.
추적:
- tracker는 현재 block을 계속 추적합니다.
- 위치 지정이 켜져 있고 요청 간격을 초과하면 tracker가 클라우드에 위치 지정 요청을 보냅니다.
  - 위치 지정에 성공하고, 위치 서비스가 반환한 id가 바뀌지 않았다면 계속 추적합니다. id가 바뀌었고 block이 이미 로드되어 있으면 새 block으로 전환해 계속 추적합니다. id가 바뀌었고 block이 아직 로드되지 않았다면 block 로드가 끝날 때까지 기다리고 다음 위치 지정 요청을 기다립니다.
  - 위치 지정에 실패하면 tracker는 현재 block을 계속 추적하고 다음 위치 지정 요청을 기다립니다.
- 기본 설정에서는 추적 상태(TargetController.IsTracked == true)인 target 노드 아래의 콘텐츠만 표시되며, ActiveController 컴포넌트 옵션으로 이 동작을 제어할 수 있습니다.
중지:
- session이 중지되면 target이 해제되고 네이티브 계층의 tracker가 소멸합니다.

기기 지원 수준 조정

MegaTrackerFrameFilter의 MegaTrackerFrameFilter.MinInputFrameLevel 속성은 Mega가 지원하는 최소 기기 수준을 지정하는 데 사용됩니다.

Mega는 거의 모든 유형의 frame data source에서 실행될 수 있지만, frame data source마다 추적 효과에 미치는 영향은 다릅니다.

기본적으로 Mega는 기기가 지원하는 가장 높은 수준의 frame data source를 추적에 사용합니다. 기본 설정에서 Mega를 지원하는 session에는 이미 6DoF와 5DoF를 지원하는 frame data source가 구성되어 있습니다.

Mega 실행 중 특정 수준의 frame data source를 지원하려면 두 조건을 만족해야 합니다.

필요한 frame data source가 session의 선택 가능한 frame data source 그룹에 있어야 합니다.
MegaTrackerFrameFilter.MinInputFrameLevel가 필요한 frame data source의 CameraTransformType 수준보다 크거나 같아야 합니다.

예를 들어 기본 session에서 3DoF 추적을 지원하려면 다음이 필요합니다.

session의 frame data source 그룹에 ThreeDofCameraDeviceFrameSource를 추가합니다.
MegaTrackerFrameFilter.MinInputFrameLevel를 ThreeDof로 수정합니다.

또 다른 예로 기본 session에서 5DoF 추적 지원을 제거하려면 다음이 필요합니다.

session의 frame data source 그룹에서 InertialCameraDeviceFrameSource를 삭제합니다.
MegaTrackerFrameFilter.MinInputFrameLevel를 SixDof로 수정합니다(수정하지 않아도 5DoF frame data source가 없으므로 5DoF는 사용되지 않습니다).

조건을 만족하는 frame data source가 없으면 session 구성에 실패합니다.

현재 시스템 상태 이해

기본 session 설정에서는 UI 메시지가 화면에 표시되며, 여기에 Mega 추적 상태 정보가 포함됩니다.

버전 >= 4003
버전 4.7 - 4002

위치 지정에 성공하면 Mega 서비스 정보 아래에 Found 상태 텍스트가 표시되고, 위치 지정에 실패하면 NotFound 상태 텍스트가 표시됩니다.

이미 로드된 block은 Block [scnObj=<objName>] (<trackingStatus>): <name> (<id>) 형식으로 표시됩니다. 여기서 <objName>은 block에 해당하는 씬 오브젝트 이름이고, <name>은 block 이름, <id>는 block ID입니다. trackingStatus는 Tracking 또는 NotTracking일 수 있으며, 각각 현재 block이 추적 중인지 여부를 나타냅니다.

위치 지정에 성공했지만 아직 로드되지 않은 block 정보는 Block [scnObj=?]: <name> (<id>)로 표시됩니다.

팁

NotFound는 정상 상태이며, Mega가 동작하는 전체 과정에서 자주 나타납니다. 이 상태가 나타나도 추적은 계속됩니다. 일반적으로 애플리케이션 개발에서 NotFound에 대해 특별한 처리를 할 필요는 없습니다.

MegaTrackerFrameFilter.LocalizationRespond 이벤트를 사용하면 현재 위치 지정 상태를 얻어 시스템이 현재 추적 대상을 찾았는지 알 수 있습니다.

아래 코드는 이 이벤트를 사용하는 방법과, 애플리케이션이 주의해야 할 일반적인 예외 상태를 처리하는 방법을 보여 줍니다.

private void Awake()
{
    megaTracker.LocalizationRespond += HandleLocalizationStatusChange;
}
        
private void HandleLocalizationStatusChange(MegaLocalizationResponse response)
{
    var status = response.Status;
    wakingUpCount = status == MegaTrackerLocalizationStatus.WakingUp ? wakingUpCount + 1 : 0;
    if (wakingUpCount >= 5)
    {
        // 서비스가 깨어나는 중이므로 최종 사용자가 기다려야 합니다
    }

    if (status == MegaTrackerLocalizationStatus.QpsLimitExceeded)
    {
        // QPS 초과, 일부 최종 사용자는 위치 지정에 실패할 수 있습니다(전체 추적 품질 저하)
        // 이때는 보통 현재 사용자 수에서 추적 품질을 보장하도록 QPS 상한을 올리는 유료 업그레이드가 필요합니다
    }

    if (status == MegaTrackerLocalizationStatus.ApiTokenExpired)
    {
        // Token 만료, Token 인터페이스로 서비스에 접근할 때만 나타납니다
        // 이 문제를 해결하려면 애플리케이션이 자체 백엔드에 Token을 요청하고, MegaTrackerFrameFilter.UpdateToken으로 갱신해야 합니다
    }
}

애플리케이션이 MegaTrackerLocalizationStatus.RequestTimeout 상태를 자주 만나면, 보통 기기와 서비스 사이의 네트워크 상태가 좋지 않다는 뜻입니다. 추적 품질을 높이려면 네트워크 환경을 개선하는 것이 좋습니다. 네트워크 상태를 개선할 수 없는 경우에는 요청 타임아웃 시간을 늘리는 방법을 고려할 수 있습니다.

참고

이 이벤트로는 위치 지정이 반환한 pose를 얻을 수 없습니다.

사실 위치 지정이 반환한 pose는 애플리케이션 개발에서 필요하지 않습니다. EasyAR는 위치 지정이 끝난 뒤 로컬 알고리즘으로 더 정확한 pose를 계산해 개발자에게 반환하며, 이 pose는 이미 block의 transform에 반영되어 있습니다. session의 실행 결과 가져오기를 참고하세요.

일시 중지와 계속

Mega의 추적과 위치 지정 기능은 각각 일시 중지하고 다시 시작할 수 있습니다.

추적 일시 중지

MegaTrackerFrameFilter.enabled를 false로 설정하면 추적을 일시 중지할 수 있습니다.

기본적으로 추적이 일시 중지되면 모든 block 노드 아래의 콘텐츠가 숨겨집니다.

MegaTrackerFrameFilter.EnableLocalization를 false로 설정하면 위치 지정을 일시 중지할 수 있습니다.

경고

위치 지정 일시 중지는 추적 효과에 영향을 주므로 일반적으로 수정하지 않는 것이 좋습니다. EasyAR 기술 지원의 안내에 따라 사용하세요.

애플리케이션 실행 중 위치 지정이 일시 중지된 적이 있다면, EasyAR에 문제를 제보할 때 반드시 그 사실을 알려야 합니다.

서비스와 요청 제어

MegaTrackerFrameFilter 컴포넌트의 파라미터를 수정해 서비스 요청 동작을 제어할 수 있습니다.

위치 라이브러리 선택

session 아래의 Mega Tracker 오브젝트를 선택하고, Service 아래의 옵션을 수정하면 연결할 위치 라이브러리를 바꿀 수 있습니다. 이 옵션은 session 시작 전에 설정해야 합니다.

기본 설정에서는 Access Source가 Global Config이며, 서비스 설정은 전역 구성을 사용합니다. 서비스 파라미터는 Project Settings의 EasyAR > Sense > Mega > Mega Block에서 수정할 수 있으며, 이 설정은 같은 전역 구성을 사용하는 모든 session에 영향을 줍니다.

팁

서비스 설정은 EasyAR 개발 센터에서 가져올 수 있습니다.
Mega Config Detail

다른 session마다 다른 위치 라이브러리를 사용하려면 Access Source를 API Key로 설정하고, 아래에서 서비스 파라미터를 수정할 수 있습니다.

스크립트에서는 MegaTrackerFrameFilter.ServiceAccessSource와 MegaTrackerFrameFilter.ServiceAccessData를 수정해 같은 효과를 얻을 수 있습니다.

예를 들어 아래 코드는 session 시작 전에 런타임 파라미터로 tracker가 서비스를 연결하도록 설정하는 방법을 보여 줍니다.

megaTracker.ServiceType = easyar.MegaApiType.Block;
megaTracker.ServiceAccessSource = easyar.MegaServiceAccessSourceType.APIKey;
megaTracker.ServiceAccessData = new easyar.APIKeyAccessData
{
    ServerAddress = serverAddress,
    APIKey = apiKey,
    APISecret = apiSecret,
    AppID = appID
};

요청 간격과 타임아웃

session 아래의 Mega Tracker 오브젝트를 선택하고, Request Time Parameters 아래의 옵션을 수정하면 서비스 요청 간격과 타임아웃 시간을 조정할 수 있습니다.

스크립트에서는 MegaTrackerFrameFilter.RequestTimeParameters를 수정해 같은 효과를 얻을 수 있습니다.

경고

요청 간격을 수정하면 추적 효과에 영향을 주므로 일반적으로 권장하지 않습니다. EasyAR 기술 지원의 안내에 따라 사용하세요.

애플리케이션 실행 중 요청 간격이 변경되었다면, EasyAR에 문제를 제보할 때 반드시 그 사실을 알려야 합니다.

위치 라이브러리 전환

MegaTrackerFrameFilter.SwitchEndPoint를 사용하면 런타임 중에 위치 라이브러리를 전환할 수 있습니다. 이 인터페이스를 사용할 때도 카메라 화면과 session은 중단되지 않습니다.

Table of Contents