• Documentation
© 2019 Space4 Co., Ltd.
All Rights Reserved.






Quick Start




- 환경설정

o 인터넷 연결
o Unity 2018.3.x 이상 권장
o Android SDK 7.0 (API Level 24) 이상 권장
o iOS v10.x 이상 권장

- Space4 SDK 다운로드

o 링크주소 : Space4Kit(Android&iOS)_v1.0.unitypackage

- HelloSpace4 오픈

o 새로운 Unity 프로젝트를 생성하고 다운받은 Space4Kit SDK 패키지를 import 합니다.
o Space4Kit / Samples / HelloSpace4_(엔진명) / Scenes / HelloSpace4_(엔진명) 샘플을 오픈합니다.

- 빌드설정 ( Android Platform )

Player Settings / Android Platform 에서
o Other Settings / Multithreaded Rendering 체크옵션을 해제합니다.
o Other Settings / Target Architecture의 x86 체크옵션을 해제합니다.
o Other Settings / Write Permission을 External로 설정합니다.
o Other Settings / Minimum API Level을 24이상으로 설정합니다.

- 빌드설정 ( iOS Platform )

Player Settings / iOS Platform 에서
o Other Settings / Auto Graphics API 체크옵션을 해제합니다.
o Other Settings / Graphics APIs 를 Metal로 설정합니다.
o Other Settings / Camera Usage Description을 설정합니다.
o Other Settings / Target min iOS Version을 10.0으로 설정합니다.
o Other Settings / Architecture 를 ARM64로 설정합니다.

- 앱실행

o 빌드설정이 끝나면 바로 빌드를 진행하고 앱을 실행시킵니다.
o 공간인식, 마커인식, 얼굴인식, QR코드인식 샘플앱을 바로 확인하실 수 있습니다.







HelloSpace4 (공간인식) Tutorial

개발환경은 QuickStart에 있는 내용을 참고하시기 바랍니다.




1. Unity 새 프로젝트를 생성합니다.

2. Space4Kit유니티 패키지를 다운받고 생성한 프로젝트에 Import합니다.
메뉴바 -> Assets -> Import Package -> Space4 패키지 파일을 지정하여 패키지를 열고 모든 파일을 import 합니다.

3. 새로운 Scene을 생성합니다.
Assets / Scenes 에 HelloSpace4 이름으로 새 Scene을 추가합니다.

4. Space4 카메라 및 세션 설정을 진행합니다.
o 초기 Main Camera를 삭제하고 Space4Kit 패키지에서 제공하는 ARCamera를 배치합니다.
Space4Kit / Prefabs / ARCamera 를 새로 만든 HelloSpace4에 배치합니다.

o 오브젝트 ARSession을 생성합니다.
빈 오브젝트를 ARSession으로 생성하고 여기에 Space4Kit의 SARSession스크립트를 추가하고 Track Mode를 “World Recognition”으로 설정합니다.

o 공간인식 세션설정을 진행합니다.
세션설정은 SARSession스크립트의 바로 아래 위치한 “Open Space4 Engine configuration”버튼을 클릭하여 Space4Configuration으로 이동합니다.

Space4Kit 을 이용하기 위해서는 라이선스를 발급받아야 합니다.
발급받은 라이선스 키를 License Key입력박스에 넣어 줍니다.
라이선스 키를 발급받는 방법은 여기 에서 확인해 주십시오.

Start Automatically옵션을 설정해줍니다.
이 옵션은 Scene로드시 자동으로 엔진을 구동시키겠는지 혹은 수동으로 엔진을 구동시키겠는가를 결정하는 옵션입니다.

Tracking Mode를 설정해줍니다.
Tracking Mode에는 “Full”, “Limited”가 있습니다.
“Full”모드는 VIO방식으로 트래킹을 진행하며 “Limited”모드는 VO방식으로 트래킹을 진행합니다.

Plane Detection Mode를 설정해줍니다.
Plane Detection 모드에는 “Any”, “Horizontal”, “Vertical”, “Both” 이렇게 4가지 모드가 있습니다.

이상으로 Space4Kit이용을 위한 AR카메라, AR세션설정을 진행하였습니다.


5. 프레임 렌더러를 추가합니다. (옵션)
프레임에서 검출되는 특징점을 렌더링하기 위해서는 Space4Kit / Prefabs / FeatureParticleRenderer Prefab을 HelloSpace4에 추가합니다.


6. 평면검출 렌더러를 추가합니다. (옵션)
프레임에서 검출되는 평면정보를 렌더링하기 위해서 PlaneDetector를 생성하고 ARCamera에 자식으로 추가합니다. (PlaneDetector는 SDK 소스 참고)


7. Space4Kit 이용을 위한 새로운 스크립트를 추가합니다.
Hello이름의 오브젝트와 스크립트를 생성하고 Hello 오브젝트에 Hello 스크립트를 추가합니다.
스크립트에서 이용하게 될 AR세션과 평면에 배치되게 될 문자객체를 추가합니다.

8. AR세션을 생성하고 시작합니다.
o AR 세션관리를 위한 멤버변수 를 Hello 스크립트에 추가합니다.

copy
            

                public SARSession arSession;
            
        

위에서 추가한 ARSession 오브젝트를 arSession에 적용합니다.

9. 이미 존재하는 맵데이터를 불러들이려는 경우에는 Session 을 수동으로 시작해줍니다.
이미 Configuration에서 Start Automatically 옵션이 해제되어있는가를 확인해주세요.
o SDK 초기화

copy
            

                SARSDK.Initialize(Space4Kit.Space4Configuration.Instance.LicenseKey);
            
        

o 서버에 보관된 맵 리스트 얻기

copy
            

                SARSDK.SetDelegate(new SARSDKDelegate
                {
        	        OnListSavedMapsConsumer = this.OnListSavedMaps,
                    OnDeleteMapDelegate = this.OnDeleteMap
                });
            
        

SARSDK 클래스에 SARSDKDelegate 클래스를 이용하여 서버에서 보관된 맵리스트를 얻어온 결과를 delegate로 넘겨받습니다.

copy
            

                public void OnListSavedMaps(List infos)
                {
                    mapId = infos.mapId;
                }
            
        

Delegate 에서 SARWorldMap.Info 형 infos 에서 보관된 맵들의 map Id를 얻을수 있습니다.
o Map Id로부터 SARWorldMap 생성

copy
            

                SARWorldMap map = new SARWorldMap();

                // set delegate
                map.SetDelegate(new SARWorldMapDelegate
                 {
                            OnMapLoadedDelegate = this.OnMapLoaded,
                            OnMapSavedDelegate = this.OnMapSaved,
                            OnAnchorSavedDelegate = OnAnchorSaved,
                            OnAnchorLoadDelegate = OnAnchorLoaded
                });
            
        

SARWorldMap의 해당한 Delegate들을 등록해줍니다.

copy
            

                map.load(mapId);
            
        

o 로드된 맵데이터로부터 세션 시작
서버로부터 맵을 다운받으면 위에서 등록한 OnMapLoaded delegate가 호출됩니다.

copy
            

                public void OnMapLoaded(SARWorldMap.Info mapInfo)
                {
	                arSession.Initialize();
                    arSession.SetInitialWorldMap(map);
                    arSession.StartSession();
                }
            
        

o Start Automatically 가 해제된 상태에서 이미 보관된 맵 데이터를 사용함이 없이 세션을 시작하려면 다음의 두 함수를 호출합니다.

copy
            

                arSession.Initialize();
                arSession.StartSession();
            
        

10. 구동중인 AR세션의 결과를 확인합니다.
스크립트의 Update나 OnGUI 함수를 이용하여 AR세션의 결과를 실시간으로 확인해봅니다.
예로 Space4Kit / Scripts / Internal / PlaneDetector 스크립트에는 프레임에서 검출된 평면정보를 실시간으로 획득하여 필요한 처리를 진행합니다.

copy
            

                var status = arSession.getCurrentStatus();
                var frame = arSession.getCurrentFrame();
                if (status != SARSessionStatus.TRACKING)
                {
                    Debug.Log("Ignore this planepose, Not tracking");
                    continue;
                }
                
                Matrix4x4 poseMatrix = 
                MatrixUtils.GetUnityPoseMatrix(frame.planePose);
                if (poseMatrix == Matrix4x4.identity)
                {
                    Debug.Log("Ignore this planepose, identity matrix");
                    continue;
                }
                // …………………………..	
            
        

(공간인식 세션에서 프레임 처리결과 평면의 위치정보를 얻습니다.)
AR세션에서 처리중의 현재의 결과정보를 얻기 위해서 arSession의 getCurrentStatus()와 getCurrentFrame() 함수를 이용하며 이 함수들은 각각 세션의 현재 상태와 세션에서 처리된 프레임 결과를 리턴합니다.

11. 검출된 평면의 위치에 문자오브젝트를 배치합니다.
위 예제 소스에서와 같이 화면의 중심점에 대한 평면정보를 얻고 필요한 위치에 문자 오브젝트를 생성하도록 합니다.

copy
            

                // ………. 
                var planePose = frame.planePose;
                Matrix4x4 poseMatrix = MatrixUtils.GetUnityPoseMatrix(planePose);
                if (poseMatrix == Matrix4x4.identity || frame.planeType != 1)
                {
                    Debug.Log("Ignore this planepose, invalid matrix");
                    return;
                }
                // create new GameObject
                GameObject newObj = Instantiate(textObj);
                newObj.name = "Text";
                newObj.transform.position = MatrixUtils.PositionFromMatrix(poseMatrix);
                newObj.transform.rotation = MatrixUtils.QuaternionFromMatrix(poseMatrix);
            
        

frame.planePose는 4x4 변환행렬로 3차원공간에서의 자세정보를 보관하고 있습니다.

이상의 과정을 거쳐 HelloSpace4 앱을 완성하였습니다.
HelloSpace4의 전체 소스는 SDK 패키지에서 확인해볼 수 있습니다.







HelloSpace4 (마커인식) Tutorial

HelloSpace4 공간인식 예제와 많은 부분이 같으며 카메라설정과 세션설정에서 차이가 있습니다.
또한 마커인식에서는ARMarkerTracker 프리팹을 이용하여 마커 트래킹을 진행합니다.




1. 카메라설정

공간인식 AR카메라와 달리X축 기준 90도로 회전설정합니다.


2. 마커인식 세션설정

- 오브젝트 ARSession을 생성합니다.
빈 오브젝트를 ARSession으로 생성하고 여기에 Space4Kit의 SARSession스크립트를 추가하고 Track Mode를 “Marker Recognition”으로 설정합니다.

- 마커인식 세션설정을 진행합니다.
세션설정은 SARSession스크립트의 바로 아래 위치한 “Open Space4 Engine configuration”버튼을 클릭하여 Space4Configuration으로 이동합니다.
라이선스 키와 Start automatically옵션설정은 공간인식예제와 같으며 자세한 내용은 여기를 눌러 확인하실 수 있습니다.

3. 마커 트래커 설정

- Database리스트에서 트래킹하려는 마커이미지를 선택하여 줍니다.
먼저 트래킹하려는 마커이미지를 StreamingAssets / Space4 폴더에 복사해 넣어줍니다.
그러면 SARMarkerTrackable스크립트의 database리스트에 자동적으로 추가됩니다.

- Space4Kit / Prefabs / ARMarkerTracker 프리팹을 HelloSpace4에 추가합니다.
배치한 ARMarkerTracker 오브젝트의 SARMarkerTrackable 스크립트의 arSession성원변수에 이미 생성한 ARSession오브젝트를 연결시켜줍니다.

- 마지막으로 ARMarkerTracker 프리팹의 하위에 3D모델 Prefab인 monkey.prefab파일을 끌어다 넣어줍니다.


이상으로 Space4Kit이용을 위한 AR카메라, AR세션, 마커트래커 설정을 진행하였습니다.







HelloSpace4 (얼굴인식) Tutorial

HelloSpace4 공간인식 예제의 카메라설정을 포함하여 많은 부분이 같으며 세션설정에서 차이가 있습니다.




1. 얼굴인식 세션설정

- 오브젝트 ARSession을 생성합니다.
빈 오브젝트를 ARSession으로 생성하고 여기에 Space4Kit의 SARSession스크립트를 추가하고 Track Mode를 “Face Recognition”으로 설정합니다.

- Space4Engine 설정을 진행합니다.
세션설정은 SARSession스크립트의 바로 아래 위치한 “Open Space4 Engine configuration”버튼을 클릭하여 Space4Configuration으로 이동합니다.
라이선스 키와 Start automatically옵션설정은 공간인식예제와 같으며 자세한 내용은 여기를 눌러 확인하실 수 있습니다.

2. 세션이 시작되면 실시간으로 검출결과를 리턴하게 되며 이용자는 세션의 getCurrentFrame() 이나 getCurrentStatus()와 같이 실시간 상태를 반환하는 함수들을 이용하여 실시간적인 처리를 진행할 수 있습니다.

copy
            

                List anchors = currentFrame.anchors;
                foreach (var an in anchors)
                {
                    if (an is SARFaceAnchor)
                    {
                        SARFaceAnchor faceanchor = (SARFaceAnchor)an;
                        var landmarks = faceanchor.landMarkPts;
                        var x = Math.Min(ltop.x, rbottom.x);
                        var y = Math.Min(ltop.y, rbottom.y) - 30;
                        var width = Math.Abs(ltop.x - rbottom.x);
                        var height = Math.Abs(ltop.y - rbottom.y);
                        var faceDB = arSession.getFaceDB();
                        var name = faceDB.recognize(faceanchor);
                        GUI.Box(new Rect(new Vector2(x, y), new Vector2(width, height)), name, skin.box);
                        foreach (var mark in landmarks)
                        {
                            Vector2 position = getScaledPositionForGUI(mark);
                            GUI.DrawTexture(new Rect(position.x - 5, position.y - 5, 10, 10), markerTexture);
                        }
                    }
                }
            
        

위의 예제에서는 프레임에서 검출된 인물의 랜드마크 (특징점모임)와 인식영역을 실시간으로 보여줍니다.
랜드마크는 인물을 식별하는데 기준이 되며 68개의 점으로 이루어져 있습니다.







HelloSpace4 (QR코드인식) Tutorial

HelloSpace4 공간인식 예제의 카메라설정을 포함하여 많은 부분이 같으며 세션설정에서의 차이가 있습니다.




1. QR코드인식 세션설정

- 오브젝트 ARSession을 생성합니다.
빈 오브젝트를 ARSession으로 생성하고 여기에 Space4Kit의 SARSession스크립트를 추가하고 Track Mode를 “Code Recognition”으로 설정합니다.

- Space4Engine 설정을 진행합니다.
SARSession스크립트의 바로 아래 위치한 “Open Space4 Engine configuration”버튼을 클릭하여 Space4Configuration으로 이동합니다.

라이선스 키와 Start automatically옵션설정은 공간인식예제와 같으며 자세한 내용은 여기를 눌러 확인하실 수 있습니다.

Try Rotate옵션을 체크하면 QR코드의 회전상태를 고려하여 화면의 여러 각도에 배치되어 있는 경우에도 코드를 정확히 검출할 수 있습니다.

2. 세션트래킹이 시작되면 Update() , OnGUI()에서 트래킹결과를 확인해볼 수 있습니다.

copy
            

                if (arSession.getCurrentStatus() == SARSessionStatus.TRACKING)
                {
                    SARFrame currentFrame = arSession.getCurrentFrame();
                    List anchors = currentFrame.anchors;
                    if (anchors != null && anchors.Count > 0)
                    {
                        Debug.Log("anchors.Count = " + anchors.Count);
                        foreach (var anchor in anchors)
                        {
    	                    // … Do Something to check results
	                    }
                    }
                }
            
        

위의 예제에서 보는것처럼 실시간으로 처리되는 프레임은 세션의 getCurrentFrame()을 호출하여 얻을 수 있습니다.
프레임에서 검출된 QR 코드정보는 프레임객체의 anchors 멤버변수에 저장되어 있으며 이용자는 List형 객체인 anchors 변수를 활용하여 필요한 작업을 할 수 있습니다.