Skip to main content
Realsee
Dashboard
Sign out
Documentation
Docs
/
Five SDK

Getting Started

Set up Five SDK with the Vue Composition API and render your first Realsee 3D space.

Integrate Five SDK development on the Vue framework using the Composition API pattern. Full source examples: JavaScript | TypeScript

In this chapter you will learn

  • How to set up your development environment.
  • How to bring in the Five SDK.
  • How to display a 3D space on screen.

Preparation

Development environment

  • You need a modern browser.

Info

Five SDK browser support is listed below. Pick whichever one you are familiar with:

SafariSafari on iOSChromeChrome for AndroidEdgeFirefox
>= 9>= 9>= 49>= 93>= 13>= 45
  • Install Node.js ^20.19.0 or >=22.12.0, matching the Vite 8 engine requirement used by this guide.

Using a development build tool

This example uses Vite to initialize the development environment. You can initialize it yourself with the code below.

# npm 6.x
npm create vite@9.1.1 my-vue-app --template vue

# npm 7+, extra double-dash is needed:
npm create vite@9.1.1 my-vue-app -- --template vue

Under src, create the directory src/0.getting-started for this tutorial.

Each tutorial creates a new directory as a record, which makes it easier to summarize and look things up. When you finish the courses you will end up with

src
├── 0.getting-started
├── 1.displaying-work
├── 2.knowing-state
...

a directory structure like this. The full code samples use this same directory structure, so you can refer to them at any time.

Tip

If you are familiar with other build tools such as Webpack, Snowpack, or parcel, you can use them instead.

Create the HTML file

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="data:;base64,iVBORw0KGgo=" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Getting started</title>
    <!-- highlight-start -->
    <style>
      * {
        margin: 0;
        padding: 0;
      }
      html,
      body,
      #app {
        width: 100%;
        height: 100%;
        overflow: hidden;
      }
    </style>
    <!-- highlight-end -->
  </head>
  <body>
    <!-- highlight-start -->
    <div id="app"></div>
    <script type="module" src="./index"></script>
    <!-- highlight-end -->
  </body>
</html>

Directly importing with <script type="module" src="./index"></script> is a feature of Vite. If you use another build tool, handle the code import and entry file yourself — for example, with HtmlWebpackPlugin under Webpack.

Write the test logic

Let's first create a simple Hello World to make sure the whole setup runs end to end.

const app = document.querySelector("#app");
// highlight-start
app.innerHTML = "Hello World.";
// highlight-end
export {};

The trailing export {}; is needed because Vite imports with type="module", so every file must be a module and needs an export. If you use another build tool, write it according to that tool's requirements.

Start the dev server with npm run dev, then go to the current page at "http://localhost:3000/src/0.getting-started/index.html".

Info

Check your console: the port number may change depending on your configuration and which ports are currently in use, so rely on the console output. If you use another build tool, start the server according to that tool's requirements.

You will then see

Hello World.

printed on the page, which means the build tool is set up.

The following chapters will no longer describe the steps above in detail; just complete them as well.

Install the dependency package from npm

Install the dependencies in your project directory

npm install @realsee/five@6.8.9 three@0.117.1

The dependencies you need are

  • @realsee/five Five SDK
  • three three.js, the graphics/math library that Five SDK depends on. Use the exact 0.117.1 version.
  • vue the Vue framework. For now, use version 3.0.0 or above.

Test the Vue component

Create a new App.vue component

import { createApp, h } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");
<template>
  <div>{{ str }}</div>
  ˜
</template>

<script setup>
const str = "test";
</script>

Render a 3D space

It's time to render a VR scene and take a look.

Load the 3D space

Delete your earlier App.vue code. We'll rewrite it. You don't need to understand what the code below means yet — you'll learn that in the next chapter.

<template>
  <FiveProvider :work="work">
    <FiveCanvas :width="512" :height="512" />
  </FiveProvider>
</template>

<script setup>
import { FiveProvider, FiveCanvas } from "@realsee/five/vue";
import { parseWork } from "@realsee/five";
import { ref } from "vue";

const work = ref();
const workURL =
  "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

fetch(workURL)
  .then((response) => response.text())
  .then((text) => (work.value = parseWork(text)));
</script>

Go back to your browser and check whether a 3D space is already displayed in the top-left area. You can operate the view with your mouse or touch gestures — the basic browsing features are already included.

Make the view fill the whole screen

You may not fully understand how the code above works, but we can see that FiveCanvas has width and height attributes, which look a lot like the view's dimensions. Viewing it in the browser, the view sits in the top-left corner, which confirms the guess. That's right — they are used to set the view's dimensions.

So let's try to make it fill the screen using the Vue Composition API approach we're familiar with.

import { ref, onBeforeUnmount } from "vue";

function useWindowDimensions() {
  const width = ref(window.innerWidth);
  const height = ref(window.innerHeight);

  const listener = () => {
    width.value = window.innerWidth;
    height.value = window.innerHeight;
  };

  window.addEventListener("resize", listener, false);
  onBeforeUnmount(() => {
    window.removeEventListener("resize", listener, false);
  });
  return { width, height };
}
export { useWindowDimensions };
<template>
  <FiveProvider :work="work">
    // highlight-start
    <FiveCanvas :width="width" :height="height" />
    // highlight-end
  </FiveProvider>
</template>

<script setup>
import { FiveProvider, FiveCanvas } from "@realsee/five/vue";
import { parseWork } from "@realsee/five";
import { ref } from "vue";
// highlight-start
import { useWindowDimensions } from "./useWindowDimensions";
// highlight-end
const work = ref();
const workURL =
  "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

fetch(workURL)
  .then((response) => response.text())
  .then((text) => (work.value = parseWork(text)));
// highlight-start
const { width, height } = useWindowDimensions();
// highlight-end
</script>

Go back to your browser and see whether it matches your expectations.

Nicely done 🥳!

Organize and split the code

Our code-splitting logic

  • Split index to mount the App root component.
  • Split App into its own file, App.vue.
  • Split the useWindowDimensions function into its own file.

What you'll learn in the next chapter

What you'll learn in the next chapter

  • What a Work is.
  • How the code you just wrote — components such as FiveProvider / FiveCanvas — actually works.