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






Quick Start




- 환경설정

o 인터넷 연결
o Android SDK 7.0 (API Level 24) 이상 권장
o Android Studio v3.x 권장

- Space4 SDK 다운로드

o 링크주소 : Space4Kit-Android_v1.0.zip

- Hello 프로젝트

o SDK 폴더안의 샘플 프로젝트를 오픈합니다.
o 빌드설정이 끝나면 바로 빌드를 진행하고 앱을 실행시킵니다.
o SDK가 제공하는 공간인식, 마커인식, 얼굴인식 샘플앱을 확인하실 수 있습니다.







HelloSpace4 (공간인식) Tutorial

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




- 안드로이드 새로운 프로젝트 HelloSpace4를 생성합니다.

- Space4Kit 안드로이드 패키지 (aar 라이브러리) 를 다운받고 생성한 프로젝트에 Import 합니다.
o Space4Kit_v1.0.aar 파일을 app/libs 폴더에 복사합니다.
o 복사한 aar파일을 프로젝트의 Dependencies에 추가합니다.

- AR렌더러를 위한 View (GLSurfaceView)를 추가하고 필요에 따라 버튼 등을 Layout에 추가합니다.
o 생성된 activity_main.xml에 GLSurfaceView을 추가합니다.

copy
            

                <android.opengl.GLSurfaceView android:id="@+id/glSurfaceView"
                                android:layout_width="match_parent"
                                android:layout_height="match_parent"/>
            
        

ㅇ 모델배치를 위한 버튼을 추가합니다.

copy
            

                <Button android:id="@+id/btn_place"
                ………
                android:layout_centerHorizontal="true"
                android:textColor="#FFFFFF"
                android:textStyle="bold" />
            
        

ㅇ 기타 필요한 부분은 Hello프로젝트의 Layout을 참고하기 바랍니다.

- Space4Kit SDK에서 지원하는 표준 렌더러 SARRenderer를 GLSurfaceView에 설정하고 AR세션을 등록합니다.
o GLSurfaceView 인스턴스를 생성하고 초기화 합니다.

copy
            

                private GLSurfaceView glSurfaceView;
            
        

MainActivity의 onCreate함수에서 초기화 합니다.

copy
            

                glSurfaceView = findViewById(R.id.glSurfaceView);
                glSurfaceView.setEGLContextClientVersion(2);
                glSurfaceView.setEGLConfigChooser(8, 8, 8, 8, 16, 0);
                glSurfaceView.getHolder().setFormat(PixelFormat.TRANSLUCENT);
            
        

o SDK에서 공간인식을 위한 샘플 렌더러 SARSampleRenderer (SARRenderer의 파생클래스) 를 프로젝트에 복사해줍니다.
o glSurfaceView에 샘플 렌더러를 세팅합니다.

copy
            

                SARSampleRenderer renderer = new SARSampleRenderer(this, false);
                glSurfaceView.setRenderer(renderer);
                glSurfaceView.setRenderMode(GLSurfaceView.RENDERMODE_CONTINUOUSLY);
            
        

AR렌더러를 위하여 SARRenderer에서는 GLES 2.0을 기본으로 사용하며 이용자 별도의 렌더러를 구성하여 이용할 수도 있습니다.
o AR세션을 생성하고 렌더러에 설정합니다.

copy
            

                private SARSession session = null;
                session = new SARSession(this); 
                renderer.setSession(session);
            
        

- 라이선스 인증 및 SDK 초기화를 진행합니다.
SDK 이용초기에 발급받은 라이선스에 대한 인증과정이 필요합니다.
SARSDK클래스를 이용하여 인증단계를 거치며 인증의 성공여부에 따라 SDK 이용가능하거나 제한되게 됩니다.
라이선스 키를 발급받는 방법은 여기 에서 확인해 주십시오.

copy
            

                SARSDK.Initialize(this, null,  "..... Your License key ......");
            
        

- SDK 초기화 및 라이선스 인증이 완료되면 공간 트래킹을 시작합니다.
o SDK 상태를 검사하고 라이선스 인증 및 SDK초기화에 성공하면 세션을 시작합니다.
라이선스 인증상태에서 SDK는 PENDING상태를 유지하며 성공하면 SUCCESS로 상태가 바뀝니다.

copy
            

                //wait for initialization is successed
                while (SARSDK.getStatus() == SARSDK.INITSTATUS.PENDING )
                {
                    try {
                        Thread.sleep(5);
                    } catch (InterruptedException e) {
                        e.printStackTrace();
                    }
                }
                if (SARSDK.getStatus() == SARSDK.INITSTATUS.SUCCESS){
                    // Configuration for WorldTracking
                    SARWorldTrackingConfiguration configuration = new SARWorldTrackingConfiguration(getApplicationContext());
                    // set camera resolution via SARWorldTrackingConfiguration
                    Size format = configuration.getSupportedVideoFormats()[0];
                    configuration.setActiveFormat(format);
                    //set mode to TrackMode.Full for VIO tracking mode
                configuration.setTrackMode(SARWorldTrackingConfiguration.TrackMode.Full);
                    configuration.setPlaneDetectionMode(SARWorldTrackingConfiguration.PlaneDetectionMode.Horizontal);
                    // Create and start session using configuration
                    session.submitConfiguration(configuration);
                    session.start();
                }
                else
                { … … }
            
        

공간인식 세션설정을 위해서 SARWorldTrackingConfiguration 클래스를 이용합니다.
모든 세션의 공유설정인 카메라설정과 함께 공간인식 고유의 설정인 WorldMap (공간맵) 을 설정합니다.
필요에 따라 (새로운 공간맵을 생성하려는 경우) 초기의 공간맵을 설정하지 않을 수도 있습니다.
setActiveFormat() 을 통하여 이용하게 될 카메라의 기본기능을 설정합니다.
그리고 공간맵설정을 위한 setInitialWorldMap()와 함께 setTrackMode(), setPlaneDetectionMode()와 같은 함수를 이용하여 공간인식세션에서 VIO/VO 모드와 평면검출방식 등을 지정해줄 수 있습니다.
예제에서는 세션 구동방식을 VIO 모드로 설정하고 수평평면만 검출하도록 설정하였습니다.
세션의 submitConfiguration()을 통하여 최종 세션설정을 마치고 start()함수의 호출로 바로 세션을 시작합니다.

- 구동중인 세션의 실시간결과를 얻기 위하여 Delegate를 설정합니다.
SDK에서 제공하는 SARSessionDelegate를 이용하여 세션의 처리결과를 실시간으로 확인할 수 있습니다.

copy
            

                public class MainActivity extends Activity implements SARSessionDelegate
            
        

위 코드에서 보는것처럼 Activity에 Delegate를 적용하였습니다.
그리고 세션생성 함수의 파라메터로 Delegate를 구현하고 있는 클래스를 설정해주어 세션결과를 리턴할 수 있습니다.

copy
            

                session = new SARSession(this); // this : delegate for …
            
        

- 등록한 Delegate를 이용하여 세션의 실시간결과를 처리합니다.
SARSessionDelegate는 여러개의 함수를 제공하며 그중에서 onUpdateFrame()함수는 세션의 현재상태와 프레임정보를 리턴합니다.

copy
            

                @Override
                public void onUpdateFrame(SARSessionStatus status, final SARFrame frame) {
                    runOnUiThread(() -> {
                        // Do whatever you want …
                        switch (status) {
                            case NOT_READY:
                                break;
                            case INITIALIZE:
                                break;
                            case LOST:
                                break;
                            case TRACKING:
                                break;
                        }
                    });
                }
            
        

위 예제에서 보는것처럼 SARFrame클래스를 이용하여 세션내에서 처리중인 모든 프레임에 대한 정보를 얻고 처리할 수 있습니다.

- 가상공간의 임의 위치에 큐브를 배치합니다.
세션이 트래킹중이고 평면이 검출되면 공간에 가상오브젝트를 배치할 수 있습니다.
모든 가상객체는 Anchor에 의하여 공간상에 표현되며 공간맵의 객체는 SARWorldAnchor에 의해 표현됩니다.

copy
            

                if (session.getCurrentStatus() ==SARSessionStatus.TRACKING) {
                    SARFrame frame = session.getCurrentFrame();
                    float[] planePose = frame.getPlanePose();
                    SARAnchor cube = new SARWorldAnchor(planePose, "Cube");
                    session.getCurrentWorldMap().addAnchor(cube);
                 }
            
        

위 예제에서 검출된 평면에 SARWorldAnchor 객체를 생성하고 세션에 등록해줍니다.
이로서 세션은 새로운 Anchor객체를 접수하고 SARSampleRenderer를 통해 큐브를 렌더링하게 됩니다.

이상의 예제에서 Space4Kit 공간인식 세션의 구동과 결과를 확인하여 보았습니다.
HelloSpace4의 전체 소스는 SDK 패키지에서 확인해볼 수 있습니다.







HelloSpace4 (마커인식) Tutorial

HelloSpace4 공간인식 예제와 많은 부분이 같으며 세션설정과 세션결과에 대한 처리부분에서 차이가 있습니다.




- 마커인식 세션설정

마커인식 세션에서는 이용하고자 하는 마커를 세션구동 초기에 SARMarkerDB클래스를 통하여 설정할 수 있습니다.

copy
            

                    SARMarkerDB db = new SARMarkerDB();
                    if (!db.load(new String[]{
                        "/sdcard/Space4Kit/marker1.jpg",
                        "/sdcard/Space4Kit/marker2.jpg",
                        "/sdcard/Space4Kit/marker3.jpg"})) {
                        Log.e("MarkerTracker", "Failed to load marker db.");
                        return;
                    }

                    conf.setInitialDB(db);
            
        

위 예제에서 마커로 이용될 이미지로 3개의 파일을 마커DB에 지정하여 주었습니다.
이러한 마커DB를 setInitialDB()를 통하여 세션설정클래스에 설정합니다.

- 검출된 마커에 대한 처리

세션구동이 시작되면 마커검출이 실시간으로 진행되며 위 예제에서 언급되었던 Delegate를 통하여 검출결과가 리턴됩니다.
세션에서 검출된 마커는 Delegate로 리턴되는 프레임객체 SARFrame에 보관되며 getAnchors()함수를 호출하여 마커정보를 확인해볼 수 있습니다.







HelloSpace4 (얼굴인식) Tutorial

HelloSpace4 공간인식 예제와 많은 부분이 같으며 세션설정과 세션결과에 대한 처리부분에서 차이가 있습니다.




- 얼굴인식 세션설정

얼굴인식 세션에서는 이미 준비된 인물DB가 있다면 세션설정 시 인물DB를 등록하여 이용할 수 있습니다.
인물DB에는 등록된 인물들에 대한 랜드마크, 인물정보 등 매 인물에 대한 정보가 보관되게 됩니다.

copy
        

                SARFaceDB facedb = new SARFaceDB();
                facedb.load("… path to face database file …");

                // config initial map
                configuration.setInitialDB(facedb);

            
        

인물DB는 파일형태로 보관 및 로드되며 DB파일의 경로를 SARFaceDB에 설정하여 인물DB를 로드합니다.
이러한 인물 DB를 setInitialDB()를 통하여 세션설정클래스에 설정합니다.

- 검출된 얼굴에 대한 처리

세션구동이 시작되면 얼굴검출이 실시간으로 진행되며 위 예제에서 언급되었던 Delegate를 통하여 검출결과가 리턴됩니다.
검출된 얼굴정보는 Delegate로 리턴되는 프레임객체 SARFrame에 보관되며 getAnchors()함수를 호출하여 인물정보를 확인해볼 수 있습니다.

copy
        

                List anchors = frame.getAnchors();

            
        

대표적으로 랜드마크정보 (68개의 얼굴 특징점모임)와 성별, 나이, 인물식별 등의 정보를 보관하며 SARFaceAnchor 객체의 속성값으로 표현됩니다.
SDK는 표준으로 SARRenderer에 세션이 등록되었다면 검출된 인물의 정보를 시각적으로 렌더링하여 줍니다.







HelloSpace4 (QR코드인식) Tutorial

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




- QR 코드인식 세션설정

copy
        

                    SARCodeTrackingConfiguration conf = new
                    SARCodeTrackingConfiguration(this);

                    Size format = conf.getSupportedVideoFormats()[1];
                    conf.setActiveFormat(format);

                    // for QRCode detection mode
                    conf.setTryRotate(true);

                
            

QR 코드인식의 세션설정에서는 카메라설정과 함께 QR코드검출방식을 지정해줄 수 있습니다.
위 예제와 같이setTryRotate함수를 이용하면 QR코드의 회전상태를 고려하여 화면의 여러각도에 배치되어 있는 경우에도 코드를 정확히 검출하도록 합니다.

- 검출된 QR코드에 대한 처리

QR코드인식 세션에서도 위 예제들에서와 같이 Delegate를 이용하여 세션결과를 실시간으로 처리할 수 있습니다.