Skip to main content
Version: 1.12.1

VLSDKManager

VL API 요청 관리 및 실시간 위치 추정을 담당하는 핵심 컴포넌트입니다. VL 응답을 처리하여 전역 좌표계에서의 기기 위치를 계산합니다.

Properties​

PropertyTypeDescription
playOnAwakeboolVLSDKManager가 생성될 시 세션을 자동으로 시작할지 여부 (기본값: true)
settingsVLSDKSettingsVLSDKManager의 설정값
arCameraTransformAR 카메라의 Transform
originTransform카메라의 지역 좌표계를 공간 상의 전역 좌표계로 변환시키는 원점. XR Origin의 Transform
mainCameraCamera메인 카메라 (Camera.main)
poseTrackerPoseTracker내부 PoseTracker 인스턴스. 고급 사용자용
trackerStateTrackerStateVLSDKManager의 현재 상태
versionstringVLSDK 패키지 버전 (읽기 전용)

Methods​

Initialize​

void Initialize()

VLSDKManager 시스템 초기화. VLSDKManager를 런타임에 생성하는 경우가 아니라면 직접 호출하지 않는다. VLSDKManager를 런타임에 생성하여 VLSDKSettings를 직접 할당하는 경우 VLSDKSettings를 VLSDKManager에 할당한 뒤에 초기화 메서드를 호출해야 한다.

Example:

m_VLSDKManager.settings = m_NewLocationSettings;
m_VLSDKManager.Initialize();

StartSession​

void StartSession()

VLSDK 세션 시작. VL 요청을 보내기 시작한다. playOnAwake가 true인 경우에는 StartSession()을 호출하지 않아도 자동으로 세션이 시작된다.

Example:

m_VLSDKManager.StartSession();

StopSession​

void StopSession()

VLSDK 세션 정지. 현재 카메라의 위치와 인식 정보를 모두 유지한채로 VL 요청만 중단한다.

Example:

m_VLSDKManager.StopSession();

ResetSession​

void ResetSession()

VLSDK 세션 초기화. VLSDK의 모든 상태를 초기화한다. ResetSession()이 호출되면 OnStateChanged(TrackerState) 이벤트가 호출되며 TrackerState.INITIAL이 전달된다.

Example:

m_VLSDKManager.ResetSession();

EnableResetByDevicePose​

void EnableResetByDevicePose(bool active)

기기의 자세를 이용한 세션 초기화 기능을 활성화 여부를 설정합니다. VLSDK는 기본적으로 기기의 상단이 바닥을 향할 경우 전체 세션을 자동으로 초기화 합니다. 매개변수로 false를 전달하면 기기의 자세가 비정상적이어도 세션이 초기화 되지 않습니다.

Parameters:

NameTypeDescription
activebooltrue일 경우 자동 리셋 활성화, false일 경우 비활성화

Example:

EnableResetByDevicePose(false);   // 기기 자세가 비정상적이어도 자동 초기화를 하지 않음.
EnableResetByDevicePose(true);    // 기기 자세가 비정상적일 경우 자동 초기화.

ChangeState​

void ChangeState(TrackerState state)

VLSDK의 상태를 강제로 변경합니다. 일반적으로 사용되지 않으며, 테스트나 특수한 경우에만 사용합니다.

Parameters:

NameTypeDescription
stateTrackerState변경할 상태

Example:

m_VLSDKManager.ChangeState(TrackerState.INITIAL);

SetTrackerConfig​

void SetTrackerConfig(TrackerConfig config)

PoseTracker의 내부 설정을 변경합니다. 고급 사용자를 위한 메서드입니다.

Parameters:

NameTypeDescription
configTrackerConfig설정할 TrackerConfig 구조체

Example:

TrackerConfig config = m_VLSDKManager.GetTrackerConfig();
config.requestIntervalAfterLocalization = 2000; // 2초로 변경
m_VLSDKManager.SetTrackerConfig(config);

GetTrackerConfig​

TrackerConfig GetTrackerConfig()

현재 PoseTracker의 내부 설정을 가져옵니다.

Returns:

TypeDescription
TrackerConfig현재 Tracker 설정

Example:

TrackerConfig config = m_VLSDKManager.GetTrackerConfig();
Debug.Log($"Request interval: {config.requestIntervalAfterLocalization}ms");

FindLocation​

string FindLocation(double latitude, double longitude)

GPS 좌표를 기반으로 해당 위치에 해당하는 VL Location ID를 찾습니다. GPS Guide가 활성화되어 있어야 합니다.

Parameters:

NameTypeDescription
latitudedouble위도
longitudedouble경도

Returns:

TypeDescription
string해당 위치의 Location ID. 매칭되는 영역이 없으면 빈 문자열 반환

Example:

string locationId = m_VLSDKManager.FindLocation(37.5665, 126.9780);
if (!string.IsNullOrEmpty(locationId))
{
    Debug.Log($"Found location: {locationId}");
}

StartDetectingGPSLocation​

void StartDetectingGPSLocation()

GPS 기반 VL Location 감지를 시작합니다. GPS Guide가 활성화되어 있을 때 1초마다 GPS 위치를 확인합니다. 일반적으로 자동으로 호출되므로 직접 호출할 필요가 없습니다.

StopDetectingGPSLocation​

void StopDetectingGPSLocation()

GPS 기반 VL Location 감지를 중지합니다.

Events​

VLSDKManager는 VL 요청/응답, 상태 변경, 위치 업데이트 등 다양한 이벤트를 제공합니다. 각 이벤트는 Unity의 UnityEvent를 상속하므로 Inspector 또는 코드에서 리스너를 추가할 수 있습니다.

OnVLPoseRequested​

public VLRequestEvent OnVLPoseRequested

VL 요청을 보낼 때마다 호출되는 이벤트입니다.

Event Data:

TypeDescription
VLRequestEventData요청 URL, Secret Key, 요청 이미지 등

Example:

m_VLSDKManager.OnVLPoseRequested.AddListener((requestData) =>
{
    Debug.Log($"VL Request sent to: {requestData.Url}");
});

OnVLPoseResponded​

public VLRespondedEvent OnVLPoseResponded

VL 응답을 수신할 때마다 호출되는 이벤트입니다.

Event Data:

TypeDescription
VLResponseEventData응답 상태, VL 위치, 신뢰도 등

Example:

m_VLSDKManager.OnVLPoseResponded.AddListener((responseData) =>
{
    if (responseData.Status == ResponseStatus.Success)
    {
        Debug.Log($"VL Success! Confidence: {responseData.Confidence}");
    }
});

OnStateChanged​

public ChangedStateEvent OnStateChanged

VLSDK의 상태가 변경될 때마다 호출되는 이벤트입니다.

Event Data:

TypeDescription
TrackerStateINITIAL, NOT_RECOGNIZED, VL_PASS, VL_FAIL, VL_OUT_OF_SERVICE

Example:

m_VLSDKManager.OnStateChanged.AddListener((state) =>
{
    switch (state)
    {
        case TrackerState.VL_PASS:
            Debug.Log("VL localization successful!");
            break;
        case TrackerState.VL_FAIL:
            Debug.LogWarning("VL localization failed continuously");
            break;
    }
});

OnLayerInfoChanged​

public ChangedLayerInfoEvent OnLayerInfoChanged

인식된 공간의 계층 정보가 변경될 때 호출되는 이벤트입니다. VL 응답의 datasetInfo 필드의 값이 전달됩니다.

Event Data:

TypeDescription
stringLayer Info (예: "NAVER_GND_123")

Example:

m_VLSDKManager.OnLayerInfoChanged.AddListener((layerInfo) =>
{
    Debug.Log($"Layer changed to: {layerInfo}");
});

OnARFrameUpdated​

public UpdatedARFrameEvent OnARFrameUpdated

매 프레임마다 호출되는 이벤트입니다. 활성화된 AR 프레임워크의 프레임 원본 데이터가 전달됩니다.

Event Data:

TypeDescription
ARFrame카메라 텍스처, 위치, 회전, intrinsic 등

Example:

m_VLSDKManager.OnARFrameUpdated.AddListener((frame) =>
{
    Texture cameraTexture = frame.texture;
    Vector3 position = frame.localPosition;
});

OnPoseUpdated​

public UpdatedPoseEvent OnPoseUpdated

매 프레임마다 호출되는 이벤트입니다. 전역 좌표계로 업데이트 된 카메라의 위치 관련 행렬 정보를 전달합니다.

Event Data:

NameTypeDescription
viewMatrixMatrix4x4카메라의 뷰 행렬
projMatrixMatrix4x4카메라의 투영 행렬
texMatrixMatrix4x4카메라 프리뷰 렌더링 행렬
relativeAltitudedouble상대 고도 (m)

Example:

m_VLSDKManager.OnPoseUpdated.AddListener((viewMatrix, projMatrix, texMatrix, altitude) =>
{
    Debug.Log($"Relative altitude: {altitude}m");
});

OnGeoCoordUpdated​

public UpdatedGeoCoordEvent OnGeoCoordUpdated

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

Event Data:

NameTypeDescription
latitudedouble위도
longitudedouble경도

Example:

m_VLSDKManager.OnGeoCoordUpdated.AddListener((latitude, longitude) =>
{
    Debug.Log($"GPS: {latitude}, {longitude}");
});

OnRelativeAltitudeUpdated​

public UpdatedRelAltitudeEvent OnRelativeAltitudeUpdated

상대 고도가 업데이트될 때마다 호출되는 이벤트입니다.

Event Data:

NameTypeDescription
altitudedouble상대 고도 (m)

Example:

m_VLSDKManager.OnRelativeAltitudeUpdated.AddListener((altitude) =>
{
    Debug.Log($"Altitude: {altitude}m");
});

OnObjectDetected​

public DetectedObjectEvent OnObjectDetected

오브젝트 감지 시 호출되는 이벤트입니다.

Event Data:

TypeDescription
DetectedObject감지된 오브젝트 정보

Example:

m_VLSDKManager.OnObjectDetected.AddListener((detectedObject) =>
{
    Debug.Log($"Object detected: {detectedObject}");
});

사용 예시​

기본 사용​

Example
using UnityEngine;
using ARCeye;

public class VLSDKController : MonoBehaviour
{
    public VLSDKManager vlsdkManager;
    public VLSDKSettings vlsdkSettings;

    void Start()
    {
        // VLSDKSettings 할당 및 초기화
        vlsdkManager.settings = vlsdkSettings;
        vlsdkManager.Initialize();

        // 이벤트 리스너 등록
        vlsdkManager.OnStateChanged.AddListener(OnStateChanged);
        vlsdkManager.OnVLPoseResponded.AddListener(OnVLResponded);

        // 세션 시작 (playOnAwake가 false인 경우)
        vlsdkManager.StartSession();
    }

    void OnStateChanged(TrackerState state)
    {
        Debug.Log($"State changed to: {state}");
    }

    void OnVLResponded(VLResponseEventData data)
    {
        if (data.Status == ResponseStatus.Success)
        {
            Debug.Log($"VL Success! Position: {data.VLPosition}");
        }
    }
}

세션 제어​

Example
// 세션 일시 정지
public void PauseVL()
{
    vlsdkManager.StopSession();
}

// 세션 재개
public void ResumeVL()
{
    vlsdkManager.StartSession();
}

// 세션 리셋 (위치가 잘못 인식된 경우)
public void ResetVL()
{
    vlsdkManager.ResetSession();
}

GPS 기반 위치 확인​

Example
void CheckLocation()
{
    double latitude = 37.5665;
    double longitude = 126.9780;

    string locationId = vlsdkManager.FindLocation(latitude, longitude);

    if (!string.IsNullOrEmpty(locationId))
    {
        Debug.Log($"현재 위치는 {locationId} 영역입니다.");
    }
    else
    {
        Debug.Log("서비스 영역 밖입니다.");
    }
}

참고​