Letsee WebAR SDK

렛시 WebAR SDK는 웹 기반 증강현실을 위한 자바스크립트 라이브러리입니다. 간편하게 설계된 ARWebApp 규격은 일반적인 HTML5 기반의 웹 페이지들을 CSS, JavaScript 만으로 편리하게 AR 콘텐츠로 만들 수 있도록 해주어, 표준 웹 기술을 지원하는 현대의 모바일 웹 브라우저에서 네이티브 앱 설치 없이 쉽고 빠르게 증강현실 애플리케이션 구현을 실현합니다.

릴리스 노트 (Release Notes)

Latest WebAR SDK v1.1.3 : Released Date (2021.05.17)

  • v1.1.3

    • 배포일 : 2021.05.14
    • wasm 버전 : v1.2.18
      • Aruco 트래커 기능 구현
      • QR 트래커 기능 구현
      • Watermark 수정 및 기능 구현
    • letsee.init() 호출 시 Engine에서 어떤 타입의 Tracker를 활성화 시킬지에 대한 option 전달 받을 수 있도록 기능 확장
      • 현재 버전에서 구동 가능한 Tracker는 다음과 같이 3가지 종류가 있음
        • Image Tracker
        • Aruco Marker Tracker
        • Qrcode Tracker
      • letsee.init({ trackerType: 'image' })와 같은 형식으로 letsee.init 함수에 옵션 객체(object) 넘겨주어 해당 Tracker를 동작 시킬 수 있음
    • letsee.start() 호출시 어떤 video stream을 사용할지에 대한 config를 받을 수 있도록 기능 확장
      • uri 동영상파일, 전면카메라 또는 후면카메라 중에서 원하는 Stream을 선택하여 해당 영상 스트림으로 SDK를 동작시킴
      • 동영상 파일은 loop 옵션을 통해 '반복적으로 재생'을 할지 '한번만 동작'을 시킬지 지정할 수 있음
      • 전면카메라를 얻어오기 위한 label의 keyword를 새로 등록 후 전면카메라를 사용시 해당 keyword를 통해 전면 카메라의 deviceId를 얻어올수 있도록 구현
      • letsee.start({ isVideo: true, uri: './test.mp4', loop: true })와 같은 형식으로 letsee.start 함수에 옵션 객체(object) 넘겨주어 선택된 스트림을 통한 SDK를 구동할 수 있도록 구현
    • SDK Three.js를 사용하여 증강현실 구현 시, Three.js의 Raycaster 사용을 도와주는 RaycasterManager 및 사용자 함수 구현
      • addThree() 함수 호출시 RaycasterManager를 생성함
      • letsee.useTHREERay: SDK에서 raycaster 기능을 on/off
      • letsee.addTHREERayObjects: 충돌 검사를 수행할 Object3D를 등록
      • letsee.removeTHREERayObjects: 충돌 검사를 위해 등록된 Object3D를 제거
      • letsee.onIntersectedObjects: 충돌 검사를 통해 검출된 Object3D 전달하는 callback함수 등록
    • Three 렌더러와 HTML 렌더러가 동시에 동작할 때, HTML 요소의 클릭이나 interaction 동작되지 않는 에러 해결
      • 문제의 원인은 Three 렌더러와 HTML 렌더러가 같은 z-index를 가지기 때문에 발생함.
      • 이때 Three 렌더러의 속성으로 pointer-event 속성을 이용하여 Three 렌더러의 클릭 이벤트를 무시하고, 이로 인해 HTML 렌더러가 클릭이 되지 않는 문제 해결
      • 추가적으로 Three의 Raycaster를 사용할때에는 앞에 HTML 요소가 있으면 Html요소가 선택되고, 3D Object가 있으면 3D Object가 선택되도록 Three 렌더러의 pointer-event 속성를 조정하여 구현.
    • SDK에서 모바일 단말기의 모션 센서(IMU) 데이터를 전달받을수 있는 사용자 함수 구현
      • DeviceMotion 이벤트와, DeviceOrientation 이벤트를 재가공하여 가속도(accelerometer), 중력을포함한가속도(accelerometerIncludingGravity), 각속도(rotationRate), 방향(orientation)을 전달받을수 있는 콜백 핸들러 함수 구현
      • letsee.onAccelerationChange: 가속도에 대한 정보를 전달받는 콜백 함수 등록
      • letsee.onAccelerationIncludingGravityChange: 중력을 포함한 가속도에 대한 정보를 전달받는 콜백 함수 등록
      • letsee.onRotationRateChange: 각속도에 대한 정보를 전달받는 콜백 함수 등록
      • letsee.onOrientationChange: 방향에 대한 정보를 전달받는 콜백 함수 등록
    • XRElement Class에서 XRElement 타입의 자식을 추가하거나 제거하는 메서드 구현
      • Object3D의 add및 remove작업을 이용하여 XRElement를 htmlRenderer가 rendering중일때 자식으로 추가하거나 제거하면 엔진에 잔상이 남는 문제 발생
      • 따라서 XRElement 클래스에 메서드를 자식 추가 및 삭제 메서드를 별도로 구현하여 위와 같은 잔상이 남는 문제 해결
      • XRElement.addChild: XRElement 자식 추가
      • XRElement.removeChild: XRElement 자식 제거
    • Html 렌더러와 Three 렌더러가 동시에 돌때 가끔 HTML 컨텐츠와 Three 컨텐츠중 한쪽만 보이는 에러 해결
      • Html 렌더러와 Three 렌더러가 동시에 동작 할때 각각의 Scene이 같은 Entity를 가져야 함
      • 문제 원인은 Three.js Scene에 entity를 add 함수로 추가하거나 또는 htmlRenderer의 Scene에서 entity를 add함수로 추가할 때, 즉 Entity가 다른쪽 Scene으로 이동할때 Entity의 부모(object.parent)를 찾아 해당 부모의 children배열에서 Entity를 제거후 다른 Scene으로 이동함
      • 따라서 Letsee에서 사용하는 Object3D의 add 함수에서 Entity타입의 Object3D가 자식으로 추가될때 부모(Scene)를 찾아서 해당 Entity를 제거하지 않도록 예외 처리후 문제 해결
    • Watermark 계산을 위한 insight.setFrame() 로직 수정
      • Wasm에서 watermark의 좌표를 계산할 때, scaleToCover,innerHeight 두개의 값을 전달받아서 계산해야함
      • 따라서 setFrame시에 scaleToCover와 innerHeight값을 매 프레임마다 넘겨줄수 있도록 setFrame으로 넘겨주는 data 수정
    • 메모리 누수(Leak)을 막기위한 insight.setFrame() 로직 수정
      • 기존 setFrame함수를 통해 이미지를 wasm으로 전달할때, JS쪽의 ImageData 객체를 frame안에 담아서 직접 전달 후, Heap 메모리를 할당(malloc)하고 해제(free)하여 Wasm내부에서 이미지를 사용함.
      • 위와 같은 방법으로 setFrame을 사용했을때, JS와 Wasm 사이에서 메모리에 대한 누수가 일어나고, 메모리 누수가 누적되면 SDK가 메모리 Leak으로 멈춰버리는 문제 발생
      • 따라서 wasm(insight)의 인터페이스로 _malloc과 _free를 JS에서 쓸수 있도록 미리 정의함
      • 이후 이미지 데이터를 저장할 HEAP 메모리를 선언하고, Heap메모리에 버퍼를 통해 Uint8Array를 저장한뒤, frame을 wasm으로 전달할때 Heap에 저장된 Uint8Array를 통해 CV_Mat 형식의 데이터를 선언후 해당 Matrix 전달
      • setFrame 이후 결과가 JS쪽으로 전달되면 _free함수를 통해 이미지를 저장한 HEAP영역의 메모리를 해지함. 이를 통해 memory leak을 해결할 수 있음.
    • IOS Safari Landscape 모드에서 클릭이나 터치 이벤트가 동작하지 않는 에러 해결
      • html 렌더러에서 가지는 perspective 값과 그 자식인 css camera 의 translateZ값이 정확하게 일치하기 때문에 문제 발생
      • 다른 브라우저에서는 동작을 잘 하지만, Safari 브라우저의 landscape 모드에서는 클릭,터치 이벤트가 동작하지 않음
      • 문제 해결을 위해 Perserve-3d가 적용된 css camera의 translateZ값을 0.1만큼 줄여서 카메라가 항상 HTMLRenderer 뒤로 오도록 로직 수정 후 문제 해결
    • letsee.addEntity 함수와 letsee의 place 태그를 통한 Entity 등록을 한꺼번에 사용시 발생하는 에러 해결
      • 기존 addTarget 함수에서 디스크립터와 이미지를 로드하는 무거운 작업 제거,
      • loadImage, loadDescriptor 와 같은 무거운 작업은 엔티티가 추가될때 엔진에서 처리하여 Entity를 추출한뒤 학습할 entity를 wasm으로 넘겨주도록 처리
      • addEntity와 scanStyleTag가 동시에 발생할때 순차적으로 처리되지 않아 발생하는 문제 제거
    • scanStyleTag 함수 동작시 에러 해결
      • scanStyleTag로 들어오는 xrElement가 entityManager의 xrElements 배열로 추가되지 않는 문제 수정
      • scanStyleTag를 통해 같은 uri를 가진 entity가 2번 이상 들어왔을때, entityManger의 entities 배열에 해당 entity가 이미 존재하면 wasm으로 해당 entity를 2번 이상 학습시키지 않도록 예외 처리

  • v1.1.2

    • 배포일 : 2021.03.05
    • wasm 버전 : v1.2.17
      • insight.init()시 경로를 입력받아 insight-worker의 경로를 blob 경로로 선언할수 있는 인터페이스 구현
      • KeyPoints 기반의 JSON 디스크립터를 통한 이미지 트래커 기능 구
    • XRElement 제어를 위한 사용자 함수 추가
      • createXRElement : HTMLElement나 DOM string을 입력받아 XRElement 객체를 생성.
      • bindXRElement : XRElement를 Entity와 연결
      • unbindXRElement : Entity와 XRElement간의 연결을 해제
      • getXRElementById : id 선택자로 XRElement 조회
      • getXRElementByClassName : class 선택자로 XRElement 목록을 조회
      • getAllXRElements : 모든 XRElement들의 목록을 반환
      • removeXRElement : XRElement를 삭제
      • removeAllXRElement : 모든 XRElement 목록을 삭제
    • Target Manager로 생성한 JSON Descriptor 호환
      • Letsee Developer의 Target Manager로 생성한 KeyPoints 기반의 JSON Descriptor 타입을 통하여 이미지를 학습시킬 수 있도록 인터페이스 확장
      • Insight.addTarget()에서 Insight.addExtractedTarget()로 네이밍 변경
      • 기존에 사용했던 Image 기반의 Json Descriptor도 사용할수 있도록 유지
      • JSON Descriptor 형식을 분석하여 어떤 타입(Keypoints 또는 Image)의 Descriptor인지 판단 후 해당 형식에 맞게 이미지를 학습시킬 수 있도록 설계
    • blob을 통한 insight-worker.js, insight-worker.wasm 경로 변경
      • SDK 이용시 insight-worker.js, insight-worker.wasm이 항상 같은 web 경로상에 존재하여야 하는 문제 해결
      • insight-worker.js, insight-worker.wasm의 경로를 blob을 통해 로컬로 다운로드하여 해당 blob 경로를 insight.init() 호출 시 해당 경로를 넘겨주어 insight 내부에서 치환될 수 있도록 wasm코드 및 insight.init() 인터페이스 수정
    • webpack 빌드 환경 구성 변경
      • webpack.dev.js, webpack-prod.js : Insight.init시 전달되는 AUTH_URL 추가
      • webpack.stage.js : SDK Webpack 빌드 후, insight.wasm, insight.js, insight.wasm, insight-worker.js, insight-worker.wasm, letsee.js 파일을 S3 버킷으로 upload 할수 있도록 환경 구성

  • v1.1.1

    • 배포일 : 2021.01.13
    • wasm 버전 : v1.2.11
    • Engine Pause & Resume 기능 추가
      • letsee.pause()가 호출되면 XRElement와 Three의 Scene과 Mesh 객체들의 Parent인 Entity의 pose matrix값을 마지막 위치에 대한 pose matrix로 값 대입.
      • Tracking이 진행되더라도 Entity의 PoseMatrix는 변화하지 않도록 수정. 이때, VideoRenderer는 계속 동작하기 때문에 백그라운드 비디오는 계속 돌고 Tracking만 되지 않음.
      • 만약 Pause기능을 사용할 때 마지막 Entity의 위치로 고정하는 것이 아니라 원하는 위치로 Entity를 입력하고 싶으면 letsee.pause()를 사용할 때 Param으로 pose matrix를 넘겨줄 수 있도록 확장성 구현.

  • v1.1.0

    • 배포일 : 2020.12.04
    • wasm 버전 : v1.2.11
    • 3D Raycasting을 위한 effectiveWidth, effectiveHeight를 ThreeRenderer property로 설정하여 쓸 수 있도록 구현
    • 각각의 Renderer에 스크린 정책 적용
    • Renderer의 Orientation이 일어날 때 Screen이 깨지는 에러 fix
    • ThreeRenderer, HTMLRenderer 동시 증강 시 한쪽 렌더러만 동작하는 에러 해결.
    • 외부에 별도로 동작하는 LetseeControl로 내부 ThreeRenderer로 다시 전환 (webpack 빌드시 wasm이 2번 호출되는 에러 발생 때문)
    • index.js에 addTHREE, addTarget, onTrackStart, onTrackMove, onTrackEnd 함수 생성
      • addTHREE : Three.js를 인자로 받아서 ThreeRenderer 관련 변수 반환 (renderer, camera, scene, update)
      • addTarget : 타겟 이미지 경로를 주입 후 해당 Target이미지에 대한 Entity 반환
      • onTrackStart, onTrackMove, onTrackEnd : TrackEvent 발생 시 유저가 등록할 수 있는 콜백 인터페이스 => 추후 LifeCycleManager로 관리
    • uri.js를 이용하여 Entity의 uri경로의 절대경로를 얻어오는 getAbsolutePath 로직을 재사용성이 좋도록 수정.