atwintest v1.0.24

Architwin Library

ArchiTwin Library

Table of Contents

• Architwin Library
  • Table of Contents
  • Installation
    • Install Using NPM
  • Getting Started
    • Define an iFrame as target for the Showcase
    • Import the library
    • Connect to a Space
  • Connection Parameters
  • Config Options
  • Space Navigation and Camera Control
    • Moving Around
    • Rotate, Pan and Tilt Camera
  • Space Overview
  • Points of Interest
  • Function Reference
    • Tags
    • Sweeps
    • Video
    • Navigation
    • Camera
    • Objects

Installation

Install Using NPM

To install the latest ArchiTwin package:

npm i architwin

Getting Started

Define an iFrame as target for the Showcase

This example uses Vue's ref attribute to reference the target iFrame. Please consult the official documentation of your preferred framework of choice on how to do reference a target component.

<template>
    <div>
      <iframe
        id="mp-showcase"
        ref="mpIframe"
        frameborder=”0”
        allow="xr-spatial-tracking"
        allowfullscreen>
      </iframe>
    </div>

</template>

Import the library

<script lang="ts">
import atwin from 'architwin';
import type { IMPConfig, IUser } from 'architwin';
import { onMounted, ref } from 'vue';

const mpIframe = ref<HTMLIFrameElement>()

// replace with your api key and user
const apiKey = "585876be-339f-4e52-a6a0-0bc816ccb95a"
const authUser = {
  email: "su@email.com",
  password: "su123"
} as IUser

....
</script>

Connect to a Space

<script lang="ts">

  ...
  onMounted( async() => {

  // set spaceUrl
  const spaceUrl = "https://basic-dev.rev-kitten.com/showcase/model3d_public/1?token=e707880f-0fc5-48a6-b3f6-643a19f81464";

  const auth = {
    apiKey: apiKey,
    user: authUser
  }

  const config: IMPConfig = {
    iframeId: 'mp-showcase',
    play: 1,
  }

  // more config options as explain later
  await atwin.connectSpace(spaceUrl, auth, config)
  
  // after connected to space, the following objects should be available
  // tags - an array of tag objects found in the space
  // sweeps - an array of sweep objects found in the space
  ...

})

</script>

Once connected, the interactive Space will be rendered in the target iFrame.
A Space generally contains Tags, 3D objects, Video Screens , Slideshow Screens and Sweeps.
You should be able to move around the Space using keyboard and mouse.

Or programmatically using methods defined in this library.

Connection Parameters

connectSpace has three important parameters:

connectSpace(spaceUrl, auth, config)

spaceUrl - the URL of the space you wanted to connect. auth - an authentication object with apiKey and user credentials. This will be provided by ArchiTwin. config - a config object to set some default space behavior

Example:

import atwin from 'architwin'

// public URL for the space, you will be provided an API Endpoint for the list of public spaces
const spaceUrl = "https://basic-dev.rev-kitten.com/showcase/model3d_public/1?token=e707880f-0fc5-48a6-b3f6-643a19f81464"

const auth = {
    apiKey: "585876be-339f-4e52-a6a0-0bc816ccb95a", //xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    user: {
        email: 'su@email.com',
        password: 'su123'
    }
}

const config = {
    iframeId: "mp-showcase", // this is required
    // ... other config options. 
}

await atwin.connectSpace(url, auth, config)

Config Options

export interface IMPConfig{
    iframeId: string,
    play?: 0 | 1,
    qs?: 0 | 1,
    tour?: 0 | 1 | 2 | 3,
    vr?: 0 | 1,
}

iframeId: string, play?: 0 | 1, default = 0

• 0 Shows a Play button ▶️️ on the iframe. The user must press the Play button ▶️️ to open the Matterport model.
• 1 Automatically opens the Matterport model when the iframe loads on the page. If the 3D Showcase is opened via a link (not embedded in an iframe), this option is chosen automatically. When embedding Showcase within an iframe, play=1 will only work if the iframe is large enough on the user’s screen to provide a good user experience. Specifically, on mobile devices, the iframe has to cover at least 60% of the screen.

qs?: 0 | 1, default = 0

• 0 Disable Quickstart (when the Matterport model first opens, zoom in from Dollhouse View).
• 1 Enable Quickstart (when the Matterport model first opens, go straight into Inside View). Learn more. Only works if Start Position is Inside View.

tour?: 0 | 1 | 2 | 3, default = 1

• 0 No tour controls or highlight reel appear.
• 1 The tour mode saved in the model is used.
• 2 Story mode tour is used.
• 3 Highlight reel mode tour is used.

vr?: 0 | 1, default = 1

• 0 Hide the VR button.
• 1 Default Show the VR button.

Space Navigation and Camera Control

Moving Around

You can navigate around the space using keyboard arrow keys or using a mouse.

Progmmatically, you also can navigate the space:

Use moveInDirection(direction: string) to move around inside the space. direction: "FORWARD", "BACKWARD", "LEFT", "RIGHT", "UP", "DOWN".

This will move the user to the nearest Sweep marker in the indicated direction.

<script lang="ts">
  import atwin from 'architwin';
  import type { IMPConfig, IUser } from 'types';
  import { onMounted, ref } from 'vue';

  ...
  atwin.moveInDirection("FORWARD")
  atwin.moveInDirection("FORWARD")

  atwin.moveInDirection("RIGHT")
  atwin.moveInDirection("RIGHT")
  atwin.moveInDirection("FORWARD")
  atwin.moveInDirection("LEFT")
  ...

</script>

Rotate, Pan and Tilt Camera

While inside the space, you can control the camera rotation and panning to have a better view around you.

Use cameraRotate(x: number, y: number, speed: number) to rotate the camera view.

Use cameraPan(x: number, z: number) to tilt and pan the Camera.

Parameters x, y and z are rotations in degrees.

Note, cameraPan will work only in Dollhouse mode.

<script lang="ts">
  import atwin from 'architwin';
  import type { IMPConfig, IUser } from 'types';
  import { onMounted, ref } from 'vue';

  ...
  // rotate around X axis, last parameter is the Speed of rotation in seconds
  atwin.cameraRotate(20,0,2)


  // rotate around Y axis
  atwin.cameraRotate(0,45,5)



  // pan around z axis (pan and tilt only works in Dollhouse mode)
  atwin.cameraPan(0,20)

  // tilt abpout x axis
  atwin.cameraPan(30,0)

  ...

</script>

Space Overview

(Note that we use the word Space and Showcase interchangeably)

Space Space is an immersive and realistic Digital Twin model of a physical space, with virtual custom objects like animated 3D objects, Video Screens, Slideshow Screens and Tags, co-existing and enhancing the real objects.

A user should be able to navigate around using PC or devices (keyboard and mouse), measure real object dimensions and interact with the virtual objects as if you are actually visiting the physical space.

Sweeps Space have static sweep markers (white circles on floor) which serves as primary navigation points. Users can go to sweeps (or click), stand and look around.

Tags Space also have tags which are virtual markers attached to Objects or Locations in space. Tags can be clicked which will render and display relevant contents like web pages, videos, images or text descriptions. It is possible to go directly to any specifig tag (gotoTag) from anywhere in Space.

It can be used as quick way to navigate around the space.

3D Objects Space usually contains 3D objects or three-dimentional models. Some 3D objects may have some simple animations.

Video Screens Another interesting objects that can be found inside the space are Video Screens. They practially look like TV screens placed at selected locations. The Video screens will automatically play when a User is nearby (2 meters). And automatically turns off when the User leaves.

Slideshow Screens Space can also contain Image Slideshow Screens. This is similar to the Video Screen, but uses static images. Clicking on the right section of the current slide image will display the next slide. Clicking on the the left section will display the previous slide.

The slideshow can be auto played in whole by clicking the lower-right corner.

Points of Interest

Tags are primarily use to mark locations or objects in space for quick and direct navigation. Tags usually contain additional content that will be rendered when hovered. Contents can be web pages, text descriptions, videos, or images.

getTags() - // returns a list of Tags found in the Space

goToTag(tagId) - // to navigate to specific Tag and accepts a Tag's ID

getSweeps() - // returns a list of Sweeps found in the Space

moveToSweep(sweepId) - // to move to a specific Sweep

Example:

<script lang="ts">
  import atwin from 'architwin';
  import type { IMPConfig, IUser } from 'types';
  import { onMounted, ref } from 'vue';

  ...
  // get current sweep data
  atwin.getCurrentSweep()


  // get current sweep position
  atwin.getSweepPosition()


  // moving to a Sweep
  atwin.moveToSweep('msdfkj353h')

  // move to a Tag
  atwin.gotoTag(5)

  ...

</script>

Function Reference

Tags

getTags() - // returns an array of tag objects found in the Space

gotoTag(tagId: number) - //transport navigate directly to the tag with given ID

Sweeps

getSweeps() - // returns an array of Sweep Collection found in the Space

moveToSweep(sweepId: string) - // transport navigate directly to the Sweep with given ID. 

getNearbySweeps(sweepId: string) - // returns the nearby or neighbors of a given sweep. 

getCurrentSweep() - // returns the current sweep detail

getSweepPosition(): {x: number, y: number, z: number} - // returns the position of the current sweep:

Example:

<script lang="ts">
  import atwin from 'architwin';
  import type { IMPConfig, IUser } from 'types';
  import { onMounted, ref } from 'vue';

  ...
  // get all Sweeps in loaded Space
  atwin.getSweeps()
  
  
  // get current sweep data
  atwin.getCurrentSweep()


  // get current sweep position
  atwin.getSweepPosition()


  // moving to a Sweep
  atwin.moveToSweep('mfj45ligf')


  // get nearby sweeps from current Sweep
  atwin.getNearbySweeps('mfj45ligf')

  ...

</script>

Video

playVideo(videoId: number) - // play a video screen

pauseVideo(videoId: number) - // pause a video screen

Example:

<script lang="ts">
  import atwin from 'architwin';
  import type { IMPConfig, IUser } from 'types';
  import { onMounted, ref } from 'vue';

  ...
  // play a video
  atwin.playVideo(1)


  // pause a video
  atwin.pauseVideo(2)
  ...
</script>

Navigation

cameraLookAt(x: number,y: number) - // set camera view at coordinate in SCREEN. 
                                    // x and y is in pixel valuews from top left corner of the space canvas
moveInDirection(direction: string) - // move in DIRECTION, can be LEFT, RIGTH, UP, DOWN, FORWARD, BACKWARD

getViewMode() - // returns the current View Mode of the space.
                // there are three modes:
                // "mode.inside" - shows the interior view of the space
                // "mode.floorplan" - shows the floor plan of the space
                // "mode.dollhouse" - shows the doll house view

setViewMode(mode: string) - // to set the viewing mode to "INSIDE", "FLOORPLAN" or "DOLLHOUSE"

Camera

getCurrentCameraPose() - // returns the current camera Pose object

getCameraPosition() - // returns the current camera Position {x,y,z}

cameraPan(x: number, z: number) -   // pan (z-axis) makes the camera look left and right.  tilt (x-axis) the camera look up and down. 
                                    // x and z are angles in degrees

cameraRotate(x: number, y: number, speed: number) - // rotates the camera view, x and y is rotation in horizontal
                                                    // and vertical rotation in degrees

Example:

<script lang="ts">
  import atwin from 'architwin';
  import type { IMPConfig, IUser } from 'types';
  import { onMounted, ref } from 'vue';

  ...

  // get current Camera Pose
  atwin.getCurrentCameraPose()


  // get current camera position
  atwin.getCameraPosition()


  // set Camera View
  atwin.cameraLookAt(0, 10)


  // move in different Directions
  atwin.moveInDirection("FORWARD")
  atwin.moveInDirection("FORWARD")


  // pan around z axis (pan and tilt only works in Dollhouse mode)
  atwin.cameraPan(0,20)


  // tilt abpout x axis
  atwin.cameraPan(30,0)


  // rotate around X axis, last parameter is the Speed of rotation in seconds
  atwin.cameraRotate(20,0,2)


  // rotate around Y axis
  atwin.cameraRotate(20,5,2)

  
  // get current View
  atwin.getViewMode()

  // set View Mode
  atwin.setViewMode("INSIDE")
  atwin.setViewMode("FLOORPLAN")
  atwin.setViewMode("DOLLHOUSE")
  ...

</script>

Objects

getNearbyObjects(type?: '3DX' | 'SLIDESHOW' | 'VIDEO', distance?: number = 2)
    // returns a list of nearby objects
    // type - can be 3Dx, Slideshow or Video; parameter is optional. if no parameter is passed, it returns all objects
    // distance - is optional but with a default of 2 meters

Example

<script lang="ts">
  import atwin from 'architwin';
  import type { IMPConfig, IUser } from 'types';
  import { onMounted, ref } from 'vue';

  ...

  // get all nearby objects
  atwin.getNearbyObjects()

  // get all nearby 3dx objects
  atwin.getNearbyObjects('3DX')

  // get all slideshow objects
  atwin.getNearbyObjects('SLIDESHOW')

  // get all video screen objects
  atwin.getNearbyObjects('VIDEO')

  // get all video screen objects with distance
  atwin.getNearbyObjects('3DX', 3)
  ...

</script>