VLSDK (v1.6.5)

1. VLSDK란?

ARC eye VL SDK는 ARC eye Visual Localization (VL) API를 이용하여 공간 상에서 모바일 기기의 위치를 측정하여 모바일 기기의 위치를 추정하는 Unity 패키지입니다. 이를 통해 공간 정보를 활용하는 AR 앱을 쉽게 구현할 수 있습니다.

2. 설치 방법

VL SDK 설치

지원 환경

  • Unity 2022.3 이상
  • Editor
    • macOS (Apple Silicon)
    • Windows (64bit)
  • Device
    • iOS (12.0 이상 ARKit 지원 기기)
    • Android (API 24 이상 ARCore 지원 기기)

VLSDK 패키지 설치

  1. Unity 상단 메뉴의 Assets > Import Packages > Custom Package… 를 클릭한 후 vl-sdk-unity-1.6.5.unitypackage를 찾아 프로젝트에 추가합니다.

    • 이 과정을 통해 다음 패키지들이 자동으로 설치됩니다.
        com.unity.modules.xr@1.0.0
  com.unity.xr.arcore@5.1.5
  com.unity.xr.arfoundation@5.1.5
  com.unity.xr.arkit@5.1.5
  com.unity.xr.management@4.4.0
  com.unity.nuget.newtonsoft-json@3.2.1
    • 설치가 완료되면 다음 define symbols들이 자동으로 설정됩니다.
        VLSDK_ARFOUNDATION
  VLSDK_NEWTONSOFT_JSON

  2. Unity 상단 메뉴의 GameObject > ARC-eye > VL > Create VLSDKManager 를 클릭하여 VLSDKManager를 Scene에 추가합니다.

  3. (Optional) GameObject > ARC-eye > Dataset > Create ARDatasetManager를 클릭하여 ARDatasetManager를 Scene에 추가합니다.

AR 기능을 위한 프로젝트 설정

  1. Edit > Project Settings > XR Plug-in Management에서 다음 사항들을 설정합니다.
    • Android settings > Plug-in Provider에서 ARCore 체크
    • iOS settings > Plug-in Provider에서 ARKit 체크
  2. (Android) Edit > Project Settings > Player > Android Settings > Other Settings에서 다음 사항들을 수정합니다.
    • Rendering > Graphics APIs에서 OpenGLES3만 활성화
    • Identification > Minimum API Level을 API Level 24 이상으로 설정
    • Configuration > Scripting Backend를 IL2CPP로 설정
    • Configuration > Target Architectures 중 ARM64만 체크

VL SDK 설정 파일 생성

VL SDK를 사용하기 위해서는 VL 데이터 변환이 완료 된 배포 완료 상태의 VL API가 필요합니다. 배포 완료 상태의 VL API를 확보 했다면 이를 VLSDK에서 사용할 수 있도록 VLSDK Settings 파일을 생성하는 과정이 필요합니다. Project 탭에서 Assets > VLSDK > VLSDK Settings.asset을 클릭하여 설정 페이지에 진입합니다.

다음은 VLSDK Settings.asset 파일을 클릭 했을 때 Inspector 창에서 보이는 모습입니다.

E18489E185B3E1848FE185B3E18485E185B5E186ABE18489E185A3E186BA_2023-02-24_E1848BE185A9E1848CE185A5E186AB_10 34 39

각 항목들에 대한 설명은 다음과 같습니다.

URL List

VL 요청을 보낼 주소들의 리스트를 입력하는 영역입니다. VLSDK는 하나의 어플리케이션에서 여러개의 VL API를 사용할 수 있도록 구현되어 있습니다. VL 요청을 보낼 주소는 ARC eye 콘솔 페이지의 ARC eye > API > API 연동 키 확인에서 확인할 수 있습니다. 해당 페이지에서 InvokeURL과 Secret Key를 가져온 뒤 VLSDK Settings의 URL List 항목에 입력합니다.

URL List의 각 항목들에 대한 세부 설명은 다음과 같습니다.

항목 설명
Location VL API가 동작하는 지역의 이름입니다. GPS Guide를 사용하는 경우 이 값을 이용하여 어떤 Invoke URL을 사용할지 선택합니다. GPS Guide를 사용하지 않는 경우에는 이 값이 사용되지 않습니다.
Invoke Url ARC eye API 연동 키 확인의 Invoke URL 값입니다.
Secret Key ARC eye API 연동 키 확인의 Secret Key 값입니다.
Is Inactivated 해당 URL을 사용하지 않을 경우 체크합니다.
  • URL Lists가 사용되는 방법
    • VLSDK가 시작되면 처음에는 URL List의 모든 주소들에 대해 VL 요청을 보냅니다.
    • 현재 위치를 성공적으로 추정 할 때 까지 각 URL 요소들을 순회하며 한 번씩 요청을 보냅니다.
    • VL 성공 응답을 받은 이후에는 성공 응답을 받았던 URL만 사용해서 요청을 보내게 됩니다.

GPS Guide

GPS Guide는 스마트폰 기기의 GPS 값을 이용해 지리적으로 의미 있는 VL API들을 선택하는 기능입니다. 사용자의 위치에 따라 특정한 VL API를 사용하고 싶은 경우 이 기능을 사용합니다. GPS Guide가 활성화 되지 않으면 URL Lists에 추가된 모든 VL API를 순회하며 VL 요청을 보냅니다.

GPS Guide를 사용하기 위해서는 VL 요청 지역이 설정된 geojson 형식의 문자열이 필요합니다. VL SDK에서는 RFC 7964 명세의 GeoJeon 포맷을 사용합니다. VL SDK는 GeoJson을 생성하는 기능을 제공하지 않기 때문에 https://geojson.io/ 과 같은 외부의 툴을 사용해 GeoJson을 생성해야 합니다.

VL SDK에서 사용할 수 있는 GeoJson을 생성하기 위해서는 location이라는 이름의 properties를 생성해야 합니다. 이 location 필드에 들어가는 값은 앞서 URL List를 설정할 때 사용했던 Location과 동일해야 합니다.

아래의 그림을 보시면 GeoJson 형태에 location 속성이 추가된 것을 보실 수 있습니다. VLSDK는 GeoJson에 입력된 location과 location 필드의 값이 일치하는 URL List의 요소를 찾아 VL 요청을 보내게 됩니다.

E18489E185B3E1848FE185B3E18485E185B5E186ABE18489E185A3E186BA_2023-02-24_E1848BE185A9E1848CE185A5E186AB_10 32 46

GeoJson의 생성이 완료되면 GPS Guide의 체크박스를 눌러 활성화를 한 뒤 Location Geo Json 필드에 앞서 생성한 GeoJson 값을 복사합니다.

테스트용 GPS 사용

실제 기기에서는 GPS 값을 이용하여 GPS Guide의 동작 여부를 테스트 할 수 있지만 Editor 모드에서는 별도의 GPS 값이 없기 때문에 테스트용 GPS 데이터를 통해 GPS Guide의 동작 여부를 확인할 수 있습니다. 테스트용 GPS 데이터는 다음 두 가지 방법을 통해 사용할 수 있습니다.

  1. GeoCoordProvider

    E18489E185B3E1848FE185B3E18485E185B5E186ABE18489E185A3E186BA_2023-02-24_E1848BE185A9E1848CE185A5E186AB_10 38 54

    GeoCoordProvider는 임의의 고정된 GPS값을 VLSDK에 할당하는 컴포넌트입니다. Hierarchy에서 VLSDKManager를 선택하면 GeoCoordProvider에 GPS 값을 할당할 수 있습니다. Play mode에 진입하면 할당한 GPS 값을 기준으로 VLSDK가 동작하게 됩니다. Use Fake GPS Coord On Device를 활성화 하면 실제 기기에서도 해당 GPS 값을 이용해서 동작을 하게 됩니다.

  1. AR Dataset

    AR Dataset Recorder를 이용하면 기기의 동작 환경을 기록한 뒤 재현할 수 있습니다. 이 경우 별도의 설정이 필요하지 않습니다. AR Dataset과 관련된 자세한 사항은 아래에서 다루도록 하겠습니다.

VL Interval Initial

위치가 인식이 되지 않았을 때 VL 요청을 보내는 주기입니다. 단위는 밀리세컨트(ms) 입니다. 기본값은 500ms 입니다.

VL Interval Passed

위치 인식이 되어 VL Pass 상태가 되었을 때 VL 요청을 보내는 주기입니다. 단위는 밀리세컨트(ms) 입니다. 기본값은 1000ms 입니다.

VL Quality

VL Quality 값의 설정을 통해 수신한 VL 위치값의 정확도에 따른 VL Pass 처리 여부를 조절할 수 있습니다. LOW, MEDIUM, HIGH 세 단계로 조절할 수 있으며 LOW 값에 가까울수록 정확도가 낮지만 성공 횟수가 많아지게 되고 HIGH 값에 가까울수록 정확도가 높지만 성공 횟수는 적게 설정 됩니다.

Show VL Pose

VL 응답 결과를 시각화 하는 기능입니다. VL 인식 정확도에 따라 정확도가 높은 순서로 초록색, 파란색, 빨간색으로 인식된 위치를 Scene에 표시합니다. 실제 기기 화면에는 렌더링 되지 않습니다.

Log Level

VLSDK의 내부 동작 간 출력되는 로그의 레벨을 설정합니다. 기본값은 WARNING입니다.

설정 파일 적용

설정이 완료된 VLSetting.assets 파일을 VLSDKManager의 Settings 필드에 할당합니다. 이제 Play 모드로 진입하면 VLSDKManager는 할당한 설정 파일의 정보를 이용하여 VL 요청을 진행합니다.

Play On Awake

Play mode에 진입 했을 때 VLSDKManager의 세션이 자동으로 실행될지 여부를 설정하는 기능입니다. 기본값은 true입니다. 만일 특정 순간부터 VL 요청을 보내길 원한다면 PlayOnAwake를 false로 설정한뒤 아래와 같이 직접 세션을 시작해야 합니다.

public class GameManager : MonoBehaviour
{
    public ARCeye.VLSDKManager m_VLSDKManager;

    void Start() 
    {
        m_VLSDKManager.StartSession();
    }
}

3. 사용 방법

VLSDKManager가 정상적으로 추가 되고 VL API까지 정상적으로 연동했다면 앱 빌드 시 VL 측위 기반 AR 기능을 사용할 수 있습니다. 앱 실행과 동시에 VL 요청이 시작 되고, VL 요청을 통해 받은 응답은 VL 내부에서 처리하여 AR Session Origin의 위치가 자동으로 갱신 됩니다.

3.1 Editor 상에서의 VL 요청

VL SDK는 Editor와 실제 디바이스에서 모두 측위 테스트를 할 수 있습니다. 실제 디바이스는 ARFoundation을 통해 획득한 카메라 프레임의 Texture를 이용하여 VL 요청을 보냅니다. Editor에서는 AR Dataset을 사용하는 방법과 TextureProvider를 사용하는 방법이 있습니다.

AR Dataset (권장)

AR Dataset은 기기의 화면과 움직임 등을 기록한 AR 전용 데이터셋 다루는 패키지입니다. VLSDK는 실제 기기의 움직임을 기반으로 위치 추정의 정확도를 향상 시키는 로직이 포함되어 있기 때문에 AR Dataset을 이용해서 개발을 진행하면 실제 기기를 사용 했을 때와 유사한 환경에서 개발을 진행할 수 있습니다.

AR Dataset은 Recoder와 Player로 구성되어 있습니다. Recorder는 VLSDK 패키지 내의 VLSDK > ARDataset > ar-dataset-recorder-0.9.3.unitypackage로 제공 되고 있습니다. Player는 VLSDK에 추가가 된 상태이며 VLSDK > Player 경로에서 확인할 수 있습니다.

Recorder

Recorder를 사용하기 위해서는 VLSDK에 추가된 ar-dataset-recorder-0.9.3.unitypackage를 사용해야 합니다. 패키지를 열면 Recorder 관련 파일들이 추가되는 것을 볼 수 있습니다. Recorder > Scenes > Recorder.unity scene을 열면 다음과 같이 카메라 앱과 같은 화면이 구현된 것을 볼 수 있습니다.

해당 scene을 iOS나 Android로 빌드해서 실행하면 데이터셋을 생성할 수 있습니다. 레코딩 버튼을 눌러 녹화를 시작한 뒤 레코딩을 종료하면 기기에 녹화된 결과를 저장하게 됩니다. 녹화면 결과는 다음과 같은 방법으로 PC에 옮길 수 있습니다.

  • iOS 환경
    • iOS의 기본 파일 앱을 실행한 뒤 레코딩 앱 이름 폴더를 PC로 공유
  • Android 환경
    • 파일 브러우저 앱을 실행한 뒤 Android -> media -> '앱 번들 이름' 경로에서 파일에 접근한 후 PC로 공유

Player

Player를 사용하기 위해서는 Scene에 ARDatasetManager가 추가 되어 있어야 합니다. GameObject > ARC-eye > Dataset > Create ARDatasetManager를 클릭하여 ARDatasetManager를 Scene에 추가합니다.

ARDatasetManager를 선택하면 Inspector에서 다음과 같은 화면을 확인할 수 있습니다. Select Dataset Directory 버튼을 누른 뒤, 압축을 해제한 데이터셋의 디렉토리를 선택합니다.

데이터를 선택한 뒤 Play mode로 진입하면 데이터셋을 촬영 했던 순간의 영상과 움직임이 출력되는 것을 볼 수 있습니다.

TextureProvider

TextureProvider는 VL 요청을 보낼 Texture를 NetworkController에 전달하는 기능을 수행합니다. TextureProvider의 Texture To Send 필드에 요청을 보내고자 하는 Texture를 할당하면 해당 Texture를 이용해 VL 요청을 보내게 됩니다. 여기에는 Texture Type이 Sprite (2D and UI)인 이미지 파일이나 비디오의 Render Texture를 할당할 수 있습니다.

E18489E185B3E1848FE185B3E18485E185B5E186ABE18489E185A3E186BA_2023-02-24_E1848BE185A9E1848CE185A5E186AB_10 52 42

이미지 파일을 사용할 경우 파일을 클릭하여 Import Settings에 진입한 뒤 아래와 같은 설정을 합니다.

Untitled

비디오 플레이어를 사용하는 경우 Render Mode를 Render Texture로 설정한 뒤 Target Texture에 VL SDK에 첨부된 VideoTexture를 할당합니다.

E18489E185B3E1848FE185B3E18485E185B5E186ABE18489E185A3E186BA_2023-02-24_E1848BE185A9E1848CE185A5E186AB_10 57 15

3.2 VLSDKManager 이벤트

VLSDKManager는 VL 인식과 관련된 각종 정보를 전달하는 이벤트를 제공하고 있습니다.

각 이벤트에 대한 세부 설명은 다음과 같습니다.

OnStateChanged

VL 인식 상태가 변경될 경우 호출되는 이벤트입니다. 세부 상태에 대한 정보는 아래의 ‘상태’ 항목을 참고해주세요

OnLayerInfoChanged(string layerInfo)

VL이 인식되는 계층이 변경 되었을 경우 호출되는 이벤트입니다. 전달 되는 매개변수는 {계층1}{계층2}{계층3}…의 형태를 가지고 있습니다.

ex. AMCOHERITZ_GND_065

OnPoseUpdated(Matrix4x4 viewMatrix, Matrix4x4 projMatrix)

매 프레임마다 호출되는 이벤트입니다. 카메라의 전역 위치와 투영 행렬을 4x4의 행렬 형태로 전달합니다.

viewMatrix - 전역 위치를 나타내는 4x4 행렬

projMatrix - 카메라의 투영행렬을 나타내는 4x4 행렬

OnGeoCoordUpdated(Double latitude, Double longitude)

GPS 위치 인식이 수행 될때마다 호출되는 이벤트입니다.

latitude - 위도

longitude - 경도

OnObjectDetected(DetectedObject info)

VOT 인식 결과를 전달하는 이벤트입니다. 현재는 사용할 수 없습니다.

3.3 상태

VL는 내부적으로 세 가지 상태를 가집니다. 최초에는 Initial 상태이며 이후 VL의 동작에 따라 상태가 변경 됩니다. 상태가 변경이 되면 VLSDKManager의 OnStateChanged(TrackerState) 이벤트가 호출됩니다.

상태 설명
Initial VL 초기화가 안 된 상태. 앱 최초 실행 시, 혹은 VL 요청이 일정 수 이상 실패 시 INITIAL 상태가 됩니다. VL Settings의 Request Interval Before Localization에 설정된 주기에 맞춰 VL 요청을 보냅니다. 이 상태가 되면 AR Session Origin은 원점으로 이동하고 VL의 내부 세선은 모두 초기화 됩니다.
VL_RECEIVED VL 응답을 성공적으로 수신한 상태. VL_PASS 상태가 되지 직전의 상태입니다.
VL_PASS VL 응답을 성공적으로 수신한 상태. Request Interval After Localization에서 설정한 주기에 맞게 VL 요청을 보냅니다.
VL_FAIL VL 응답이 일시적으로 실패 중인 상태. Request Interval Before Localization에서 설정한 주기에 맞게 VL 요청을 보냅니다. VL 요청을 통해 갱신된 AR Session Origin은 유지 됩니다. 이 상태가 지속되면 INITIAL 상태로 변환.
VL_OUT_OF_SERVICE GPS Guide 사용 결과 유효한 VL API를 찾을 수 없는 상태. 지속적으로 GPS 값을 이용해 사용 가능한 VL API를 탐색합니다.

3.4 제어 메서드

VL의 제어는 VLSDKManager를 통해서 할 수 있습니다. VLSDKManager는 기기 별로 카메라 이미지와 위치를 전달받아 VL 요청을 보내고 그 결과를 Scene에 적용하는 역할을 수행합니다. VLSDKManager에서 사용할 수 있는 메서드는 다음과 같습니다.

메서드 이름 설명
StartSession() PoseTracker 세션을 시작합니다. 세션이 시작되면 매 프레임마다 카메라의 위치를 갱신하고 필요한 순간에 VL 요청을 보냅니다. 기본적으로 VLSDKManager의 Start 이벤트에서 실행합니다.
StopSession() PoseTracker 세션을 중단합니다. 카메라 위치 갱신이 중단되고 VL 요청을 보내지 않습니다.
ResetSession() PoseTracker 세션을 초기화합니다. State가 INITIAL이 되고 AR Session Origin이 원점으로 이동됩니다.

4. 문의 사항

VLSDK 사용 시 버그를 발견하거나 사용 방법에 대한 문의가 있을 경우 dl_ar@naverlabs.com으로 연락 바랍니다.

버그 리포팅 시 VLSDK Settings의 Log Level을 Verbose로 설정하여 로그를 출력한 뒤 Unity Console에서 Stack Tracing Logging의 설정을 모두 Full로 선택한 상태에서 전체 로그를 함께 첨부해주시면 문제 상황을 더욱 빠르게 확인할 수 있습니다.