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






Quick Start




- 환경설정

o 인터넷 연결
o iOS v10.0 이상 권장
o Xcode v11.x 이상 권장
o OpenCV 3.4.3 iOS Framework
o Metal 기반 렌더링

- Space4 SDK 다운로드

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

- Hello프로젝트

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







HelloSpace4 (공간인식) Tutorial

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




1. XCode 새로운 프로젝트 HelloSpace4를 생성합니다.

2. Space4Kit iOS 패키지 (Space4Kit 프레임워크) 를 다운받고 생성한 프로젝트에 Import 합니다.
o Frameworks 폴더안의 Space4Kit.framework와 module.modulemap 파일을 새로 생성한 프로젝트 폴더안에 복사합니다.

o 프로젝트의 Build Settings 에서 다음과 같이 수정합니다.
Framework Search Paths, Header Search Paths, Import Paths 속성들에 위에서 추가한 프레임워크의 폴더경로를 추가합니다.

3. AR 렌더러를 위한 UIView를 Main.storyboard에 배치합니다.
이를 위해 SDK전용 AR렌더러 SARRenderer를 이용하며 구체적인 소스코드는 Hello프로젝트를 참고해주세요.
SARRenderer에는 Background 렌더링을 위한 BackgroundRenderer와 공간인식에서 이용될 큐브 렌더러 CubeRenderer 그리고 평면 렌더링을 위한 CircleRenderer를 내장하고 있습니다.

이와 함께 UI와 SARRenderer를 연결해주는 PreviewView 클래스 (Hello 프로젝트 소스코드 참고)를 추가합니다.
4. 라이선스 인증 및 SDK 초기화를 진행합니다.
SDK 이용초기에 발급받은 라이선스에 대한 인증과정이 필요합니다.
SARSDK클래스를 이용하여 인증단계를 거치며 인증의 성공여부에 따라 SDK 이용가능하거나 제한되게 됩니다.

copy
            

                SARSDK.Initialize(Your License key ......")
            
        

이와 함께 SDKDelegate 설정 및 렌더러 초기화를 진행합니다.

copy
            

                SARSDK.setDelegate(self)
                renderer.initialize(rect: self.view.frame)
                renderer.layers.foreach({previewView.addSubLayer($0)})
            
        

5. AR세션설정을 진행하고 세션을 시작합니다.
SDK 초기화가 성공하면 즉 SARSDK.status가 SUCCESS이면 AR세션을 시작할 수 있습니다.
공간인식 세션설정을 위해서 SARWorldTrackingConfiguration 클래스를 이용합니다.
모든 세션의 공유설정인 카메라설정과 함께 공간인식 고유의 설정인 WorldMap(공간맵)을 설정합니다.
필요에 따라 (새로운 공간맵을 생성하려는 경우) 초기의 공간맵을 설정하지 않을 수도 있습니다.

copy
            

                let configuration: SARWorldTrackingConfiguration = SARWorldTrackingConfiguration()
                guard let supportedFormats = configuration.getSupportedVideoFormats() else { return }
                configuration.setActiveFormat(inputFormat: supportedFormats[4])
                configuration.trackMode = SARWorldTrackingConfiguration.TrackMode.Full
                configuration.planeDetectionMode = .Both
        
                // load existing map
                if map != nil {
                    configuration.setInitialWorldMap(map: map!)
                }
        
                session = SARSession(to: self)
                Session!.submitConfiguration(submit: configuration)
                Session!.start()
                // set session to renderer
                Self.renderer.setSession(session: session!)
            
        

setActiveFormat() 을 통하여 이용하게 될 카메라의 기본기능을 설정합니다.
그리고 공간맵설정을 위한 setInitialWorldMap()와 함께 setTrackMode(), setPlaneDetectionMode()와 같은 함수를 이용하여 공간인식세션에서 VIO/VO모드와 평면검출방식 등을 지정해줄 수 있습니다.
예제에서는 세션 구동방식을 VIO모드로 설정하고 수평, 수직면을 모두 검출하도록 설정하였습니다.
세션의 submitConfiguration()을 통하여 최종 세션설정을 마치고 start()함수의 호출로 바로 세션을 시작합니다.
세션시작을 마치면 렌더러에 구동중인 세션을 등록합니다.

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

copy
            

                // Delegate 함수 구현
                extension ViewController: SARSessionDelegate {
	                func onUpdateFrame(status: SARSessionStatus, frame: SARFrame) {
	                    DispatchQueue.main.async {
		                    // 새 프레임을 렌더
	  	                    self.renderer.update(frame)		
		                    // … Do whatever you want …
	                    }
	                }
                }
            
        

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

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

copy
            

                guard let session = session,
                let frame = session.getCurrentFrame(),
                let pose = frame.planePose,
                let worldMap = session.getCurrentWrodlMap() else {return}
        
                worldMap.addAnchor(SARWorldAnchor(transform: pose, name: "Cube"))
            
        

위 예제에서 검출된 평면에 SARWorldAnchor 객체를 생성하고 세션에 등록해줍니다.

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







HelloSpace4 (마커인식) Tutorial

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




- 마커인식 세션설정

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

copy
        

                let markerDB = SARMarkerDB()
                markerDB.load(path: [“… path to marker database file …”])

                // set markerDB to session configuration
                configuration.setInitialDB(initial: markerDB)

            
            

- 검출된 마커에 대한 처리

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







HelloSpace4 (얼굴인식) Tutorial

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




- 얼굴인식 세션설정

얼굴인식 세션에서는 이미 준비된 인물DB가 있다면 세션설정시 인물DB를 등록하여 이용할 수 있습니다.

copy
            

                let faceDB = SARFaceDB()
                faceDB.load("… path to face database file …")

                // set faceDB to session configuration
                configuration.setInitialDB(initial: faceDB)

            
        

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

- 검출된 얼굴에 대한 처리

렌더링은 SARRenderer와 함께 얼굴인식 전용 FaceRenderer (Hello 프로젝트 참고)를 이용하여 진행합니다.
검출된 얼굴정보는 Delegate로 리턴되는 프레임객체 SARFrame에 보관되며 getAnchors()함수를 호출하여 인물정보를 확인해볼 수 있습니다.
대표적으로 랜드마크정보(68개의 얼굴 특징점모임)와 성별, 나이, 인물식별 등의 정보를 보관하며 SARFaceAnchor 객체의 속성값으로 표현됩니다.







HelloSpace4 (QR코드인식) Tutorial

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




- QR 코드인식 세션설정

QR 코드인식의 세션설정에서는 카메라설정과 함께 QR코드검출방식을 지정해줄 수 있습니다.

copy
            

                let configruation = SARCodeTrackingConfiguration()
                guard let supportedFormats = configuration.getSupportedFormats() else {return}

                conf.setActiveFormat(format: supportedFormats[1])

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

            
        

위 예제와 같이setTryRotate함수를 이용하면 QR코드의 회전상태를 고려하여 화면의 여러각도에 배치되어 있는 경우에도 코드를 정확히 검출하도록 합니다.

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

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