letsee

letsee

Letsee SDK를 Script를 통해 import 하면 자동으로 생성되는 Letsee의 기본 class입니다. Letsee SDK의 스크립트 로딩 후 웹 브라우저에서 글로벌 객체인 window.letsee 또는 letsee로 접근할 수 있습니다. Letsee SDK를 사용하여 증강 컨텐츠를 제작할 때 할때 해당 글로벌 객체인 letsee 이용하여 개발을 진행합니다.

Constructor

new letsee()

WebAR SDK가 실행되면, window.letsee로 접근가능한 Letsee class 입니다. 아래는 가장 간단하게 WebAR SDK를 다운받고 place media 태그를 사용하여 Hello World 문자열을 마커위에 출력하는 예제입니다.

Example
<!DOCTYPE html>
<html lang="en">
   <head>
      <meta charset="UTF-8">
      <title>Letsee WebAR SDK Test WebApp</title>
      <script src="https://developer.letsee.io/api/webar?key=YOUR_APP_KEY"></script>
      <style media="place" type="text/css">
         #container {
             -letsee-target: uri('toystory.json');
             width: 140px;
             height: 200px;
             border: 4px solid red;
         }
      </style>
   </head>
   <body>
      <div id="container">
         <button>Hello World</button>
      </div>
      <script>
         letsee.ready(() => {
                letsee.start();
            });
         letsee.init();
      </script>
   </body>
</html>

Methods

init()

Letsee의 SDK의 Engine을 준비를 시작하고 초기화를 진행하여 SDK가 동작할 준비를 합니다.

Example
letsee.init();

ready(callback)

Letsee SDK의 Engine 준비가 완료되고 하고 기본적인 초기화가 모두 진행된후 호출되는 콜백 이벤트를 등록합니다.

Example
letsee.ready();
Parameters:
Name Type Description
callback function

SDK Engine이 준비가 되면 호출되는 callback 함수.

start()

Letsee SDK를 실제로 동작시킵니다. letsee.start()가 호출되면 디바이스로부터 카메라 프레임을 얻어온 뒤 이미지로 바꾼 후, 매 프레임마다 Engine으로 해당 이미지를 전달합니다. letsee.start()는 항상 letsee.ready()의 콜백 함수 안에 선언되어야합니다.

Example
letsee.ready(() => {
   letsee.start();
});

pause(pose)

마커에 증강된 Entity의 증강(Tracking)을 멈추고 화면에서 일시적으로 Pause를 수행합니다. 만약 16자리의 Pose Array(ModelView Matrix)를 인자로 넘겨주면 해당 pose Matrix 위치로 이동하여 Pause를 수행합니다.

Example
letsee.pause();
Parameters:
Name Type Description
pose undefined | Array(16)

16자리 ModelView Matrix Array

resume()

멈춰진 Entity가 마커에서 다시 증강(Tracking)되어 보일수 있도록 Resume을 수행합니다. 만약 16자리의 Pose Array(ModelView Matrix)를 인자로 넘겨주면 해당 pose Matrix 위치로 이동하여 Resume를 수행합니다.

Example
letsee.resume();

onTrackStart(callback)

TrackStart 이벤트가 전파됬을 때 동작하는 콜백 이벤트를 등록합니다. Entity(마커)가 카메라 화면 안에 들어와 SDK Engine이 마커 검출(detection)을 성공했을때 TrackStart 이벤트가 발생합니다.

Example
// 마커 Tracking 시작 후 호출
letsee.onTrackStart(e => {
    console.log('TrackStart 이벤트 호출');
    console.log(e); // TrackEvent 출력
})
Parameters:
Name Type Description
callback function
Properties
Name Type Description
event TrackEvent

TrackStart Event 전달

onTrackMove(callback)

TrackMove 이벤트가 전파됬을 때 동작하는 콜백 이벤트를 등록합니다. 마커 검출(detection) 이후, 카메라 화면안에서 Entity(마커)가 움직일때 해당 마커에 대해 SDK Engine이 해당 마커를 추적(Tracking)합니다. 추적(Tracking) 중일 때 마커가 화면 안에 있으면 반복적으로 TrackMove 이벤트가 발생합니다.

Example
// 마커 Tracking 동작 중일때 호출
letsee.onTrackMove(e => {
    console.log('TrackMove 이벤트 호출');
    console.log(e); // TrackEvent 출력
})
Parameters:
Name Type Description
callback function
Properties
Name Type Description
event TrackEvent

TrackMove Event 전달

onTrackEnd(callback)

TrackEnd 이벤트가 전파됬을 때 동작하는 콜백 이벤트를 등록합니다. 추적(Tracking)상태에서 마커(Entity)가 화면 밖으로 이동하여 마커가 화면밖에서 벗어나거나, 일부 가려졌을 때, 추적(Tracking)이 풀리게 됩니다. 이 때 TrackEnd 이벤트가 발생합니다.

Example
// 마커 Tracking 종료 후 호출
letsee.onTrackEnd(e => {
    console.log('TrackEnd 이벤트 호출');
    console.log(e); // TrackEvent 출력
})
Parameters:
Name Type Description
callback function
Properties
Name Type Description
event TrackEvent

TrackEnd Event 전달

addTarget(uri) → {Entity}

마커의 이미지 타겟(descriptor)을 SDK 엔진에 등록하고, 결과로 마커(Entity) 객체를 얻어옵니다. 이후 XRElement를 생성 후 해당 Entity를 타겟으로 등록(binding)시켜 화면에 출력합니다.

Example
letsee.init();
letsee.ready(() => {
   letsee.start();
   letsee.addTarget('test.json').then(entity => {
       const helloWorldElem = document.createElement('div');
       helloWorldElem.innerHTML = 'Hello world!';
       const xrElement = letsee.createXRElement(helloWorldElem);
       letsee.bindXRElement(xrElement, entity);
});
Parameters:
Name Type Description
uri string

마커 이미지의 uri 경로

Returns:
Type
Entity

addTHREE(threejs) → {Promise.<ThreeRendererEvent>}

THREE.js를 연동하고 Three.js의 3D world를 마커(Entity)위에 증강시킬 수 있는 환경을 구축할때 사용합니다. 첫번쨰로, THREE 라이브러리를 연동하고 해당 THREE 라이브러리를 Promise 함수로 전달합니다. 이후, callback 함수를 통해 letsee SDK의 THREE.js world를 증강시키는 SDK의 THREERenderer에 대한 renderer, camera, scene, update를 얻어옵니다.

renderer

  • Letsee SDK와 연동 된 three.js의 renderer 입니다.
  • renderer 3D 공간을 마커(Entity) 위에 render할 때 필요합니다.

camera

  • Letsee SDK와 연동 된 three.js의 perspective camera 객체입니다.
  • 해당 camera는 SDK를 구동시키는 모바일 디바이스에 대한 fov값과 aspect ratio를 가지고 있습니다.

scene

  • Letsee SDK와 연동 된 three.js의 Scene 객체입니다.
  • SDK를 사용하는 개발자가 해당 Scene 객체 위에 자신이 증강시키고 싶은 Three.js의 컨텐츠를 만들고 해당 Scene위에 추가할 수 있습니다.

update

  • requestAnimationFrame() 에서 Scene이 한번 render 될 때마다 호출 시켜줘야하는 함수입니다.
  • 해당 함수가 호출되면, Letsee SDK Engine이 입력받은 한 Frame에 대한 연산을 수행하고 대기합니다.
Example
letsee.ready(() => {
    letsee.start();
    letsee.addTHREE(THREE).then(obj => { // 1. Three라이브러리를 param으로 삽입하고 결과로 3D를 그릴때 사용되는 renderer, camera, scene, update를 얻어옵니다.
        console.log(obj)
        renderer = obj.renderer; // WebGLRenderer
        scene = obj.scene; // Three.js Scene (Object3D)
        update = obj.update; // SDK 다음 Frame을 그리도록 호출하는 함수
        letsee.addTarget('toystory.json').then(entity => {
            toystory = entity; // 2. 마커에 대한 Entity 객체를 얻어옵니다.
            const geometry = new THREE.BoxGeometry();
            const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
            const cube = new THREE.Mesh( geometry, material );
            cube.scale.set(50, 50, 50);
            toystory.add(cube); // Entity에 cube mesh 삽입
            scene.add(toystory); // 3. mesh Object들을 담은 Entity 객체를 Three.js Scene에 추가합니다.

            const animate = async function() {
                requestAnimationFrame(animate);
                await update(); // 4. Letsee SDK에서 다음 Frame을 호출합니다.
                const camera = letsee.threeRenderer().getDeviceCamera(); // 5. Three.Camera를 가져옵니다.
                renderer.render(scene, camera); // 6. WebGLRenderer를 통해 scene을 렌더링합니다.
            };
            animate();
        });
    });
});
Parameters:
Name Type Description
threejs THREE

three.js 라이브러리. 아래와 같이 Script를 삽입하면 THREE가 global로 생성됨.

<script src="https://unpkg.com/three@0.121.1/build/three.min.js"></script>

Returns:
Type
Promise.<ThreeRendererEvent>

getEntityByUri(uri) → {Entity}

HTMLElement 혹은 DOM string을 이용하여 XRElement를 생성합니다. Entity를 인자로 받은 경우, XRElement를 Entity(마커)에 연결합니다.

Example
// test.json을 descriptor uri로 가지는 Entity를 조회
letsee.getEntityByUri('test.json');
Parameters:
Name Type Description
uri string

해당 uri를 갖는 Entity를 검색할때 사용하는 문자열

Returns:
  • Letsee의 Entity 객체
Type
Entity

createXRElement(htmlElement, entity) → {XRElement}

HTMLElement 혹은 DOM string을 이용하여 XRElement를 생성합니다. Entity를 인자로 받은 경우, XRElement를 Entity(마커)에 연결합니다.

Example
// 예제 1 : HTMLElement로 XRElement 생성
const divElement = document.createElement('div');
divElement.innerHTML = 'example';
const xrElement = letsee.createXRElement(divElement);

// 예제 2 : DOM String을 통해 XRElement 생성
const xrElement = letsee.createXRElement('<div>example</div>')

// 예제 3 : XRElement 생성 후, Entity로 binding
const entity = letsee.getEntityByUri('test.json');
letsee.createXRElement('<div>example</div>', entity);
Parameters:
Name Type Description
htmlElement HTMLElement | string

HTMLElement 또는 <div></div>와 같은 Dom 형식의 문자열

entity Entity

letsee의 Entity 객체

Returns:
  • 생성된 XRElement를 반환
Type
XRElement

bindXRElement(xrElement, entity) → {XRElement}

입력받은 XRElement를 Entity(마커)에 연결합니다.

Example
// XRElement 생성 후, Entity에 binding
const xrElement = letsee.createXRElement('<div>example</div>')
const entity = letsee.getEntityByUri('test.json');
bindXRElement(xrElement, entity)
Parameters:
Name Type Description
xrElement XRElement | Entity

HTMLElement 또는 <div></div>와 같은 Dom 형식의 문자열

entity Entity

letsee의 Entity 객체

Returns:
  • Entity에 연결된 XRElement를 반환
Type
XRElement

unbindXRElement(xrElement) → {XRElement}

입력받은 XRElement와 Entity(마커)의 연결을 끊습니다. THREE.js를 이용하여 AR컨텐츠를 만들 때, THREE 라이브러리를 연동하고, 결과로 letsee의 THREE.js에 대한 renderer, camera, scene, update을 얻어옵니다.

Example
// xrElement를 찾은 뒤, entity와의 연결을 unbind
const xrElementById = letsee.getXRElementById('id-selector'); // id 선택자를 통해 XRElement 조회
unbindXRElement(xrElement)
Parameters:
Name Type Description
xrElement XRElement

Letsee의 XRElement 객체

Returns:
  • Entity로부터 연결이 끊긴 XRElement를 반환
Type
XRElement

getXRElementById(id, entity) → {XRElement}

입력받은 id 선택자를 지닌 XRElement를 검색하여 반환합니다.

Example
// id 선택자를 통해, XRElement 조회
const xrElementById = letsee.getXRElementById('id-selector');
Parameters:
Name Type Description
id string

XRElement가 가지고 있는 HTMLElement 최상위 부모의 id 선택자

entity Entity

letsee의 Entity 객체

Returns:
  • id 선택자로 검색된 XRElement를 반환
Type
XRElement

getXRElementByClassName(className) → {Array.<XRElement>}

입력받은 class 선택자를 지닌 XRElement 배열을 검색하여 반환합니다.

Example
// class 선택자를 통해, XRElements 목록을 조회
const xrElementsByClass = [];
xrElementsByClass = letsee.getXRElementByClassName('class-selector');
Parameters:
Name Type Description
className string

XRElement가 가지고 있는 HTMLElement 최상위 부모의 className 선택자

Returns:
  • class 선택자로 검색된 XRElement 배열을 반환
Type
Array.<XRElement>

getAllXRElements(entity) → {Array.<XRElement>}

모든 XRElement들을 배열에 담아 반환합니다. 만약 Entity를 인자로 받은 경우 Entity에 연결된 XRElement들을 배열에 담아 반환합니다.

Example
// 예제 1 : 모든 XRElement 조회
const allXRElements = [];
allXRElements = letsee.getAllXRElements();

// 예제 2 : 인자로 전달한 Entity에 binding 되어 있는 XRElement 조회
const allXRElementsByEntity = [];
const entity = letsee.getEntityByUri('test.json');
const allXRElementsByEntity = getAllXRElements(entity);
Parameters:
Name Type Description
entity Entity | undefined

Letsee의 Entity 객체, 혹은 빈 값

Returns:
  • 모든 XRElement 배열을 반환
Type
Array.<XRElement>

removeXRElement(xrElement) → {XRElement}

입력받은 XRElement를 Entity와의 연결을 끊고 SDK의 XRElement 관리 목록에서 삭제합니다.

Example
// 예제 1 : id로 XRElement 조회 후, SDK의 XRElement 관리 목록에서 삭제
const xrElementById = letsee.getXRElementById('id-selector');
letsee.removeXRElement(xrElementById);

// 예제 2 : 모든 XRElement 조회 후, 반복문을 통해 SDK의 XRElement 관리 목록에서 삭제
const allXRElements = letsee.getAllXRElements();
allXRElements.forEach((xrElement) => {
    letsee.removeXRElement(xrElement);
})
Parameters:
Name Type Description
xrElement XRElement

Letsee의 XRElement 객체

Returns:
  • 삭제된 XRElement 를 반환
Type
XRElement

removeAllXRElements(entity) → {Array.<XRElement>}

모든 XRElement를 Entity와의 연결을 끊고 xrElement 관리 목록에서 삭제합니다. 인자로 Entity를 전달받은 경우 해당 Entity에 연결된 XRElement 들의 연결을 끊고 목록에서 삭제합니다.

Example
// 예제 1 : 모든 XRElement의 Entity와의 연결을 unbinding한 뒤, SDK의 XRElement 관리 목록에서 삭제
letsee.removeAllXRElements();

// 예제 2 : 인자로 입력받은 Entity에 연결된 XRElement의 연결을 unbinding한 뒤, SDK의 XRElement 관리 목록에서 삭제
const entity = letsee.getEntityByUri('test.json');
letsee.removeAllXRElements(entity);
Parameters:
Name Type Description
entity Entity | undefined

Letsee의 Entity 객체 혹은 빈 값

Returns:
  • 삭제된 XRElement 배열을 반환
Type
Array.<XRElement>