View360
파노라마 360 이미지 뷰어
class View360 extends Component<View360Events>
Extends
Properties
View360의 현재 버젼 문자열
true일 경우, 캔버스의 크기가 변경되었을 때 자동으로 View360#resize를 호출합니다.
Autoplay 기능의 매니저 인스턴스.
이 인스턴스를 통해 autoplay 옵션을 변경하는 것도 가능합니다.
프로젝션 카메라.
파노라마 이미지/비디오를 렌더링할 canvas 엘리먼트의 CSS 선택자
캔버스 엘리먼트는 루트 엘리먼트 내부에 있어야합니다. 루트 엘리먼트의 직계 자식 엘리먼트(Direct child element)일 필요는 없습니다.
회전/줌 컨트롤러.
WebGL 디버깅을 활성화합니다. 이 값을 true로 할 경우 성능이 하락할 수 있습니다.
이 옵션은 View360을 개발하기 위해 내부적으로 사용됩니다.
마우스 우클릭시 표시되는 컨텍스트 메뉴를 비활성화합니다.
카메라의 수평 FOV(Field of View) 값. (도 단위, °)
자이로스코프를 통한 카메라 회전을 담당하는 컨트롤.
gyro 옵션 변경도 가능합니다.
핫스팟 렌더러 인스턴스.
hotspot 옵션 변경도 가능합니다.
카메라의 초기 pitch(x축 회전)값 (도 단위, °)
View360은 오른손 좌표계를 사용하기 때문에, 양(+)의 값은 카메라가 위를 보게 하고, 음(-)의 값은 카메라가 아래를 보게 합니다.
카메라의 초기 yaw(y축 회전)값 (도 단위, °)
View360은 오른손 좌표계를 사용하기 때문에, 카메라가 해당 값만큼 시계 반대방향으로 회전합니다.
카메라의 초기 줌 값.
이 값을 2로 설정할 경우 파노라마 이미지를 가로 기준 200%만큼 확대합니다.
init()이 호출되었는지 여부를 가리키는 값
프레임간 시간 차이의 최대값. (초 단위)
퍼포먼스 등의 이유로 프레임 렌더링이 늦어졌을 때, 화면이 갑작스럽게 바뀌는 것을 막아줍니다.
렌더링할 triangle mesh의 인스턴스
pitch(x축 회전) 범위를 제한합니다. (도 단위, °)
추가된 플러그인의 배열
현재 사용중인 Projection의 인스턴스. 프로젝션을 활성화하지 않았을 경우 null입니다.
파노라마 이미지 소스나 프로젝션 타입을 변경하려면 View360#load를 호출하면 됩니다.
프로젝션 렌더러.
루트 엘리먼트 (.view360-container)
카메라 회전을 담당하는 컨트롤.
rotate 옵션 변경도 가능합니다.
true로 설정할 경우, 모바일(터치) 환경의 캔버스 영역 내에서 스크롤을 가능하게 합니다.
이 값을 활성화할 경우, 사용자가 카메라 뷰를 위/아래로 바꾸기 위해서는 먼저 가로로 스와이프한 이후에 세로로 스와이프해야만 합니다.
캔버스 엘리먼트에 적용할 tabindex 어트리뷰트의 값.
이 값을 설정해야만 키보드 컨트롤을 사용 가능합니다.
기본값으로 0이 설정됩니다. null로 지정하면 tabindex를 설정하지 않습니다.
마우스 사용시 CSS cursor값을 자동으로 변경할지 여부.
true일 경우 기본 상태에서 cursor: "grab"을, 입력 도중에 cursor: "grabbing"을 캔버스에 적용합니다.
true일 때 autoResize가 활성화되었으면, 사용 가능한 환경에서 ResizeObserver API를 사용해서 캔버스 크기 변화를 추적합니다.
WebXR 기반의 VR 기능 매니저 인스턴스.
true로 설정할 경우, 캔버스 영역 내에서 마우스 휠을 이용한 페이지 스크롤이 가능해집니다.
이 값을 활성화할 경우, 마우스 휠을 통한 줌이 불가능하게 됩니다.
yaw(y축 회전) 범위를 제한합니다. (도 단위, °)
카메라 줌을 담당하는 컨트롤.
zoom 옵션 변경도 가능합니다.
카메라 줌 범위를 제한합니다.
null일 경우 기본값으로 0.6에서 10의 범위를 사용합니다.
Methods
새로운 플러그인을 추가합니다.
인스턴스를 제거하고 모든 리소스를 해제합니다.
내부 컴포넌트들을 초기화하고 프로젝션 소스를 로드합니다.
플러그인을 제거합니다.
파노라마 이미지/비디오의 한 프레임을 렌더링합니다.
프레임 갱신은 보통 필요한 때에만 자동적으로 이루어지기 때문에, 보통은 이 메소드를 호출할 필요는 없습니다.
옵션 변경 이후에도 프레임 갱신이 이루어지지 않는다면, 이 메소드를 호출해주세요.
View360이 내부적으로 캐시하고 있는 엘리먼트 크기를 현재 크기로 갱신합니다.
Events
새로운 프레임 렌더 직전에 발생하는 이벤트
사용자 입력이 끝날 때 발생하는 이벤트.
사용자 입력 시작 시점에 발생하는 이벤트.
콘텐츠가 로드된 직후 발생하는 이벤트.
콘텐츠 로드를 시작하기 전에 발생하는 이벤트.
프로젝션이 변경되었을 때 발생하는 이벤트
새로운 프레임 렌더 직후에 발생하는 이벤트
View360#resize가 호출되었을 때 발생하는 이벤트
캔버스 엘리먼트를 드래그하지 않고 클릭했을 때 발생하는 이벤트.
VR 세션이 끝난 이후에 발생하는 이벤트
VR 세션에 진입한 직후에 발생하는 이벤트
카메라가 보는 방향이 변경되었을 때 발생하는 이벤트.
이 이벤트는 프레임이 렌더링되었을때만 발생합니다.
즉, 프레임 렌더 사이에 실제 카메라 방향이 여러번 변경되더라도 실제 이벤트는 화면 갱신이 이루어지는 시점에 바라보는 값으로만 트리거됩니다.
Constructor
new View360(root: string | HTMLElement, options: Partial<View360Options>): View360
Parameters
string | HTMLElement
View360을 마운트할 루트 엘리먼트, CSS 셀렉터나 HTMLElement를 지정 가능합니다.
적용할 옵션들
import View360, { EquirectProjection } from "@egjs/view360";
// Create new View360 instance
const viewer = new View360("#id-of-a-container", {
projection: new EquirectProjection({
src: "URL_TO_PANORAMA_IMAGE_OR_VIDEO",
})
});
Properties
VERSION
VERSION"#VERSION#"
View360의 현재 버젼 문자열
// If the installed version of the View360 is v4.0.0, View360.VERSION is equal to "4.0.0"
console.log(View360.VERSION) // 4.0.0
autoInit
autoInitboolean
true
이 값이 true이고, projection이 설정되었으면, 인스턴스 생성 시점에 자동으로 init()을 호출합니다.
import View360, { EquirectProjection, EVENTS } from "@egjs/view360";
// viewer.init() is called on instance creation
// But as `init` is asynchronous, you should wait for "ready" event if you want to do something after initialization.
const viewer = new View360("#el_id", {
autoInit: true,
projection: new EquirectProjection({ src: "SRC_TO_URL" })
});
console.log(viewer.initialized); // false, as `init` is asynchronous
viewer.once(EVENTS.READY, () => {
console.log(viewer.initialized); // true
});
autoResize
autoResizeboolean
true
true일 경우, 캔버스의 크기가 변경되었을 때 자동으로 View360#resize를 호출합니다.
const viewer = new View360("#el_id", {
autoResize: true
});
// This can trigger `viewer.resize()` if the canvas size was not 400px
const canvas = viewer.renderer.canvas;
canvas.style.width = "400px";
autoplay
autoplay
Autoplay 기능의 매니저 인스턴스.
이 인스턴스를 통해 autoplay 옵션을 변경하는 것도 가능합니다.
// Disable autoplay
viewer.autoplay.disable();
camera
canvasSelector
canvasSelectorstring
"canvas"
파노라마 이미지/비디오를 렌더링할 canvas 엘리먼트의 CSS 선택자
캔버스 엘리먼트는 루트 엘리먼트 내부에 있어야합니다. 루트 엘리먼트의 직계 자식 엘리먼트(Direct child element)일 필요는 없습니다.
<div class="view360-container">
<canvas id="not_this_one"></canvas>
<!-- This will be selected -->
<canvas id="canvas_to_select"></canvas>
</div>
const viewer = new View360("#el_id", {
canvasSelector: "#canvas_to_select"
});
control
control
회전/줌 컨트롤러.
debug
debugboolean
false
WebGL 디버깅을 활성화합니다. 이 값을 true로 할 경우 성능이 하락할 수 있습니다.
이 옵션은 View360을 개발하기 위해 내부적으로 사용됩니다.
disableContextMenu
disableContextMenuboolean
false
마우스 우클릭시 표시되는 컨텍스트 메뉴를 비활성화합니다.
fov
fovnumber
90
카메라의 수평 FOV(Field of View) 값. (도 단위, °)
// Init with fov: 120
const viewer = new View360("#el_id", { fov: 120 });
// Back to 90
viewer.fov = 90;
gyro
gyro
자이로스코프를 통한 카메라 회전을 담당하는 컨트롤.
gyro 옵션 변경도 가능합니다.
hotspot
hotspot
핫스팟 렌더러 인스턴스.
hotspot 옵션 변경도 가능합니다.
initialPitch
initialPitchnumber
0
카메라의 초기 pitch(x축 회전)값 (도 단위, °)
View360은 오른손 좌표계를 사용하기 때문에, 양(+)의 값은 카메라가 위를 보게 하고, 음(-)의 값은 카메라가 아래를 보게 합니다.
const viewer = new View360("#el_id", {
initialPitch: 60
});
viewer.on("ready", () => {
console.log(viewer.camera.pitch); // 60
});
initialYaw
initialYawnumber
0
카메라의 초기 yaw(y축 회전)값 (도 단위, °)
View360은 오른손 좌표계를 사용하기 때문에, 카메라가 해당 값만큼 시계 반대방향으로 회전합니다.
const viewer = new View360("#el_id", {
initialYaw: 30
});
viewer.on("ready", () => {
console.log(viewer.camera.yaw); // 30
});
initialZoom
initialZoomnumber
1
카메라의 초기 줌 값.
이 값을 2로 설정할 경우 파노라마 이미지를 가로 기준 200%만큼 확대합니다.
const viewer = new View360("#el_id", {
initialZoom: 2
});
viewer.on("ready", () => {
console.log(viewer.camera.zoom); // 2
});
initialized
initializedboolean
init()이 호출되었는지 여부를 가리키는 값
const viewer = new View360("#el", { autoInit: false });
console.log(viewer.initialized); // false
await viewer.init();
console.log(viewer.initialized); // true
maxDeltaTime
maxDeltaTimenumber
1 / 30
프레임간 시간 차이의 최대값. (초 단위)
퍼포먼스 등의 이유로 프레임 렌더링이 늦어졌을 때, 화면이 갑작스럽게 바뀌는 것을 막아줍니다.
mesh
meshnull | TriangleMesh<CommonProjectionUniforms>
렌더링할 triangle mesh의 인스턴스
pitchRange
pitchRangenull | Range
null
pitch(x축 회전) 범위를 제한합니다. (도 단위, °)
const viewer = new View360("#el_id", {
pitchRange: [-45, 45]
});
viewer.on("ready", () => {
console.log(viewer.camera.pitch); // 0
viewer.camera.lookAt({ pitch: 60 });
console.log(viewer.camera.pitch); // 45
});
plugins
plugins
추가된 플러그인의 배열
const viewer = new View360("#el_id", {
plugins: [new ControlBar()]
});
console.log(viewer.plugins); // [ControlBar]
viewer.addPlugins(new LoadingSpinner()) // [ControlBar, LoadingSpinner];
projection
projectionnull | Projection
현재 사용중인 Projection의 인스턴스. 프로젝션을 활성화하지 않았을 경우 null입니다.
파노라마 이미지 소스나 프로젝션 타입을 변경하려면 View360#load를 호출하면 됩니다.
const viewer = new View360
renderer
renderer
프로젝션 렌더러.
rootEl
rootElHTMLElement
루트 엘리먼트 (.view360-container)
<div id="viewer" class="view360-container">
<canvas class="view360-canvas"></canvas>
</div>
import View360 from "@egjs/view360";
const viewer = new View360("#viewer");
console.log(viewer.rootEl); // Element with id "viewer"
rotate
rotate
카메라 회전을 담당하는 컨트롤.
rotate 옵션 변경도 가능합니다.
scrollable
scrollableboolean
true
true로 설정할 경우, 모바일(터치) 환경의 캔버스 영역 내에서 스크롤을 가능하게 합니다.
이 값을 활성화할 경우, 사용자가 카메라 뷰를 위/아래로 바꾸기 위해서는 먼저 가로로 스와이프한 이후에 세로로 스와이프해야만 합니다.
tabIndex
tabIndexnull | number
0
캔버스 엘리먼트에 적용할 tabindex 어트리뷰트의 값.
이 값을 설정해야만 키보드 컨트롤을 사용 가능합니다.
기본값으로 0이 설정됩니다. null로 지정하면 tabindex를 설정하지 않습니다.
const viewer = new View360("#el_id", {
tabindex: 5
});
<!-- After init -->
<div class="view360-container">
<canvas class="view360-canvas" tabindex="5"></canvas>
</div>
useGrabCursor
useGrabCursorboolean
true
마우스 사용시 CSS cursor값을 자동으로 변경할지 여부.
true일 경우 기본 상태에서 cursor: "grab"을, 입력 도중에 cursor: "grabbing"을 캔버스에 적용합니다.
useResizeObserver
useResizeObserverboolean
true
true일 때 autoResize가 활성화되었으면, 사용 가능한 환경에서 ResizeObserver API를 사용해서 캔버스 크기 변화를 추적합니다.
vr
vr
WebXR 기반의 VR 기능 매니저 인스턴스.
// Example: Enter VR
// This must be called on user interaction, else will be rejected.
viewer.vr.enter();
wheelScrollable
wheelScrollableboolean
false
true로 설정할 경우, 캔버스 영역 내에서 마우스 휠을 이용한 페이지 스크롤이 가능해집니다.
이 값을 활성화할 경우, 마우스 휠을 통한 줌이 불가능하게 됩니다.
yawRange
yawRangenull | Range
yaw(y축 회전) 범위를 제한합니다. (도 단위, °)
const viewer = new View360("#el_id", {
yawRange: [-30, 30]
});
viewer.on("ready", () => {
console.log(viewer.camera.yaw); // 0
viewer.camera.lookAt({ yaw: 60 });
console.log(viewer.camera.yaw); // 30
});
zoom
zoom
카메라 줌을 담당하는 컨트롤.
zoom 옵션 변경도 가능합니다.
zoomRange
zoomRangenull | Range
null
카메라 줌 범위를 제한합니다.
null일 경우 기본값으로 0.6에서 10의 범위를 사용합니다.
const viewer = new View360("#el_id", {
zoomRange: [0.5, 4]
});
viewer.on("ready", () => {
console.log(viewer.camera.zoom); // 1
viewer.camera.lookAt({ zoom: 6 });
console.log(viewer.camera.zoom); // 4
});
Methods
addPlugins
addPluginsvoid
addPlugins(...plugins: View360Plugin[]): void
새로운 플러그인을 추가합니다.
Parameters
추가할 플러그인들
// Add a single plugin
viewer.addPlugins(new ControlBar());
// Add multiple plugins
viewer.addPlugins(new ControlBar(), new LoadingSpinner());
destroy
destroyvoid
destroy(): void
인스턴스를 제거하고 모든 리소스를 해제합니다.
hasOn
hasOnboolean
hasOn<K>(eventName: K): boolean
Parameters
K
init
initPromise<void>
init(): Promise<void>
내부 컴포넌트들을 초기화하고 프로젝션 소스를 로드합니다.
load
loadPromise<boolean>
load(projection: Projection): Promise<boolean>
새로운 파노라마 이미지 혹은 비디오를 로드하고 표시합니다.
만약 View360이 아직 초기화되지 않았다면, init()을 호출합니다.
Parameters
새로운 파노라마 이미지/비디오에 적용할 옵션들
Returns
프로젝션 로드에 성공했을 경우 Promise<true>를 반환합니다.
// Change to video
viewer.load({
src: "URL_TO_NEW_VIDEO",
video: true
});
off
off
off<K>(eventName: K, handlerToDetach: EventCallback<View360Events, K, View360>): View360
Parameters
K
EventCallback<View360Events, K, View360>
on
on
on(eventHash: Partial<{ beforeRender: ((event: BeforeRenderEvent) => any); inputEnd: ((event: InputEndEvent) => any); inputStart: ((event: InputStartEvent) => any); load: ((event: LoadEvent) => any); loadStart: ((event: LoadStartEvent) => any); projectionChange: ((event: ProjectionChangeEvent) => any); ready: ((event: ReadyEvent) => any); render: ((event: RenderEvent) => any); resize: ((event: ResizeEvent) => any); staticClick: ((event: StaticClickEvent) => any); viewChange: ((event: ViewChangeEvent) => any); vrEnd: ((event: VREndEvent) => any); vrStart: ((event: VRStartEvent) => any) }>): View360
Parameters
Partial<{ beforeRender: ((event: BeforeRenderEvent) => any); inputEnd: ((event: InputEndEvent) => any); inputStart: ((event: InputStartEvent) => any); load: ((event: LoadEvent) => any); loadStart: ((event: LoadStartEvent) => any); projectionChange: ((event: ProjectionChangeEvent) => any); ready: ((event: ReadyEvent) => any); render: ((event: RenderEvent) => any); resize: ((event: ResizeEvent) => any); staticClick: ((event: StaticClickEvent) => any); viewChange: ((event: ViewChangeEvent) => any); vrEnd: ((event: VREndEvent) => any); vrStart: ((event: VRStartEvent) => any) }>
once
once
once(eventHash: Partial<{ beforeRender: ((event: BeforeRenderEvent) => any); inputEnd: ((event: InputEndEvent) => any); inputStart: ((event: InputStartEvent) => any); load: ((event: LoadEvent) => any); loadStart: ((event: LoadStartEvent) => any); projectionChange: ((event: ProjectionChangeEvent) => any); ready: ((event: ReadyEvent) => any); render: ((event: RenderEvent) => any); resize: ((event: ResizeEvent) => any); staticClick: ((event: StaticClickEvent) => any); viewChange: ((event: ViewChangeEvent) => any); vrEnd: ((event: VREndEvent) => any); vrStart: ((event: VRStartEvent) => any) }>): View360
Parameters
Partial<{ beforeRender: ((event: BeforeRenderEvent) => any); inputEnd: ((event: InputEndEvent) => any); inputStart: ((event: InputStartEvent) => any); load: ((event: LoadEvent) => any); loadStart: ((event: LoadStartEvent) => any); projectionChange: ((event: ProjectionChangeEvent) => any); ready: ((event: ReadyEvent) => any); render: ((event: RenderEvent) => any); resize: ((event: ResizeEvent) => any); staticClick: ((event: StaticClickEvent) => any); viewChange: ((event: ViewChangeEvent) => any); vrEnd: ((event: VREndEvent) => any); vrStart: ((event: VRStartEvent) => any) }>
removePlugins
removePluginsvoid
removePlugins(...plugins: View360Plugin[]): void
플러그인을 제거합니다.
Parameters
제거할 플러그인들
// Remove a single plugin
viewer.removePlugins(plugin1);
// Remove multiple plugins
viewer.removePlugins(plugin2, plugin3);
renderFrame
renderFramevoid
renderFrame(delta: number): void
파노라마 이미지/비디오의 한 프레임을 렌더링합니다.
프레임 갱신은 보통 필요한 때에만 자동적으로 이루어지기 때문에, 보통은 이 메소드를 호출할 필요는 없습니다.
옵션 변경 이후에도 프레임 갱신이 이루어지지 않는다면, 이 메소드를 호출해주세요.
Parameters
number
프레임간 시간 차이, 밀리초 단위
resize
resizevoid
resize(): void
View360이 내부적으로 캐시하고 있는 엘리먼트 크기를 현재 크기로 갱신합니다.
trigger
trigger
trigger<K>(event: K, ...params: EventTriggerParams<View360Events, K>): View360
Parameters
K
EventTriggerParams<View360Events, K>
Events
beforeRender
inputEnd
inputStart
load
loadStart
projectionChange
ready
render
resize
staticClick
vrEnd
vrStart
viewChange
viewChange
카메라가 보는 방향이 변경되었을 때 발생하는 이벤트.
이 이벤트는 프레임이 렌더링되었을때만 발생합니다.
즉, 프레임 렌더 사이에 실제 카메라 방향이 여러번 변경되더라도 실제 이벤트는 화면 갱신이 이루어지는 시점에 바라보는 값으로만 트리거됩니다.