ArchiTwin Library
-
Architwin Library
- Table of Contents
- Installation
- Getting Started
- Executing methods on specific App Phases
- Space Overview
- Subscribing to Space Events
-
Points of Interest
- Adding, removing and customizing Tags
- Accessing List of Rendered Objects and Object Structure
- Transforming Objects
- Undoing and Redoing Transformation Changes
- Adding Objects To Your Space
- Creating a Customizable Media Screen
- Setting Video Playback in the Space
- Setting Animation Control in the Space
- Copying object To Your Space
- Navigate to Object
- Deleting Object To Your Space
- Replacing Object To Your Space
- Creating Text Markup Screen in the space
- Typescript Interface Reference
- Meeting UI Guide
-
Function Reference
- Space
- Tags
- Sweeps
- Video
- Navigation
- Camera
-
Objects
- getNearbyObjects()
- addMediaScreen()
- setTransformMode()
- revertTransform()
- removeTransformControls()
- setAnimationState()
- showObjectDimensions()
- copyObject()
- deleteObject()
- deleteObjectFromSpace()
- replaceObject()
- addTextMarkupScreen()
- setTextMarkupScreenContent()
- getNearestSweepFromObject()
- setSelectedObject()
- getSelectedObject()
- clearSelectedObject()
- goToModel()
- get3DXObjects()
- setLibrary()
- getLibrary()
- disposeModel()
-
Virtual Meeting
- createMeeting()
- joinMeeting()
- leaveMeeting()
- startVideo()
- stopVideo()
- startLocalVideo()
- stopLocalVideo()
- startAudio()
- stopAudio()
- muteAudio()
- unMuteAudio()
- muteLocalAudio()
- unMuteLocalAudio()
- getDevices()
- switchMicrophone()
- switchSpeaker()
- switchCamera()
- getMicList()
- getSpeakerList()
- getCameraList()
- createLocalVideoTrack()
- createLocalAudioTrack()
- initializeHTMLElements()
To install the latest ArchiTwin package:
npm i architwin
Before you start coding your architwin powered app, there are a few things you need to have ready to ensure that you are able to run the app properly without interruptions. For a seamless development experience, make sure to have the following ready:
- appKey: your appKey is used to authenticate your connection when loading the 3D showcase. For security purposes, the appKey can only be used by a domain (e.g. awesomesite.com) it is associated with. This key is important especially when you launch your app in production and utilize your own site domain. Please contact us to request your appKey
- apiKey: not to be confused with the appKey, the apiKey is used to authenticate all API requests sent to our servers including user authentication and fetching object data connected to a showcase. Please contact us to request your apiKey
-
apiURL: an optional key in the auth object which if set, will point all internal API calls to the api endpoint or base URL you assign. If this is not set, all api calls will be directed to the proxy address set in the
vite.config.ts
file during local development. Example:apiURL: "apps.awesomesite.com/api"
will resolve internally toapps.awesomesite.com/api/cas/tickets?someparams
orapps.awesomesite.com/api/v1/showcase/id/1
. It is important to add/api
to the base url of your custom apiURL to ensure the api requests are properly sent. There is no need to add a forward slash at the end of our custom apiURL. Please take note that you may have to setup a proxy server to bypass CORS issues when you deploy your application on your production servers - Username and password: User credentials used to authenticate the user. Please contact us to request your username and password
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 reference a target component.
<template>
<div class="at_showcase_container" id="showcase-container">
<iframe id="mp-showcase" class="showcase" scrolling="no" width="100%" height="700" frameborder="0" allow="xr-spatial-tracking" allowfullscreen></iframe>
<div class="at_map_container">
<div id="at-map">
</div>
</div>
</div>
</template>
<script lang="ts">
import * as atwin from 'architwin';
//We also support default imports using import * as atwin from 'architwin';
import type { IMPConfig, IUser } from 'architwin/lib/types'; //for typescript projects
import { onMounted, ref } from 'vue';
const mpIframe = ref<HTMLIFrameElement>()
// replace with your api key and user
const apiKey = "YOUR-API-KEY"
const authUser = {
email: "su@email.com",
password: "su123"
} as IUser
....
</script>
In your vite.config.ts
, add the followig block of code. This will allow your app in your development environment to send API request to our servers and circumvent CORS issues. If you are not using vite as your build tool, please refer on the official documentation of your build tool of choice on how to setup the proxy.
You may have to change the VITE_PROXY value if you intend to direct your api requests on another server during development.
During production deployment you may need to setup proxy settings using your web or proxy server (ie: nginx, apache).
import { fileURLToPath, URL } from "node:url";
import { defineConfig, loadEnv } from "vite";
import vue from "@vitejs/plugin-vue"; //for Vue projects
import { svelte } from '@sveltejs/vite-plugin-svelte' //for Svelte projects
import react from '@vitejs/plugin-react' //for React projects
import dotenv from "dotenv";
// https://vitejs.dev/config/
export default defineConfig(({ command, mode }) => {
const env = loadEnv(mode, process.cwd(), "");
console.log("=== env ===", mode, JSON.stringify(env));
const VITE_PROXY = "https://basic-dev.rev-kitten.com";
return {
env: env,
plugins: [
vue(), //for vue projects,
svelte(), //for svelte projects,
react(), //for react projects
],
server: {
host: true,
port: 5173,
proxy: {
"/api": {
target: VITE_PROXY,
secure: false,
changeOrigin: true,
},
"/admin": { target: VITE_PROXY, secure: false, changeOrigin: true },
"/default": { target: VITE_PROXY, secure: false, changeOrigin: true },
},
},
devServer: {
host: true,
port: 5173,
proxy: {
"/api": { target: VITE_PROXY, secure: false, changeOrigin: true},
"/admin": { target: VITE_PROXY, secure: false,
changeOrigin: true },
"/default": { target: VITE_PROXY, true: false, changeOrigin: true },
},
},
resolve: {
alias: {
"@": fileURLToPath(new URL("./src", import.meta.url)),
},
},
//@ts-ignore
test: {
globals: true,
environment: "jsdom",
}
};
});
In order to connect to space you may use connectSpace() method.
<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";
// space url can also be a matterport url
// ex: const spaceUrl = "https://my.matterport.com/show/?m=qSGGhhjTYbN";
const auth = {
apiURL: 'YOUR-API-URL'
apiKey: apiKey,
user: authUser
}
const config: IMPConfig = {
iframeId: 'mp-showcase',
bundlePath: "path/to/bundle/", // optional. Iframe src should be something like this: <bundlePath>/showcase.html?
appKey: 'YOUR-APP-KEY'
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.
WARNING: This feature is deprecated, subscribe using Space Events instead
Your application may need to execute certain methods during the initialization of your 3D space. For example, you may want to useaddObjectToSpace()
method to render a model to your 3D space the moment the 3D space becomes interactive. While you can always just invoke the function after the connectSpace()
method there may be times where this will cause an error as the connectSpace()
method which is an async method, may have not finished initializing the necessary internal variables that allow other methods to work properly. When you invoke the connectSpace()
method, the library does some internal validation and then goes to several phases to render your 3D space and make it interactive. These phases are the following:
ARCHTWIN APP PHASES
- LOADING: Initial fetch request to matterport. This is where the bundle downloads the 3D space from matterport and starts rendering it
- STARTING: Matterport begins the transition to the start location
- PLAYING The 3D space is now ready for user interaction
You can also view the technical diagram of how this work below:
To invoke a function from your application during one of the phases. Simply pass the function name as a parameter in the connectSpace()
method. Make sure to not add a parenthesis to your function name when you pass it as a parameter to avoid invoking the function prematurely.
Example:
//Your application side function
async function runThisOnPlayState(){
const tags = await axios.get('my-custom-endpoint')
//Keep in mind that you should map the data from your endpoint into an object structure that the library supports
await atwin.showTags(tags)
}
await atwin.connectSpace(spaceUrl, auth, config,{onPlay:runThisOnPlayState})
In this example, the method named runThisOnPlayState
is passed as a value to the onPlay
key of an object. This will invoke the function during the PLAYING phase of the library. To invoke your function in a different phase, simply pass it to a different key in the object. You can pass your functions to onLoad,onStart, and onPlay. Async and synchronous functions are valid. Refer to the table below for more information
parameter | type | required | default | values |
---|---|---|---|---|
onLoad | Function | no | none | async or non-async function |
onStart | Function | no | none | async or non-async function |
onPlay | Function | no | none | async or non-async function |
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.
Note: We use the word Space and Showcase interchangeably.
Your 3D space allows your users to move around and interact with objects loaded into that space. Interactions such as clicking and dragging 3D objects in a space are events that your app may need to listen to and subsequently trigger the appropriate function for such an event.
You can subscribe to a particular event and pass callback method or methods to trigger when a subscribed event is fired using the subscribeSpaceEvent()
method.
The method accepts the following as its parameters:
parameter | type | required | default | values |
---|---|---|---|---|
eventType | SPACE_EVENTS or string | yes | none | valid event type |
callback | Function or Array of Functions | yes | none | function or async function |
To subscribe to an event, simpley call the subscribeSpaceEvent()
and pass the event you want to subscribe to and the method you want to trigger. Subscribing to an event will also return to you the data of an object if you are interacting with one. Said object data will implement the IShowcaseObject
interface.
Example:
function myFunction(objectData){
console.log("I will run during a DRAG_END event",objectData)
}
atwin.subscribeSpaceEvent('DRAG_END',myFunction)
You can subscribe your method to more than one event. Currently, we support subscribing only the following events but we are working to add more events in the future.
SUPPORTED EVENTS
- CLICK
- HOVER
- DRAG
- BRAG_BEGIN
- DRAG_END
- LOADING_PHASE
- STARTING_PHASE
- PLAYING_PHASE
- PLACED_TAG
- TAG_SAVED
- TAG_DISPOSED
- MEDIASCREEN_EXPANDED
- MEDIASCREEN_MINIMIZED
- MEDIA_PLAY
- MEDIA_PAUSE
- MEDIA_MUTE
- MEDIA_UNMUTE
- PARTICIPANT_ADDED
- PARTICIPANT_REMOVED
- PARTICIPANT_VIDEO_ON
- PARTICIPANT_VIDEO_OFF
- PARTICIPANT_AUDIO_STATE
- MEETING_ENDED
- SELECTED_TAG
- MODEL_RENDERED
- MODEL_DISPOSED
- TAG_MESSAGE_OPENED
- TAG_MESSAGE_SENT
- TAG_MESSAGE_RETRIEVED
- TAG_RECEPIENT_CHANGED
- TAG_LINK_COPIED
- TAG_LINK_GENERATED
- SET_TAG_ICON
- VIEW_TAG_MESSAGE
- TOOLBAR_LOADED
For more information regarding the loading,starting, and playing phase events. Please refer to this section
If you wish to subscribe multiple methods to an event. You can use the folliwing methods listed below
Method 1: Subscribing each method one at a time
function myFunction(objectData){
console.log("Function 1")
}
function myFunction2(objectData){
console.log("Function 2")
}
atwin.subscribeSpaceEvent('DRAG_END',myFunction)
atwin.subscribeSpaceEvent('DRAG_END',myFunction2)
Method 2:
Placing multiple methods in a parent method and passing it to the subscribeSpaceEvent
method
function myFunction(){
console.log("Function 1")
}
function myFunction2(){
console.log("Function 2")
}
function parentFunction(objectData) {
myFunction()
myFunction2()
}
atwin.subscribeSpaceEvent('DRAG_END',parentFunction)
Method 3:
Inserting multiple methods into an array and passing it to the subscribeSpaceEvent
method.
function myFunction(){
console.log("Function 1")
}
function myFunction2(){
console.log("Function 2")
}
const functionArray = [myFunction,myFunction2]
atwin.subscribeSpaceEvent('DRAG_END',functionArray)
Keep in mind that the library's event system utilizes an FIFO algorithm. Your functions will always be executed in chronological order meaning functions that were subscribed first will be executed first.
If you wish to unsubscribe your method from a subscribed event, simply call the unsubscribeSpaceEvent()
method to so. The method accepts the following parameters:
The method accepts the following as its parameters:
parameter | type | required | default | values |
---|---|---|---|---|
eventType | SPACE_EVENTS or string | yes | none | valid event type |
callback | Function or Array of Functions | yes | none | function or async function |
Example:
function myFunction(){
console.log("I will be unsubscribed and no longer trigger during the next DRAG_END event")
}
atwin.unsubscribeSpaceEvent('DRAG_END',myFunction)
If you used Method 3 in subscribing multiple methods. You can pass the same array to the unsubscribeSpaceEvent()
method and they will all be unsubscribed from the event.
const functionArray = [myFunction,myFunction2]
atwin.unsubscribeSpaceEvent('DRAG_END',functionArray)
The library has a list of default event types you can subscribe to but you may at times need to create your own event type to use for a specific task. You can easily create and subscribe to your own custom event by using registerCustomSpaceEvent()
and subscribeSpaceEvent()
respectively. Here is how to do it.
IMPORTANT: Your custom event type name must not be the same as an existing custom event type or a default event type. Doing so will return an error and the registration will fail.
STEP 1: Register your event type name. As a convention, the name of your event type should be in uppercase and use snake_case (e.g. FOO_BAR). It is important to register you custom event type first before subscribing a method to it. You can register one or multiple events using the method.
//Register one custom event type
atwin.registerCustomSpaceEvent('MY_EVENT')
//Register multiple custom events
const newEvents = ['FOO','BAR','MY_EVENT']
atwin.registerCustomSpaceEvent(newEvents)
STEP 2: Subscribe to your custom event
function myFunction(objectData){
console.log("Function 1")
}
atwin.subscribeSpaceEvent('MY_EVENT',myFunction)
To trigger your custom event, you can use the dispatchSpaceEvent()
in your app. You can also optionally pass a data payload with said event. Just make sure that you have done steps 1 and 2 before doing so.
The dispatchSpaceEvent()
method accepts the following as its parameters:
parameter | type | required | default | values |
---|---|---|---|---|
eventType | SPACE_EVENTS or string | yes | none | valid event type |
payload | any | no | none | any |
const someData = {
//some data here
}
atwin.dispatchSpaceEvent('MY_EVENT',someData)
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.
You may use the getTags() method in order to get a list of Tags found in the space.
You may use the goToTag() method in order to navigate to specific Tag
You may use the getSweeps() method in order get a list of Sweeps found in the Space.
You may use the moveToSweep() method in order to move to a specific Sweep
parameter | type | required | default | values |
---|---|---|---|---|
sweepId | string | yes | Id of the sweep |
import * as atwin from 'architwin';
...
const spaceUrl = "https://basic-dev.rev-kitten.com/showcase/model3d_public/1?token=e707880f-0fc5-48a6-b3f6-643a19f81464"
const ispace = {
id: 1;
name: "mySpace";
space_url: spaceUrl;
tagpin_image: null;
} as ISpace
const tagId = "5"
const sweepId = "10"
// returns a list of Tags found in the Space
await atwin.getTags(ispace)
// to navigate to specific Tag and accepts a Tag's ID
await atwin.goToTag(tagId)
// returns a list of Sweeps found in the Space
await atwin.getSweeps()
// to move to a specific Sweep
await atwin.moveToSweep(sweepId)
...
More Examples:
import * as atwin from 'architwin';
...
// get current sweep data
await atwin.getCurrentSweep()
...
Tags are interactive elements that can be added to a 3D Space. Tags are essentially clickable anotations or markers that can be placed within the 3D model of a space, typically linking to additional information or media. They enhance the user experience by providing context and additional details about specific features or objects within the Space.
To render a tag in the Space, you can use renderTag() method. The renderTag() method accepts payload input.
Example:
import * as atwin from 'architwin'
const payload = {
tag: { /* Define your tag descriptor here */ },
relocate: true,
attachments: ['attachment1.png', 'attachment2.png'],
icon: 'icon.png'
};
try {
const renderedTag = await atwin.renderTag(payload);
console.log('Rendered Tag:', renderedTag);
} catch (error) {
console.error('Error rendering tag:', error);
}
You can define your tag descriptor like this:
const tag = {
id?: string;
anchorPosition: Vector3;
stemVector: Vector3;
stemVisible?: boolean;
label?: string;
description?: string;
color?: Color;
opacity?: number;
iconId?: string;
attachments?: string[];
};
To remove a tag in the Space, you can use disposeTags(). The disposeTags() has no parameter.
Example:
import * as atwin from 'architwin'
// Example usage of the disposeTags function
async function removeTagsFromSpace() {
try {
console.log("Removing Mattertags from space...");
await atwin.disposeTags();
console.log("Mattertags removed successfully.");
} catch (error) {
console.error("Error removing Mattertags:", error);
}
}
// Call the function to remove Mattertags from the space
removeTagsFromSpace();
Removing a specific tag in the Space, the disposeTag is the right method to use.
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
};
try {
await atwin.disposeTag(payload);
console.log('Tag disposed successfully.');
} catch (error) {
console.error('Error disposing the tag:', error);
}
Tags are customizables, you customize tag labels, description, stem, icon and its color.
editTagLabel() is the right method to change or edit the label of a specific tag.
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
label: 'New Label' // Specify the new label for the tag
};
try {
await atwin.editTagLabel(payload);
console.log('Tag label edited successfully.');
} catch (error) {
console.error('Error editing the tag label:', error);
}
To edit or change the description of a tag, the editTagDescription() is the method you can use.
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
description: 'New Description' // Specify the new description for the tag
};
try {
await atwin.editTagDescription(payload);
console.log('Tag description edited successfully.');
} catch (error) {
console.error('Error editing the tag description:', error);
}
You can also choose not show or hide the tag stem by invoking editTagStem().
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
stemVisible: true // Specify the new stem visibility value
};
try {
await atwin.editTagStem(payload);
console.log('Tag stem visibility edited successfully.');
} catch (error) {
console.error('Error editing the tag stem visibility:', error);
}
Tag icon also editable, you can utilize the editTagIcon() method for this.
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
icon: 'new-icon.png', // Specify the new icon file path or reference (optional)
color: 'blue' // Specify the new color for the tag
};
try {
await atwin.editTagIcon(payload);
console.log('Tag icon and color edited successfully.');
} catch (error) {
console.error('Error editing the tag icon and color:', error);
}
You can also change the color of the tag itself, just use the editTagColor() method.
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
color: { r: 255, g: 0, b: 0 } // Specify the new color (RGB format)
};
try {
await atwin.editTagColor(payload);
console.log('Tag color edited successfully.');
} catch (error) {
console.error('Error editing the tag color:', error);
}
Ataching media to a tag is also possible, you can utilize the attachTagMedia() method.
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
attachments: ['media1.jpg', 'media2.jpg'] // Specify the media file paths
};
try {
await atwin.attachTagMedia(payload);
console.log('Media attached to the tag successfully.');
} catch (error) {
console.error('Error attaching media to the tag:', error);
}
You can also remove the attached media, just call the detachTagMedia() method.
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
attachmentIds: ['attachment1', 'attachment2'] // Specify the attachment IDs to detach
};
try {
await atwin.detachTagMedia(payload);
console.log('Media detached from the tag successfully.');
} catch (error) {
console.error('Error detaching media from the tag:', error);
}
Please explore the Tags related function to learn more what you can do with tags.
Objects that have been loaded and rendered into the 3D space are stored in an array called _3DXObjects which you can access by doing calling it this way
atwin._3DXObjects
All the elements in this array implement the IObjectData
interface. Each element in the array contains all the data you would need manipulate the object.
interface used (TS)
interface IObjectData {
collider?: any
object: IShowcaseObject
component: Scene.IComponent
node: Scene.INode
type?: string
}
Each object element inside atwin._3DXObjects
contains the value keys:
collider - Collider components define the shape of an 3D/2D object for the purposes of physical collisions. A collider, which is invisible, does not need to be the exact same shape as the GameObject’s mesh.
object - The object key is an object that implements the IShowcaseObject
interface. This is one of the most important values as the object contains all the information about an object such as its id,name,position,rotation,scale,amazon_uri link, and etc. You can look at the interface below to view the full makeup of the object key.
interface used (TS)
export interface IShowcaseObject {
id: number;
showcase_id: number;
object_id: number;
user_id: number;
object_position: {
x: number;
y: number;
z: number;
};
object_rotation: {
x: number;
y: number;
z: number;
};
object_scale: {
x: number;
y: number;
z: number;
};
autoplay: boolean;
autoplay_distance: number;
offset_position: number;
offset_rotation: number;
position_unit: string;
showcase_object_name: string;
is_deleted: boolean;
is_read: boolean;
is_new: boolean;
object_data: I3DObject;
}
component: This objects contains functions and variables responsible for intializing, updating, and destroying a rendered objects mesh, texture, etc. This object also contains the three.js instance. Since the 3D space is rendered with Three.js under the hood. You can use this instance to invoke methods made available by three.js. This gives you a lot of flexibility and control provided you know how to use it. This documentation will not cover Three.js specific methods. Visit their official website if you want to learn more about it.
node: The node is responsible for managing the lifecycle of a 3D/2D objects. The node can be used to start()
and stop()
a rendered model. Invoking start()
will render the model into the scene while stop()
will destroy it and remove it from the scene.
type: A string that states the file or object type of a 3D/2D object. The file type could be any of the following
Valid Types
type | context | description |
---|---|---|
GLB | 3D model | A 3D model with or without animation |
FBX | 3D model | A 3D model with or without animation |
FRAME | Media Screen | A customizable media screen |
ZIP | slideshow | A zip file rendered as a image slideshow |
The atwin.selectedObject
variable is an example of a variable that implements this interfacea and contains this data.
Transformation such as translate, scale, and rotate are actions used to manipulate objects in a 3D space. These transformations allow you to change an object's position, size, and orientation respectively.
NOTE: Please be aware that transform controls are disabled when viewMode in the config object you pass into connectSpace is undefined or is set to public. To enable transform controls in your 3D space. Make sure to set viewMode to 'interactive'.
Translate - Translation refers to moving an object from one position to another in space. It involves shifting the object's entire coordinate system without altering its orientation.
Scale - Scaling is the process of changing the size of an object by uniformly increasing or decreasing its dimensions along each axis. It can make an object larger (scaling up) or smaller (scaling down).
Rotate - Rotation involves changing the orientation or angle of an object around a specified point or axis. It rotates the object clockwise or counterclockwise by a certain angle.
There are several methods that allows you to transform an object. Let's go through each one
Clicking on any object in the space will attach the axis controls to it. By default, clicking on an object will show axis controls for translating the object. You can then use your mouse cursor to click and drag the object to modify its position,rotation, and scale in however way that pleases you. See screenshot for reference
You can switch the transform mode on the currently selected object by using the setTransformMode() method.
Please take note that transform controls can only be attached to one object at a time. Clicking on another object will remove the transform controls in the previous object and add it the currently selected object. It is impractical to attach multiple transform controls on more than one object. If you wish to programmatically transform multiple methods, then the next method offers a solution.
If you wish the to access the object data of the object that has been clicked on. You can do so by calling the atwin.selectedObject
variable which returns an object implementing the IObjectData
interface containing all the necessary data you need. Know more about the structure of an object by going to this section
import * as atwin from 'architwin';
...
console.log("Selected object data", atwin.selectedObject)
...
Switching Transform Modes
If you wish switch transformation mode, you can pass either 'translate' or 'scale' or 'rotate' as parameters to the setTransformMode() method. This will switch the transform controls on the currently selected object
parameter | type | required | default | values |
---|---|---|---|---|
mode | string | yes | 'translate' or 'scale' or 'rotate' |
import * as atwin from 'architwin';
...
// set the transform mode into translate
atwin.setTransformMode('translate')
// set the transform mode into scale
atwin.setTransformMode('scale')
// set the transform mode into rotate
atwin.setTransformMode('rotate')
...
If you need to transform the position,rotation, and scale of one or more objects without having to use the mouse then the
setObjectTransformation()
method will allow you to do so. The method accepts the following parameters
parameter | type | required | default | values |
---|---|---|---|---|
node | Scene.INode | yes | none | The node of the object |
transform | Object3DPosition | yes | Object containing object position,rotation,scale. More information below |
The transform object contains the following key-value pairs. These values when set will be applied to your target object
parameter | type | required | default | values |
---|---|---|---|---|
object_position | Vector3 | yes | none | Valid x,y,z coordinates |
object_rotation | Vector3 | yes | none | Valid x,y,z coordinates |
object_scale | Vector3 | yes | none | Valid x,y,z coordinates |
In this example, we will get a random 3D model from the array of rendered objects stored in atwin._3DXObjects
and manipulate it using the method. The object we will be manipulating in this example is a 3D model with a file type of GLB (You can also transform other object types such as a media screen). This will return a javascript object that contains the rendered object's data which implement the IObjectData
interface. You can know more about that by going to this section
import * as atwin from 'architwin';
...
const targetObject = atwin._3DXObjects.find(obj => obj.object.object_data.object_type == 'GLB')
const transform = {
object_position: {
x: 12.345435,
y: 0,
z: 4.54754732
},
object_rotation: {x:0,y:12,z:8},
object_scale: {x:2,y:2,z:2}
}
atwin.setObjectTransformation(targetObject.node,transform)
...
NOTE: You can also mirror an object by knowing the center position first then add and subtract (depending whether you want to mirror it to the left or to the right) values on either x, y, or z in the object_position.
import * as atwin from 'architwin';
...
const centerPosition:Vector3 = {x:6, y:6,z:6}
// add 5 values in either x, y, or z in the object_position to the mediaScreen to be positioned in the left
const mediaScreen = ArrayOfMediaScreen.value[0]
const newObjectPosition = {
object_position: {x:centerPosition.x+5, y:centerPosition.y, z:centerPosition.z},
object_rotation: {x:0, y:0, z:0},
object_scale: {x:4, y:4, z:1}
} as Object3DPosition;
atwin.setObjectTransformation(mediaScreen.node, newObjectPosition)
// subtract 5 values in either x, y, or z in the object_position to the mediaScreen to be positioned in the right
const mirrorMediaScreen = ArrayOfMediaScreen.value[1]
const mirrorObjectPosition = {
object_position: {x:centerPosition.x-5, y:centerPosition.y, z:centerPosition.z},
object_rotation: {x:0, y:0, z:0},
object_scale: {x:4, y:4, z:1}
} as Object3DPosition;
atwin.setObjectTransformation(mirrorMediaScreen.node, mirrorObjectPosition)
...
If done correctly, you should see your target object(s) display or reposition to your intended position, rotation, and scale. Please take note that the transform controls UI will not be attached to the object if you use this method
Redo and undo are actions that allow you to revert or replay previous transformations performed on an object. They provide a way to navigate through the history of transformations and make adjustments or restore previous states.
Assuming that you have already selected an object and already performed different transformation actions. You can use the methods in the library to redo and undo the changes.
In order to do this, you may use the revertTransform() method to revert changes. By default, the action is set to 'undo'.
import * as atwin from 'architwin';
...
atwin.revertTransform()
...
If you want to redo a tranformation, change the parameter to 'redo'.
import * as atwin from 'architwin';
...
atwin.revertTransform('redo')
...
Adding an object to your space refers to the process of incorporating a pre-existing 2D or 3D object from the database into the 3D space. It allows for the creation of visualizations, simulations, and interactive experiences in your space.
In order to add an object, you may use the addObjectToSpace() method.
parameter | type | required | default | values |
---|---|---|---|---|
objectUrl | string | yes | none | valid url to media/object |
objectType | string | yes | none | valid supported file type (GLB,FBX) |
config | ObjectConfig | yes | valid config object |
There are two ways you can use the addObjectToSpace() method. We will go through each one
Method 1: Adding Programmatically
If you wish to add new object to your space to a pre-defined position, you can use the addObjectToSpace() method and pass the objectConfig
along.
import * as atwin from 'architwin';
...
let objectUrl:string = "https://example.s3.amazonaws.com/filename.GLB";
let objectType:string = "GLB"
const yourTargetPosition = {
x: 12.345435,
y: 0,
z: 4.54754732
}
const objScale = {x:1,y:1,z:1}
const objRotation = {x:0,y:0,z:0}
let objectConfig = {
position: yourTargetPosition,
scale: objScale,
rotation: objRotation,
} as ObjectConfig;
atwin.addObjectToSpace(objectUrl,objectType, objectConfig)
...
Method 2: Adding with click method using getTargetPosition
The library has several helper methods that provide a range of commmon functionalities to help you achieve certain actions easier. If for example, you do not have your intended position coordinates stored in the database or in a local area and wish to click a specific area of the 3D space and get that the coordinates of the area you clicked, you may do some by using the getTargetPosition()
helper method in tangent with the addObjectToSpace() method to do so. You can click here to know more about the getTargetPosition()
method
Here is an example of how you can use the two methods together. This is just one example, it is up to you on how you wish to combine different methods provided by the library
import * as atwin from 'architwin';
...
function myCallbackFunction(clickedPosition){
let objectUrl:string = "https://example.s3.amazonaws.com/filename.GLB";
let objectType:string = "GLB"
const objRotation = {x:0,y:0,z:0}
const objScale = {x:1,y:1,z:1}
let objectConfig = {
position: clickedPosition,
scale: objScale,
rotation: objRotation,
} as ObjectConfig;
await atwin.addObjectToSpace(objectUrl,objectType, objectConfig)
}
atwin.getTargetPosition(myCallbackFunction)
...
A Media Screen is a customizable 2D object whose content can be used to display either an image or a video in the 3D space. You may for example use it in your 3D space and allow your users to interact with it and change its content.
In order to add a media screen, you may use the addMediaScreen() method. The addMediaScreen() method accepts the following parameters:
parameter | type | required | default | values |
---|---|---|---|---|
mediaUrl | string | no | empty string | valid public url to an image |
transform | {Vector3,Vector3,Vector3} | yes | Refer to information below** | |
readonly | boolean | no | false | true or false |
autoplay | boolean | no | false | true or false |
The transform object is an object that contains the following key-value pairs
parameter | type | required | default | values |
---|---|---|---|---|
position | Vector3 | yes | no default | valid numeric x,y,z values |
scale | Vector3 | no | {x:1,y:1,z:1} | valid numeric x,y,z values |
rotation | Vector3 | no | {x:0,y:0,z:0} | valid numeric x,y,z values |
By default, your media screen will show a blank white canvas if you set the mediaUrl parameter of the addMediaScreen() method as an empty string or undefined
.
IMPORTANT: The link to your media you provide to the mediaUrl MUST be publicly accessible and have the appropriate CORS headers, otherwise, your media will not load into the media screen.
There are many ways you can use this method to add a media screen to your 3D space. Let's go through each one.
NOTE: The following examples utilize typescript and will utilize the TypeScript (TS) interfaces the library provides. While you can use just plain JavaScript (JS) for your project and copy the following code snippets (minus the TS interfaces) to your plain JS project, we highly recommend that you use TypeScript instead for your Architwin powered projects to take advantage of the type-safety and the custom interfaces provided by the library
Method 1: Adding Programmatically
To create a media screen on a pre-defined position, you can create an object that contains the position,rotation,and scale.
import * as atwin from 'architwin';
...
const yourTargetPosition = {
x: 12.345435,
y: 0,
z: 4.54754732
}
const objRotation = {x:0,y:0,z:0}
const objScale = {x:1,y:1,z:1}
const transform = {
position: yourTargetPosition,
rotation: objRotation,
scale: objScale
}
await atwin.addMediaScreen('',transform)
...
If done correctly, you should be able to see your media screen in your intended position. This method is useful if you already have the position, rotation, and scale values stored in a database or possibly in a local array
Method 2: Adding with click method using getTargetPosition
The library has several helper methods that provide a range of commmon functionalities to help you achieve certain actions easier. If for example, you do not have your intended position coordinates stored in the database or in a local area and wish to click a specific area of the 3D space and get that the coordinates of the area you clicked, you may do some by using the getTargetPosition()
helper method in tangent with the addMediaScreen() method to do so. You can click here to know more about the getTargetPosition()
method
Here is an example of how you can use the two methods together. This is just one example, it is up to you on how you wish to combine different methods provided by the library
import * as atwin from 'architwin';
...
function myCallbackFunction(clickedPosition){
const objRotation = {x:0,y:0,z:0}
const objScale = {x:1,y:1,z:1}
const transform = {
position: clickedPosition,
rotation: objRotation,
scale: objScale
}
atwin.addMediaScreen('',transform)
return coords
}
await atwin.getTargetPosition(myCallbackFunction)
...
Attach Media Screen Parameters
parameter | type | required | default | values |
---|---|---|---|---|
mediaScreenId | number | yes | none | id of object |
mediaUrl | string | yes | none | valid public url to the media |
mediaType | string | no | image | 'image' or 'video' |
IMPORTANT: The link to your media you provide to the mediaUrl MUST be publicly accessible and have the appropriate CORS headers, otherwise, your media will not load into the media screen.
In this example, we are using a link pointing to the media stored in an s3 bucket as the mediaUrl and a random media screen id. You will have to substitute the id with an actual id of a rendered media screen.
Example with image:
import * as atwin from 'architwin';
...
const targetMediaScreenId = 12
const validUrl = 'https://stg-feelpet.s3.ap-northeast-1.amazonaws.com/0CB45E51-EC48-4727-906A-4CD8A13C0770.jpg'
atwin.attachMediaScreenContent(targetMediaScreenId, validUrl, 'image')
...
Example with video:
import * as atwin from 'architwin';
...
const targetMediaScreenId = 12
const validUrl = 'https://stg-feelpet.s3.ap-northeast-1.amazonaws.com/VID_20230203_165202.mp4'
await atwin.attachMediaScreenContent(targetMediaScreenId, validUrl, 'video')
...
When setting a video as the media screen content. You can use the setVideoPlayback() method to programmatically play,pause,mute,and unmute a video. You can navigate to the playback controls section to learn more about the method. Here is an example on how to use it.
In this example, we are getting a random media screen from the atwin._3DXObject
array which contains all the objects rendered in the space. Media screens whose media type is a video will have a variable called planeElement
inside the object's component
which contains an HTML video element that we can manipulate using the setVideoPlayback() method. Please take note that this variable is not acessible if the media type of the media screen content is an image.
Interface used
export interface IObjectData {
collider?: any
object: IShowcaseObject
component: Scene.IComponent
node: Scene.INode
type?: string
}
Example:
import * as atwin from 'architwin';
...
const randomMediaScreen:IObjectData = atwin._3DXObject.find(obj => obj.object.object_data.object_type == 'FRAME')
// plays the video
atwin.setVideoPlayback('play', randomMediaScreen.component.planeElement)
...
You can use the transform controls to change the position, scale, and rotation of the media screen using the mouse cursor.
Media screens by default will display a dock button on each corner of the displayed media that allows you to dock the media screen in the 4 corners of your FOV inside a space. To hide these buttons, you may add the following in your config object.
const config = {
//other configs
mediaScreenConfig: {
showExpandButton: false
}
}
Setting video playback refers to the act of adjusting various controls associated with the playback of a video in the space. It involves manipulating controls such as pause, play, mute, and unmute to modify the playback behavior according to user's preferences.
Pause - Pausing a video temporarily allows user to freeze the video at a specific moment.
Play - Playing a video resumes its playback from paused state, allowing the user to watch the video in real-time .
Mute - Muting a video disables the audio playback, suppressing any sound embedded within the video.
Unmute - Unmuting a video enables the audio playback, restoring any sound embedded within the video.
Assuming that you have already selected a video, you can now set the playback of the video.
Inorder to set the playback of a video, you may use the setVideoPlayback() method.
parameter | type | required | default | values |
---|---|---|---|---|
action | string | yes | none | 'play' or 'pause' or 'mute' or 'unmute' |
element | HTMLVideoElement | yes | none | supported html video element |
If you wish to change the action of the playback, add a parameter such as 'play','pause', 'mute', 'unmute' depending on your preference.
Example:
import * as atwin from 'architwin';
...
const randomMediaScreen:IObjectData = atwin._3DXObject.find(obj => obj.object.object_data.object_type == 'FRAME')
// plays the video
atwin.setVideoPlayback('play', targetVideoElement)
// pauses the video
atwin.setVideoPlayback('pause', targetVideoElement)
// mutes the video
atwin.setVideoPlayback('mute', targetVideoElement)
// unmutes the video
atwin.setVideoPlayback('unmute', targetVideoElement)
...
NOTE: Please take note that this variable is not acessible if the media type of the media screen content is an image.
Setting animation control refers to the process of manipulating the playback of animations applied to 3D objects in the space. It involves utilizing controls such as play and pause to control the the animation.
Assuming that you have already selected an animated 3D object, you can now control the setting of the animation.
In order to set the animation control of a 3D object, you may use the setAnimationState() method. By default the action is set to 'play'.
NOTE: Please take note that the 3D object MUST be fully rendered first in the space before you can manipuate its animation state. This method will have no affect on 3D objects that do not have any animations in them.
parameter | type | required | default | values |
---|---|---|---|---|
action | string | yes | play | 'play' or 'pause' |
modelId | number | yes | none | showcase id of the 3D model |
import * as atwin from 'architwin';
...
const modelID = 17
atwin.setAnimationState('play', modelID)
...
If you wish to pause the Animation of the 3D object, change the parameter to 'pause'.
import * as atwin from 'architwin';
...
const modelID = 17
atwin.setAnimationState('pause', modelID)
...
Copying an object refers to creating a duplicate or clone of an object. When an object is copied in the space, it means that the object's data is duplicated.
Assuming that you have already selected an object to be copied, you may now copy the object by calling copyObject() method. You may also specify a custom offset position and rotation of the object to be cloned.
parameter | type | required | default | values |
---|---|---|---|---|
payload | IShowcaseObject | yes | object payload | |
position_offset | Vector3 | no | +0.5 | |
rotation_offset | Vector3 | no | +0.5 |
import * as atwin from 'architwin';
...
let offsetPos:Vector3 = {x:0,y:0,z:0}
let offsetRot:Vector3 = {x:0,y:0,z:0}
if (atwin.selectedObject.object) {
await atwin.copyObject(atwin.selectedObject.object, offsetPos, offsetRot)
}
...
NOTE: rotation_offset can be manipulated in order to mirror the object
Navigating to an object in space refers to the process of moving the camera's location near to the object.
Assuming that you have already selected an object to navigate to, you may now navigate to the object by using goToModel() method.
parameter | type | required | default | values |
---|---|---|---|---|
objectId | number | yes |
import * as atwin from 'architwin';
....
await atwin.goToModel(objectId)
....
Deleting an object in space refers to the process of removing a pre-existing 2D or 3D object from the 3D environment or space. This action results in the elimination of the visual representation and physical presence of the object within the virtual space. By removing the object, users can maintain control over the composition and contents of their space, allowing for more dynamic and tailored virtual experiences.
Assuming that you have already selected an object to be deleted, you may now delete the object by using deleteObjectFromSpace() method.
parameter | type | required | default | values |
---|---|---|---|---|
selected | IObjectData | yes |
import * as atwin from 'architwin';
...
// this function handles the object to be deleted from space
async function handleDeleteObjectFromSpace() {
await atwin.deleteObjectFromSpace(atwin.selectedObject)
}
...
NOTE: This is only deleting the object from the space and not from the database.
Replacing an object in space refers to the process of substituting a pre-existing 2D or 3D object within a 3D environment or space with another object. This action involves removing the original object and introducing a new one in its place, while maintaining the object's location and any associated properties or attributes.
Assuming that you have already selected an object to be replaced, you may now replace the object by using replaceObject() method.
parameter | type | required | default | values |
---|---|---|---|---|
payload | I3DObject | yes | ||
target | IObjectData | yes | ||
options | Object | no | null |
import * as atwin from 'architwin';
...
// id of the object
const objectId:number = 5
// object that will replace
const objectData = await atwin.getObject(objectId)
// object to be replaced
const objectDataToBeReplaced = atwin.selectedObject
// this function handles the replaceObject() method
async function handleReplaceObject() {
await atwin.replaceObject(objectData, objectDataToBeReplaced)
}
...
A text markup screen is a graphical user interface objecet that allows users to input and display formatted text in the 3D space. The method internally generates elements and programmatically applies CSS styling. You can use this method to display text messages to the 3D screen.
In order to add a text markup screen in your space, you may use the addTextMarkupScreen() method.
parameter | type | required | default | values |
---|---|---|---|---|
title | string | no | empty string | title of message |
message | string | yes | none | message content |
textScreenName | string | yes | none | name of text frame |
transform | {Vector3, Vector3, Vector3} | yes | none | numeric value for x, y, z |
textColor | string | no | black | valid color value |
backgroundColor | string | no | '#fffff' | valid color value |
import * as atwin from 'architwin';
...
const title:string = 'My Text Markup Screen'
const message:string = 'This is my message'
const position = {
x: 12.345435,
y: 0,
z: 4.54754732
}
const scale = {x:0, y:0, z:0}
const rotation = {x:0, y:0, z:0}
const transform = {
position: position,
scale: scale,
rotation: rotation
}
atwin.addTextMarkupScreen(title, message, transform)
...
If you wish to update the style and content for the text frame, you may use the setTextMarkupScreenContent() method. You can customize the text content as well as the foreground and background color of the target text markup screen.
parameter | type | required | default | values |
---|---|---|---|---|
showcase_id | number | yes | none | id of target object |
title | string | no | empty string | title of the content |
text | string | no | empty string | body of the content |
textColor | string | no | black | valid color value |
backgroundColor | string | no | '#fffff' | valid color value |
import * as atwin from 'architwin';
...
const id = 10
const title = 'My title'
const text = 'This is the content of the body'
const textColor = 'white'
const backgroundColor = '#00000'
atwin.setTextMarkupScreenContent(id, title, text, textColor, backgroundColor)
...
We encourage that you use typescript for any new project you intend to use the library with. With typescript, you can take advantage of the type interfaces provided by the library. This helps you catch errors more easily on your IDE instead of seeing it on production. If you do intend to just use vanilla JS for your project, you can still use this section as reference on how how to structure the javascript objects in yours project
You can use the library's type interfaces by importing it using the following import path
import type {IShowcaseObject} from 'architwin/lib/types'
const spaceObject:IShowcaseObject = {}
The library also exports a couple enums that you can use in your project too. Here are a few ways of importing enums
//Method 1: Import interface and enums in one line
import {type IShowcaseObject,SPACE_EVENTS} from 'architwin/lib/types'
//Method 2: Import interface and enums separately
import type {IShowcaseObject} from 'archtwin/lib/types'
import {SPACE_EVENTS} from 'architwin/lib/types'
const spaceObject:IShowcaseObject = {}
As a convention, interfaces provided by the library are written in PascalCase while enums are written in an uppercase SNAKE_CASE. We recommend that you follow this convention for your own interfaces for uniformity.
interface ITag {
id: number,
tag_name: string, // required
showcase_id: number, // required
floor_id: number, // required
color_id: number, // required
details?: string,
remarks?: string,
json_data: MpSdk.Tag.TagData, // required (mp tag data)
tag_type_id?: number,
sid: string,
bid?: string,
filename?: string,
tag_image?: string,
tag_url?: string,
tag_order?: number,
label: number, // required
}
interface ITagPublic {
id: string;
name: string;
}
interface IShowcaseObject {
id: number;
showcase_id: number;
object_id: number;
user_id: number;
uuid?: string;
space_uuid?: string;
object_uuid?: string;
object_position: {
x: number;
y: number;
z: number;
};
object_rotation: {
x: number;
y: number;
z: number;
};
object_scale: {
x: number;
y: number;
z: number;
};
autoplay: boolean;
autoplay_distance: number;
offset_position: number;
offset_rotation: number;
position_unit: string;
showcase_object_name: string;
is_deleted: boolean;
is_read: boolean;
is_new: boolean;
object_data: I3DObject;
}
interface I3DObject {
id: number;
uuid?: string;
upload_file: string;
upload_filename: string;
filename: string;
user_id: number;
name: string;
description: string;
object_type: string;
object_key: string;
amazon_uri: string;
object_thumbnail?: string;
thumbnail_key?: string;
thumbnail_type?: string;
}
interface IObjectData {
collider?: any
object: IShowcaseObject
component: Scene.IComponent
node: Scene.INode
type?: string
}
interface NearbyObjects {
x3d: Array<IObjectData>
videos: Array<IObjectData>
slideshows: Array<IObjectData>
}
interface ObjectConfig {
options?: {
name?: string | undefined
title?: string | undefined
type?: string | undefined
url?: string | undefined
iframeId?: string | undefined
wrapperId?: string | undefined
textColor?: string | undefined
backgroundColor?: string | undefined
visible?: boolean | undefined
aspectRatio?: number | undefined
text?: string | undefined
fontSize?: number | undefined
background?: boolean | undefined
centered?: boolean | undefined
height?: number | undefined
curveSegments?: number | undefined
bevelEnabled?: boolean | undefined
bevelThickness?: number | undefined
bevelSize?: number | undefined
bevelOffset?: number | undefined
bevelSegments?: number | undefined
}
position?: Vector3
scale?: Vector3
rotation?: Vector3
}
interface MediaScreenConfig {
mediaUrl?: string
mediaType?:string
transform?: VectorCoords
readonly?: boolean
autoplay?:boolean
}
export interface VectorCoords {
object_position: Vector3
object_rotation: Vector3
object_scale:Vector3
}
interface MeetingInfo {
space_id: string;
meeting_id?: string;
host_name?: string;
title?: string;
meeting_start?: Date;
meeting_status?: MeetingStatus;
duration?: number;
password?: string;
}
interface MeetingConfig {
customColors?: MeetingCustomColors;
customAvatars?: Avatar[];
deviceControl?: MeetingDeviceControl;
meetingBarPosition?: MeetingBarPosition;
}
interface MeetingDeviceControl {
videoInput: boolean;
audioInput: boolean;
audioOutput: boolean;
}
interface Avatar {
model: string;
thumbnail: string;
}
interface MeetingConfig {
customColors?: MeetingCustomColors;
customAvatars?: Avatar[];
deviceControl?: MeetingDeviceControl;
meetingBarPosition?: MeetingBarPosition;
}
interface MeetingDeviceControl {
videoInput: boolean;
audioInput: boolean;
audioOutput: boolean;
}
interface IParticipant {
id?: string;
name?: string;
type?: IParticipantType;
color?: string;
avatar?: Avatar;
shapeNum?: number;
}
interface IMpParticipant{
avatar: {
model: string,
thumbnail: string,
},
avatarConfig: {
height: number,
scale: number,
laserOrigin: {x: number, y: number, z: number}
},
id: string,
name: string,
color?: string,
shape?: PShapes,
position: {x: number, y: number, z: number},
rotation: {x: number, y: number, z: number},
}
Hosting Live Virtual Meetings inside 3D Space using Video SDK
This meeting feature utilizes the Video SDK to host virtual conferences within a 3D Space View. It includes a custom-designed meeting UI displayed as a sidebar on the left side of the screen. This allows the user to create, share, and join meetings using a meeting link provided by the host.
The next few sections will explain how you can get started in creating or hosting your own virtual meeting inside your 3D Spaces.
Before you can start hosting or joining meetings, make sure that meeting sidebar is enabled in toolbar Config.
Example:
const config = {
//Other config values...
toolbarConfig: {
active: isAtwinSideBarEnabled.value,
lang: lang.value,
menuItems: {
meeting: true
}
},
} as IMPConfig;
Once the meeting sidebar is enabled, click the video icon in the toolbar, and the first screen that appears will be the create meeting screen.
The following data are required to proceed from the create meeting screen:
- Meeting Topic : string - The name or topic of the meeting.
- Fullname : string - The name of the participant.
This screen will allow users to set up their audio, speakers, and camera settings before entering the virtual conference.
- Audio: Users can mute/unmute audio before joining the meeting.
- Camera: Users can disable/enable camera view before joining the meeting.
- Choose Avatar: Users can select an avatar and set as their profile during the meeting.
- Video: Users can select any connected camera device they wish to use.
- Speaker: Users can select any connected speaker device they wish to use.
- Microphone: Users can select any connected microphone device they wish to use.
Once a user visits the meeting link provided by the host, they will be automatically directed to the 3D Space view specific to that meeting. At the same time, the join meeting
screen will be displayed, allowing users to enter the meeting. To proceed, users are required to input their name in the "Fullname" field before joining the meeting.
This screen is where the virtual conference will take place. Both the host and participants can see and interact with each other through visual and audio communication.
-
Meeting Controls: The list of meeting controls includes settings, screen sharing, and toggles for video and audio.
- Settings: This three-dots represents the settings of the sidebar. This is where users can view the list of participants, can follow a participant inside space view, and copy the meeting link.
- Share screen: This screen button will allow users to share their screen to other participants within the meeting.
- Video: This video icon button toggles the user's camera on or off.
- Audio: This audio icon button toggles the user's microphone on or off.
Some Functions are async; when invoking them, Use keyword await or .then syntax
Connect and load a 3D space into an HTML iframe asynchronously using this function. It initializes various configuration settings and view modes based on the provided parameters.
async function connectSpace(
url: string,
auth: { apiURL?: string; apiKey: string; user: IUser } | null,
config: IMPConfig,
callbacks: { onLoad: Function; onStart: Function; onPlay: Function } | undefined = undefined
): Promise<void>
parameter | type | required | default | values |
---|---|---|---|---|
url | string | yes | valid space URL | |
auth | { string; string; IUser } | yes | ||
config | IMPConfig | yes |
url - the URL of the space you wish to connect to.
- The connectSpace method can also accomodate the following URL parameters:
-
"tagId" : ID of the tag
- In cases where the 'tag' is included in the URL with an assigned value, the camera location will swiftly adjust to the specified tag within the 3D space once the loading is complete. The particular tag to focus on will be determined by the value of the 'tag' parameter.
-
"sweepId" : ID of the sweep
- If the 'sweep' is present in the URL with a value, the camera location will immediately navigate to the specific sweep within the 3D space after loading. This specific sweep will be identified using the value of the 'sweep' parameter.
-
"brand" : 0 | 1
- 0 : Remove the 'Presented By' information upon model launch. Additionally, hide contact details within the "About" panel located in the upper-left corner of the 3D Showcase interface.
- 1 (Default) : Show all branding-related information within the "About" panel positioned at the top-left corner of the 3D Showcase interface.
-
"hr" : 0 | 1
- 0 : Hide the highlight reel located at the bottom of the 3D Showcase user interface.
- 1 (Default) : Dispaly highlight reel
-
"tour" : 0 | 1 | 2 | 3
- 0 : Tour controls and highlight reel will not be visible.
- 1 (Default) : The saved tour mode within the model is used.
- 2 : Story mode tour is used.
- 3: Highlight reel mode tour is used.
-
"dh" : 0 | 1
- 0 : Hide the Dollhouse View during the introductory fly-in. Additionally, hide the Dollhouse Button located in the bottom left corner of the 3D Showcase user interface. Moreover, remove the snapshots of the Dollhouse and Floorplan views from the highlight reel.
- 1 (Default) : Display Dollhouse View
-
"tagNav" : 0 | 1
- 0 : Removes the < and > buttons from Tags and disables navigation through Tags using the "," and "." keys.
- 1 (Default): Displays the < and > buttons for Tags and permits navigation through Tags using the "," and "." keys.
-
"mt" : 0 | 1
- 0 : Conceal Mattertags and "Mattertag™ Content" toggle in the "About" panel.
- 1 (Default) : Display Mattertag™ Posts
-
"mls": 0 | 1 | 2
- 0 (Default) : Show branding information, links in Mattertag™ Posts, and VR.
- 1 : Show the MLS-friendly version of the Matterport model. This hides branding, hides links in Mattertag™ Posts, and hides VR.
- 2 : Same behavior as &mls=1 but also hides the "About" panel in the top-left corner after loading.
-
"f" : 0 | 1
- 0 : Hide the option to switch floors. This treats the Matterport model as "all one floor".
- 1 (Default) : Allow the user navigate the 3D model floor by floor.
-
"fp" : 0 | 1
- 0 : Hide the floor plan view button from the bottom-left corner of the 3D Showcase UI.
- 1 (Default) : Display the floor plan view button in the bottom-left corner of the 3D Showcase UI.
-
"search" : 0 | 1
- 0 : Hide the magnifying glass (search) icon from the upper-left corner of the 3D Showcase UI.
- 1 (Default) : Display the magnifying glass (search) icon in the upper-left corner of the 3D Showcase UI. If Space Search is disabled at the account level, this parameter has no effect.
-
"title" : 0 | 1
- 0 : The space title is not being shown, and the top-left about panel is also not visible.
- 1 (Default) : "The space title is being shown. The top-left about panel is visible."
-
"vr" : 0 | 1
- 0 : Remove the VR button.
- 1 (Default) : Display the VR button.
-
If the parameters 'objectId,' 'tag,' and 'sweep' are present in the URL with values, the first parameter among the three will be accommodated based on the URL structure.
auth - an authentication object with the apiKey and user credentials. Default user credentials will be provided by ArchiTwin for testing which you can change anytime to your own user credentials. The auth object passed to the connectSpace
method may consist of the following keys:
- apiURL: (string) an optional key which if set, will point all internal API calls to the api endpoint or base URL you assign. If this is not set, all api calls will be directed to the proxy address set in the
vite.config.ts
file during local development. Example:apiURL: "apps.awesomesite.com/api"
will resolve internally toapps.awesomesite.com/api/cas/tickets?someparams
orapps.awesomesite.com/api/v1/showcase/id/1
. It is important to add/api
to the base url of your custom apiURL to ensure the api requests are properly sent. There is no need to add a forward slash at the end of our custom apiURL. Please take note that you may have to setup a proxy server to bypass CORS issues when you deploy your application on your production servers - apiKey: (string) sets the required apiKey that is inserted into the authorization headers of each API request
- user: (IUser | Object) an object that contains the
email
andpassword
of the user.
config - a config object to set some default space behavior. You can learn more about the config object below.
export interface IMPConfig {
iframeId: string;
appKey?: string;
bundlePath?: string;
mapId?: string;
meetingApiKey?: string,
showOriginalTags?: boolean,
// Launching 3D Showcase
help?: 0 | 1 | 2;
nt?: 0 | 1;
play?: 0 | 1;
qs?: 0 | 1;
// Visibility
brand?: 0 | 1;
dh?: 0 | 1;
tour?: 0 | 1 | 2 | 3;
gt?: 0 | 1;
hr?: 0 | 1;
mls?: 0 | 1 | 2;
mt?: 0 | 1;
tagNav?: 0 | 1;
pin?: 0 | 1;
portal?: 0 | 1;
// User Interface
f?: 0 | 1;
fp?: 0 | 1;
// LOCALIZATION
lang?: MP_LANG;
// GUIDED TOURS
kb?: 0 | 1;
lp?: 0 | 1;
st?: Number; // Number of milliseconds to wait at each highlight during a Guided Tour. Default is 3500 ms.
title?: 0 | 1 | 2;
tourcta?: 0 | 1 | 2;
// Transition speed (meters per second) when moving between highlights. Recommend speed is in range of 1 to 3, default of 2. Your highlight reel must be set to "Walkthrough" mode (not slideshow)
wts?: Number;
// Set this parameter to start the tour automatically and define the number of seconds after initial fly-in before the Guided Tour automatically starts. Help is not shown. Set to a negative number to not start the Guided Tour.
ts?: Number;
hl?: 0 | 1 | 2;
vr?: 0 | 1;
//OTHERS,
nozoom?: 0 | 1;
search?: 0 | 1;
wh?: 0 | 1;
prod?: boolean; //sets appropriate file path of showcase based on value
viewMode?: VIEW_MODE | string //determines if viewer of space can utilize features like transform controls
fetchObjectsOnLoad?: {
active?:boolean
apiEndpoint?:string //Custom api endpoint to fetch space/showcase objects from. Supports azusa and open_at endpoint. Default points to open_at endpoint
}
mapConfig?: IMapConfig
mediaScreenConfig?: ISharedScreen
toolbarConfig?: IToolbarConfig
avatartwinConfig?: {
avatartwinKey: string
}
meetConfig?: {
sdkKey: string
secretKey: string
}
appConfigKeys?:{
mpKey: string //required
embedlyKey: string //for rendering attachments
meetSdkKey?: string //zoom sdk key
meetSecretKey?: string //zoom secret key
// avatartwinKey?: string //superviz key
appName?: string // app name / title
}
debug?: {
//If debug valu is not defined, Only error logs are shown by default
//Valid log levels are trace,warn,error,info,trace,silent
logLevel: string
},
restrictionConfig?:{
isTagReadOnly?: boolean
}
}
iframeId: string: The id
of the target iframe where the 3D space will be loaded into.
appKey: your appKey is used to authenticate your connection when loading the 3D showcase. For security purposes, the appKey can only be used by a domain (e.g. awesomesite.com) it is associated with. This key is important especially when you launch your app in production and utilize your own site domain. Please contact us to request your appKey
bundlePath?: string: bundlePath is an optional key that can be set for projects whose project structure requires a custom path to the bundle SDK provided by matterport. If not set, the package will by default set the bundle path to the bundle SDK found inside the architwin package in node_modules.
viewMode string: viewMode is an optional key that enables and disables transform controls in your 3D space. If the value of viewMode is not set, it will default to setting the viewMode to 'public' which disables transform controls. To enable the ability to transform objects using the transform control axis UI, you must set viewMode to 'interactive'
Example:
bundlePath: "assets/customBundleName"
This will resolve internally to "assets/customBundleName/showcase.html?someparams"
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.
Example:
import * as 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 = {
apiURL: "YOUR-API-URL", //Set the url to make api requests to
apiKey: "YOUR-API-KEY", //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)
You can enable a minimap display of your 3D space by setting the following key-values in your config object that you pass into the connectSpace
method
const config = {
//Other config values...
mapConfig: {
mapId: 'at-map', //required
position: 'topLeft',
}
} as IMPConfig;
To ensure that you will not encounter any errors. Make sure to follow the prescribed markup structure under the defining an iFrame section. All CSS classes or ids used internally by the library will have an at_
prefix for classes and an at-
for ids. The classes and ids are named this way to avoid any naming conflicts with your apps own CSS classes or ids.
You can technically forego the at_showcase_container class of the parent div with your own class. Just make sure it has the position
attribute set to relative
otherwise things may not position correctly.
mapConfig Options
- mapId - The id attribute value of the div element that will hold the map.
- position - (optional) Specify where to place the minimap. Valid positions are topLeft, topRight, bottomRight, bottomLeft. By default, the map is placed at the topRight corner if this value is not set.
- fixedSized - (optional) Specify a fixed width of the minimap. By default, the minimap has width of 100px and expands to 250px upon mouse hover. Please take note that setting a fixed width of your minimap will disable the hover-to-expand animation. Any numberic value you provide will be translated into pixel units
Example:
const config = {
//Other config values...
mapConfig: {
mapId: 'at-map', //required
position: 'topLeft',
fixedSized:{
width: 300
}
}
} as IMPConfig;
- sweepMarker - (optional) Specify the backgroundColor, activeColor, hoverColor, opacity and if the sweep markers should be displayed on hover or all the time. For opacity, we recommend you set it between 0.5 to 0.8 to not obscure the minimap and or make your markers too transparent. Any valid CSS color value can be used for backgroundColor,activeColor, and hoverColor. You can display the sweep markers at all times by setting showOnHover value to false.
const config = {
//Other config values...
sweepMarker: {
showOnHover: false,
backgroundColor: '#fc9f5b',
activeColor: '#FBD1A2',
hoverColor: '#7DCFB6',
opacity: 0.8
}
} as IMPConfig;
- zIndex - (optional) Set the z-index of the map. In cases where you have UI elements that coincide with the position of the minimap. You set the z-index value of the minimap to determine what order the minimap should be rendered.
Customizing Individual Minimap Sweep Buttons
You may use the setSweepMarkerColor
method if you need to customize the individual colors of the sweep buttons in the minimap. The method accepts either an object that contains the sweepId of the sweep button and the new background color or an array of said object
parameter | type | required | default | values |
---|---|---|---|---|
payload | SweepColor or Array of SweepColor | yes |
Example:
import * as atwin from 'architwin'
const newSweepColor = {
sweepId: 'validSweepId',
backgroundColor: '#353535'
} as SweepColor
atwin.minimap.setSweepMarkerColor(newSweepColor)
If you want to change the color of multiple sweep buttons when the minimap
sweep buttons are rendered, you may subscribe to the MINIMAP_SWEEPS_RENDERED
event using the subscribeSpaceEvent
method.
Example:
import * as atwin from 'architwin'
const newSweepColors = [
{
sweepId: 'validSweepId',
backgroundColor: '#353535'
},
//other objects
]
atwin.subscribeSpaceEvent('MINIMAP_SWEEPS_RENDERED', atwin.minimap.setSweepMarkerColor(newSweepColors))
Displaying the minimap outside the iFrame
There may be instances where you need to display the provided minimap outside of the 3D space displayed by your iFrame. In such cases, you may access the setMap
method of the minimap
object to display the minimap elsewhere. Do take note that there can only be one instance of the minimap displayed at a time. Which means that you should not pass minimapConfig to the connectSpace method when displaying the minimap outside the space. We may add the ability to display multiple minimaps at the same time in future releases.
The setMap method requires the following parameters
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
mpSdk | MpSdk | yes | none | Matterport SDK instance |
appKey | string | yes | none | Your matterport app key |
mapId | string | yes | none | id of the element that will hold the map |
NOTE: You can get the instance of mpSdk by using the getAtwinSdk
method
Here's an example on how to do it.
Step 1: Create an element and give it the id of at-map
<div id="at-map"></div>
Step 2: Run the setMap method and pass the required parameters
import * as atwin from 'architwin'
const sdk = getAtwinSdk()
atwin.minimap.setMap(sdk,'YOUR-APP-KEY','at-map')
To activate a toolbar display within your 3D Space, you can set the following key-value pairs in your configuration object.
Example:
const config = {
//Other config values...
toolbarConfig: {
active: true,
lang: 'en', // Supported language: en and ja,
themeConfig: {
customizations: {
toolbarOffset: {
top: 55,
},
},
}
},
} as IMPConfig;
Toolbar Config Options This setup will define and showcase the active menu items within the toolbar. These items consist of the tag list, object list, minimap, screenshot, and theme picker. Apart from the tag list menu, other items can be optional.
-
menuItems - (optional) By default, all items are active. With this configuration, you can specify menu items that you wish to disable in the toolbar.
- meeting: Allows virtual meetings.
- screenshot: Enables capturing a screenshot of the space.
- models: Allows adding of objects (3D, images, etc.) inside 3D Space.
- minimap: Displays a minimap of your 3D Space.
Example:
const config = {
//Other config values...
toolbarConfig: {
active: isAtwinSideBarEnabled.value,
lang: lang.value,
menuItems: {
meeting: false
}
},
} as IMPConfig;
-
Screenshot config
An optional object for screenshot settings in IMPConfig.
-
visible: An optional boolean indicating if the screenshot functionality is visible. Defaults to
true
. -
withCameraData: An optional boolean specifying if camera data should be included with the screenshot. Defaults to
false
.
-
visible: An optional boolean indicating if the screenshot functionality is visible. Defaults to
Example:
const config = {
//Other config values...
toolbarConfig: {
active: isAtwinSideBarEnabled.value,
lang: lang.value,
menuItems: {
screenshot: {
visible: true,
withCameraData: true,
}
}
},
} as IMPConfig;
Toolbar Theme Config Options This configuration enables customization of the toolbar display within the 3D space.
-
customizations - (optional) Specify the color theme, and position of the toolbar.
- toolbarOffset: Determines the toolbar's position (top, right, bottom, left).
Example:
const config = {
//Other config values...
toolbarConfig: {
active: true,
lang: 'en',
themeConfig: {
customizations: {
toolbarOffset: {
top: 55,
},
},
}
},
} as IMPConfig;
(Optional) This configuration unifies the management of secret keys utilized within the application.
Example:
const config = {
//Other config values...
appConfigKeys:{
embedlyKey: "embedly_key_here"
meetSdkKey?: "zoom_sdk_key_here"
meetSecretKey?: "zoom_secret_key_here"
},
} as IMPConfig;
App Key Config Options
- embedlyKey - This key is for rendering media attachments in tags.
- meetSdkKey - This is the video sdk key.
- meetSecretKey - This is the video sdk secret key.
(Optional) This configuration allows the app to disable certain features inside the Space View. Currently, the configuration supports restricting the tag feature to make tags read-only.
Example:
const config = {
//Other config values...
restrictionConfig: {
isTagReadOnly: false
},
} as IMPConfig;
...
// set to true if restriction is needed
config.restrictionConfig!.isTagReadOnly = true
(Optional) This configuration determines the log levels displayed in the app's console log. If the debug value is not defined, only error logs are shown by default. Valid log levels include trace, warn, error, info, and silent.
Example:
const config = {
//Other config values...
debug:{
logLevel: 'trace'
},
} as IMPConfig;
To activate a toolbar display within your 3D Space, you can set the following key-value pairs in your configuration object.
Example:
const config = {
//Other config values...
toolbarConfig: {
active: true,
lang: 'en', // Supported language: en and ja,
themeConfig: {
customizations: {
toolbarOffset: {
top: 55,
},
},
}
},
} as IMPConfig;
Toolbar Config Options This setup will define and showcase the active menu items within the toolbar. These items consist of the tag list, object list, minimap, screenshot, and theme picker. Apart from the tag list menu, other items can be optional.
-
menuItems - (optional) By default, all items are active. With this configuration, you can specify menu items that you wish to disable in the toolbar.
- meeting: Allows virtual meetings.
- models: Allows adding of objects (3D, images, etc.) inside 3D Space.
- minimap: Displays a minimap of your 3D Space.
Example:
const config = {
//Other config values...
toolbarConfig: {
active: isAtwinSideBarEnabled.value,
lang: lang.value,
menuItems: {
meeting: false
}
},
} as IMPConfig;
Toolbar Theme Config Options This configuration enables customization of the toolbar display within the 3D space.
-
customizations - (optional) Specify the color theme, and position of the toolbar.
- toolbarOffset: Determines the toolbar's position (top, right, bottom, left).
Example:
const config = {
//Other config values...
toolbarConfig: {
active: true,
lang: 'en',
themeConfig: {
customizations: {
toolbarOffset: {
top: 55,
},
},
}
},
} as IMPConfig;
(Optional) This configuration unifies the management of secret keys utilized within the application.
Example:
const config = {
//Other config values...
appConfigKeys:{
embedlyKey: "embedly_key_here"
meetSdkKey?: "zoom_sdk_key_here"
meetSecretKey?: "zoom_secret_key_here"
},
} as IMPConfig;
App Key Config Options
- embedlyKey - This key is for rendering media attachments in tags.
- meetSdkKey - This is the video sdk key.
- meetSecretKey - This is the video sdk secret key.
(Optional) This configuration allows the app to disable certain features inside the Space View. Currently, the configuration supports restricting the tag feature to make tags read-only.
Example:
const config = {
//Other config values...
restrictionConfig: {
isTagReadOnly: false
},
} as IMPConfig;
...
// set to true if restriction is needed
config.restrictionConfig!.isTagReadOnly = true
(Optional) This configuration determines the log levels displayed in the app's console log. If the debug value is not defined, only error logs are shown by default. Valid log levels include trace, warn, error, info, and silent.
Example:
const config = {
//Other config values...
debug:{
logLevel: 'trace'
},
} as IMPConfig;
Displaying the minimap outside the iFrame
There may be instances where you need to display the provided minimap outside of the 3D space displayed by your iFrame. In such cases, you may access the setMap
method of the minimap
object to display the minimap elsewhere. Do take note that there can only be one instance of the minimap displayed at a time. We may add the ability to display multiple minimaps at the same time in future releases.
The setMap method requires the following parameters
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
mpSdk | MpSdk | yes | none | Matterport SDK instance |
appKey | string | yes | none | Your matterport app key |
mapId | string | yes | none | id of the element that will hold the map |
NOTE: You can get the instance of mpSdk by using the getAtwinSdk
method
Here's an example on how to do it.
Step 1: Create an element and give it the id of at-map
<div id="at-map"></div>
Step 2: Run the setMap method and pass the required parameters
import * as atwin from 'architwin'
const sdk = getAtwinSdk()
atwin.minimap.setMap(sdk,'YOUR-APP-KEY','at-map')
Utilize this asynchronous function for disconnecting and efficiently cleaning up resources linked to the connected 3D space. It stops any playing videos, disposes of tags, clears objects and states, and ultimately disconnects while clearing the currently displayed Space.
Function Signature
async function disconnectSpace(): Promise<void>
Example:
import * as atwin from 'architwin'
atwin.disconnectSpace();
This method returns an array of ITag
containing information of all tags in the space.
Function Signature
async function getTags(space: ISpace): Promise<ITag[] | null>;
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
space | ISpace | yes |
Example:
import * as atwin from 'architwin'
const space = /* specify the space object */;
const tags = await atwin.getTags(space);
if (tags) {
console.log('Tags:', tags);
} else {
console.log('No tags found or an error occurred.');
}
This method enables direct navigation to the tag within the space, identified by a specific ID.
Function Signature
async function gotoTag(tagId: string): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
tagId | string | yes | any string |
Example:
import * as atwin from 'architwin'
const tagId = /* specify the tag ID */;
await atwin.gotoTag(tagId);
The renderTag() is used for rendering a tag in the space based on the provided payload.
Function Signature
async function renderTag(payload:
{ tag: MpSdk.Tag.Descriptor },
addTo_tags: boolean = true
): Promise<MpSdk.Tag.TagData>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes | ||
addTo_tags | boolean | no | true | true/false |
Setting of addTo_tags:
- true: Insert the rendered tag into an array that contains all the rendered tags.
- false: Renders the tag but does not insert it into the array containing all the rendered tags.
Example:
import * as atwin from 'architwin'
const payload = {
tag: { /* Define your tag descriptor here */ }
};
try {
const renderedTag = await atwin.renderTag(payload);
console.log('Rendered Tag:', renderedTag);
} catch (error) {
console.error('Error rendering tag:', error);
}
This function retrieves all tags in the space.
Function Signature
function getMpTags(): ITag[]
Example:
import * as atwin from 'architwin'
const tags = atwin.getMpTags();
console.log('Tags:', tags);
// Iterate through the tags and access their properties
tags.forEach(tag => {
console.log('Tag ID:', tag.id);
console.log('Tag Label:', tag.label);
// Add more properties as needed
});
This function is a synchronous function that takes a tagId as its parameter and returns an ITag object with the corresponding ID.
Function Signature
function getMpTag(tagId: string): ITag | undefined
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
tagId | string | yes | valid tag ID |
Example:
import * as atwin from 'architwin'
const tagIdToRetrieve = '123456789'; // Replace with the actual tag ID
const tag = atwin.getMpTag(tagIdToRetrieve);
if (tag) {
console.log('Tag:', tag);
// Access tag properties as needed
console.log('Tag Label:', tag.label);
console.log('Tag Description:', tag.description);
} else {
console.error('Tag not found.');
}
The showTags function is an asynchronous function that takes an array of ITag objects (tags) as its parameter. It processes each tag in the array, performs various operations related to displaying the tags in a specific context. These operations include adding tags, attaching media, and potentially editing tag icons.
Also, this function provides the option to display tags along with tag icons, if desired.
Function Signature
async function showTags(
tags: ITag[],
_withIcon: boolean = false
): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
tags | array | yes | array of ITag | |
_withIcon | boolean | no | false | true/false |
Example:
import * as atwin from 'architwin'
const tagsToDisplay = [
// An array of ITag objects, each representing a tag
// Replace this with your actual tag data
// Example: { json_data: { /* tag data */ } },
// ...
];
// If no tag icon display
try {
await atwin.showTags(tagsToDisplay);
} catch (error) {
console.error('Error displaying tags:', error);
}
// If with tag icon display
try {
await atwin.showTags(tagsToDisplay, true);
} catch (error) {
console.error('Error displaying tags:', error);
}
This method is designed to remove tags from a space. Tags are typically used for annotating or adding information to a 3D space, and this function helps remove those annotations.
Function Signature
async function disposeTags(): Promise<void>
Example:
import * as atwin from 'architwin'
// Example usage of the disposeTags function
async function removeTagsFromSpace() {
try {
console.log("Removing Mattertags from space...");
await atwin.disposeTags();
console.log("Mattertags removed successfully.");
} catch (error) {
console.error("Error removing Mattertags:", error);
}
}
// Call the function to remove Mattertags from the space
removeTagsFromSpace();
Removing a specific tag in the space can be achieved by invoking the disposeTag() method. The disposeTag() method takes a payload as its parameter, which must include a tagId property with a value.
Function Signature
async function disposeTag(payload: { tagId: string }): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
};
try {
await atwin.disposeTag(payload);
console.log('Tag disposed successfully.');
} catch (error) {
console.error('Error disposing the tag:', error);
}
The attachTagMedia
function operates asynchronously, accepting an object payload as its input parameter. Its primary purpose is to link media files to a particular tag identified by its tagId. To achieve this, it retrieves the tag through the getMpTag function and subsequently associates the designated media files.
Function Signature
async function attachTagMedia(payload: {
tagId: string,
attachments: string[]
}): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
attachments: ['media1.jpg', 'media2.jpg'] // Specify the media file paths
};
try {
await atwin.attachTagMedia(payload);
console.log('Media attached to the tag successfully.');
} catch (error) {
console.error('Error attaching media to the tag:', error);
}
In contrary of attachTagMedia(), this asynchronous function available for detaching media attachments from a particular tag, identified by its tagId, using an object payload as its input. The process involves retrieving the tag and subsequently separating the specified media attachments.
Function Signature
async function detachTagMedia(payload: {
tagId: string,
attachmentIds: string[]
}): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
attachmentIds: ['attachment1', 'attachment2'] // Specify the attachment IDs to detach
};
try {
await atwin.detachTagMedia(payload);
console.log('Media detached from the tag successfully.');
} catch (error) {
console.error('Error detaching media from the tag:', error);
}
An asynchronous operation is provided for relocating a specific tag identified by its tagId, with the tagId as its input parameter.
Function Signature
async function moveTag(tagId: string, callback?: Function): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
tagId | string | yes | valid tag ID |
Example:
import * as atwin from 'architwin'
const tagIdToMove = '123456789'; // Replace with the actual tag ID
try {
await atwin.moveTag(tagIdToMove);
console.log('Tag moved successfully.');
} catch (error) {
console.error('Error moving the tag:', error);
}
This asynchronous function is provided to modify the label of a particular tag, identified by its tagId, using an object payload as its parameter.
Function Signature
async function editTagLabel(payload: {
tagId: string,
label: string
})
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
label: 'New Label' // Specify the new label for the tag
};
try {
await atwin.editTagLabel(payload);
console.log('Tag label edited successfully.');
} catch (error) {
console.error('Error editing the tag label:', error);
}
This asynchronous function is available for modifying the description of a designated tag identified by its tagId, with an object payload as its parameter.
Function Signature
async function editTagDescription(payload: {
tagId: string,
description: string
})
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
description: 'New Description' // Specify the new description for the tag
};
try {
await atwin.editTagDescription(payload);
console.log('Tag description edited successfully.');
} catch (error) {
console.error('Error editing the tag description:', error);
}
This function is at your disposal to modify both the icon and color of a particular tag identified by its tagId, using an object payload as its parameter.
Function Signature
async function editTagIcon(payload: {
tagId: string,
icon?: string,
color: MpSdk.Color | string
})
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
icon: 'new-icon.png', // Specify the new icon file path or reference (optional)
color: 'blue' // Specify the new color for the tag
};
try {
await atwin.editTagIcon(payload);
console.log('Tag icon and color edited successfully.');
} catch (error) {
console.error('Error editing the tag icon and color:', error);
}
The editTagStem()
asynchronous function is available for adjusting the visibility of the stem of a specific tag, identified by its tagId, using an object payload as its parameter.
Function Signature
async function editTagStem(payload: {
tagId: string,
stemVisible: boolean
})
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
stemVisible: true // Specify the new stem visibility value
};
try {
await atwin.editTagStem(payload);
console.log('Tag stem visibility edited successfully.');
} catch (error) {
console.error('Error editing the tag stem visibility:', error);
}
This editTagColor
asynchronous function is provided for modifying the color of a particular tag, identified by its tagId, using an object payload as its parameter.
Function Signature
async function editTagColor(payload: {
tagId: string,
color: MpSdk.Color
})
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | { } | yes |
Example:
import * as atwin from 'architwin'
const payload = {
tagId: '123456789', // Replace with the actual tag ID
color: { r: 255, g: 0, b: 0 } // Specify the new color (RGB format)
};
try {
await atwin.editTagColor(payload);
console.log('Tag color edited successfully.');
} catch (error) {
console.error('Error editing the tag color:', error);
}
Retrieve information about the sweeps (viewpoints) within the loaded 3D space using this asynchronous method.
Function Signature
async function getSweeps(): Promise<ISweep[] | null>
Example:
import * as atwin from 'architwin'
const sweeps = await atwin.getSweeps();
if (sweeps) {
console.log('Sweeps:', sweeps);
} else {
console.log('No sweeps found in the loaded space.');
}
This asynchronous function moves the camera location to a specific sweep (viewpoint) within the loaded 3D space.
Function Signature
async function moveToSweep(sweepId: string, rotation?: Vector2): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
sweepId | string | yes | Id of the sweep | |
sweepId | Vector2 | optional | {x,y} |
Example:
import * as atwin from 'architwin'
const sweepId = /* specify the sweep ID */;
await atwin.moveToSweep(sweepId);
console.log('Camera view moved to sweep ' + sweepId);
Retrieve information about nearby sweeps (viewpoints) for a given sweep within the loaded 3D space using this asynchronous function.
Function Signature
async function getNearbySweeps(sweepId: string): Promise<string[] | undefined>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
sweepId | string | yes | Id of the sweep |
Example:
import * as atwin from 'architwin'
const sweepId = /* specify the sweep ID */;
const nearbySweeps = await atwin.getNearbySweeps(sweepId);
console.log('Nearby Sweeps:', nearbySweeps);
Obtain information about the current sweep that the camera view is focused on within the loaded 3D space using this function.
Function Signature
function getCurrentSweep(): ISweep
Example:
import * as atwin from 'architwin'
const currentSweep = atwin.getCurrentSweep();
console.log('Current Sweep:', currentSweep);
Retrieve information about the exact location of the current sweep's position. This function will return sweep's (x,y,z) coordinates.
Function Signature
function getCurrentSweepPosition(): MpSdk.Vector3
Example:
import * as atwin from 'architwin'
const currentSweepPosition = atwin.getCurrentSweepPosition();
console.log('Current Sweep Position:', currentSweepPosition);
This function retrieves all sweep data within the currently loaded space. It will return an array of objects, each containing information about a sweep. Each object includes properties such as id, position, and neighbors.
Function Signature
function getAllSweeps(): {
id: string;
position: Vector3;
neighbors: string[];
}[]
Where:
- id: ID of the sweep
- position: Position of the sweep (Vector3 coordinates)
- neighbors: Array of IDs of the neighboring sweeps
Example:
import * as atwin from 'architwin'
const allSweeps = atwin.getAllSweeps();
console.log('All Sweeps:', allSweeps);
Custom sweep pucks allow you to place a 2D circle or 3D torus as an additional visual indicator in your sweeps. Do take note that the sweep pucks do not replace the existing sweep markers on the space. To add custom sweep pucks to your space simply add the following to your config object that you pass to connectSpace
const config = {
//other configs
sweepPuckConfig: {
shape: 'torus', //either circle or torus. Default is circle
color: '#F7572B' //any valid CSS color value
}
} as IMPConfig
atwin.connectSpace(url,config)
You should be able to see your custom sweep pucks once your space has fully loaded. Do take note that large spaces with numerous sweeps will take time to load all the sweep pucks. Additionally, if you need to have custom colors for each sweep puck then you can pass an array of objects that follows the SweepColor
interface to the color key instead of a string.
Example
const sweepPuckColors = [
{
sweepId: 'jkwbfisbqwr',
backgroundColor: '#000000'
}
//other elements
]
const config = {
//other configs
sweepPuckConfig: {
shape: 'torus', //either circle or torus. Default is circle
color: sweepPuckColors
}
} as IMPConfig
atwin.connectSpace(url,config)
Initiate playback of a video object with a specified ID in the loaded 3D space using this function. It fetches the video object using the provided video ID and starts playback.
Function Signature
function playVideo(videoId: number): void
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
videoId | number | yes | Id of the video |
Example:
import * as atwin from 'architwin'
const videoId = /* specify the video ID */;
atwin.playVideo(videoId);
Pause playback of a video object with a specified ID in the loaded 3D space using this function. It retrieves the video object using the provided video ID and halts its playback.
Function Signature
function pauseVideo(videoId: number): void;
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
videoId | number | yes | Id of the video |
Example:
import * as atwin from 'architwin'
const videoId = /* specify the video ID */;
atwin.pauseVideo(videoId);
This function enables you to control the playback and mute state of an HTML video element by specifying an action. Supported actions include "play," "pause", "mute," and "unmute." The function modifies the playback and mute settings of the provided video element based on the action.
Function Signature
function setVideoPlayback(action: string, element: HTMLVideoElement): void;
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
action | string | yes | 'play' or 'pause' or 'mute' or 'unmute' | |
element | HTMLVideoElement | yes | HTML video element |
Example:
import * as atwin from 'architwin'
const action = "play"; // Specify the desired action
const videoElement = /* Specify the HTML video element */;
atwin.setVideoPlayback(action, videoElement);
Move the camera within the space in a specified direction using this asynchronous function. Supported directions comprise 'LEFT,' 'RIGHT,' 'UP,' 'DOWN,' 'FORWARD,' and 'BACK'.
Function Signature
async function moveInDirection(direction: string): Promise<void>;
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
direction | string | yes | "FORWARD" or "BACK" or "LEFT" or "RIGHT" |
Example
import * as atwin from 'architwin'
const desiredDirection = "LEFT"; // Specify the desired direction
atwin.moveInDirection(desiredDirection)
.then(() => {
console.log("Camera moved successfully!");
})
.catch(() => {
console.error("Error occurred while moving the camera.");
});
Retrieve the current camera pose, including the details about the camera's spatial orientation and position within the space. The camera pose provides details about the camera's spatial location and orientation, allowing you to understand its position in the virtual environment.
Function Signature
function getCurrentCameraPose(): MpSdk.Camera.Pose
Example:
import * as atwin from 'architwin'
const cameraPose = atwin.getCurrentCameraPose();
console.log("Current Camera Pose:", cameraPose);
Retrieve the present camera position within the 3D space using this function. The function provides the coordinates (x, y, z) that signify the camera's placement in the 3D space.
Function Signature
function getCameraPosition(): MpSdk.Vector3
Example:
import * as atwin from 'architwin'
const cameraPosition = atwin.getCameraPosition();
console.log("Current Camera Position:", cameraPosition);
Pan the camera view adjustments by specifying rotation angles along both the horizontal and vertical axes using this function. The panning action simulates looking sideways left and right (horizontal) and looking up and down (vertical).
Function Signature
async function cameraPan(x: number, z: number): Promise<void>;
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
x | number | yes | number of degrees will pan the camera to the right | |
y | number | yes | number of degrees will tilt the camera upward |
Example:
import * as atwin from 'architwin'
// Pan the camera by 30 degrees to the right and tilt by 10 degrees upward
atwin.cameraPan(30, 10)
.then(() => {
console.log("Camera pan success");
})
.catch((error) => {
console.error("Camera pan error:", error);
});
This function allows you to rotate the camera's view by specifying rotation angles along the horizontal and vertical axes. The rotation action simulates changing the direction the camera is facing.
Function Signature
async function cameraRotate(x: number, y: number, speed: number): Promise<void>;
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
x | number | yes | number of degrees will pan the camera to the right | |
y | number | yes | number of degrees will tilt the camera upward | |
speed | number | yes | number of second will camera animate to specified angle ( x , y) |
Example:
import * as atwin from 'architwin'
// Rotate the camera by 45 degrees horizontally and 15 degrees vertically at a speed of 0.5
cameraRotate(45, 15, 0.5)
.then(() => {
console.log("Camera rotate success");
})
.catch((error) => {
console.error("Camera rotate error:", error);
});
Obtain the existing view mode of the Matterport scene using this function. The view mode illustrates the manner in which the scene is presented, which includes 3D walkthrough mode, dollhouse mode, or floor plan mode.
Function Signature
function getViewMode(): MpSdk.Mode.Mode
Example:
import * as atwin from 'architwin'
const currentViewMode = atwin.getViewMode();
console.log("Current view mode:", currentViewMode);
Change the current view mode of the 3D space scene to the designated mode using this function. The chosen view mode dictates the presentation style of the space, including options like 3D walkthrough mode, dollhouse mode, or floor plan mode.
Function Signature
async function setViewMode(mode: string): Promise<void>;
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
mode | string | yes | "dollhouse" or "floorplan" or "inside" or "outside" or "transitioning" |
Example:
import * as atwin from 'architwin'
async function changeToDollhouseMode() {
await atwin.setViewMode("dollhouse");
console.log("Changed to Dollhouse mode");
}
This function adjusts the camera's view to focus on a specific point in the Matterport scene. The point is defined in screen coordinates, where x and y represent the pixel coordinates from the upper-left corner of the screen.
Function Signature
async function cameraLookAt(x: number, y: number): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
x | number | yes | Horizontal position, in pixels. Starting from the canvas' top left corner. | |
y | number | yes | Vertical position, in pixels. Starting from the canvas' top left corner. |
Example
import * as atwin from 'architwin'
async function focusOnPoint(x, y) {
await atwin.cameraLookAt(x, y);
console.log("Camera focused on point", x, y);
}
This function takes a screenshot (JPEG) of the user’s current space view. It creates a temporary download link for the screenshot image with the filename 'image.png', and then triggers the download.
Function Signature
async function captureSpaceScreenshot(callback?: Function | null, resolution?: Renderer.Resolution, visibility?: Renderer.Visibility): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
resolution | Renderer.Resolution | optional | { width : 1920, height : 1080 } | { width : 600, height : 800 } or any values exceed to 4096 |
visibility | Renderer.Visbility | optional | { mattertags : false, measurements : false, sweeps: false, views : false } | {mattertags : true, measurements : false, sweeps: false, views : true} |
callback | Function | optional |
Example:
import * as atwin from 'architwin'
async function captureSpace() {
// The desired resolution for the screenshot. For example: {width: 1920, height: 1080} If no resolution is specified, then the resolution of the size of Showcase (the current window or the iframe embed) is used. Maximum 4096 x 4096.
const resolution = {
width : 1920,
height : 1080
}
// Toggles certain scene objects such as Mattertag Posts and sweep markers. If no visibility object is specified, then all scene objects are hidden.
const visibility = {
mattertags : true,
measurements : false,
sweeps: true,
views : false
}
// With Parameters:
await atwin.captureSpaceScreenshot(resolution, visibility);
// Without Parameters
await atwin.captureSpaceScreenshot();
}
This function captures a screenshot of a virtual space and retrieves details about the camera's position and rotation at the time of the capture. It is designed to provide an easy way to get both a visual snapshot and the camera's state.
Function Signature
function captureScreenshotAndCameraDetails(callback?: Function | null, resolution?: Renderer.Resolution, visibility?: Renderer.Visibility, iframeId?: string): Promise<{
base64Screenshot: string;
cameraPose: MpSdk.Camera.Pose;
}>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
callback | Function | optional | ||
resolution | Renderer.Resolution | optional | { width : 1920, height : 1080 } | { width : 600, height : 800 } or any values exceed to 4096 |
visibility | Renderer.Visbility | optional | { mattertags : false, measurements : false, sweeps: false, views : false } | {mattertags : true, measurements : false, sweeps: false, views : true} |
iframeId | string | optional |
Example:
import * as atwin from 'architwin'
async function captureScreenshotAndCameraDetails() {
// The desired resolution for the screenshot. For example: {width: 1920, height: 1080} If no resolution is specified, then the resolution of the size of Showcase (the current window or the iframe embed) is used. Maximum 4096 x 4096.
const resolution = {
width : 1920,
height : 1080
}
// Toggles certain scene objects such as Mattertag Posts and sweep markers. If no visibility object is specified, then all scene objects are hidden.
const visibility = {
mattertags : true,
measurements : false,
sweeps: true,
views : false
}
// With Parameters:
const screenshotDetails = await atwin.captureScreenshotAndCameraDetails(resolution, visibility);
log.info("Screenshot Details: ", screenshotDetails)
// Without Parameters
const screenshotDetails = await atwin.captureScreenshotAndCameraDetails();
log.info("Screenshot Details: ", screenshotDetails)
// With iframe id
const screenshotDetails = await atwin.captureScreenshotAndCameraDetails(iframeId: 'iframe-id');
log.info("Screenshot Details: ", screenshotDetails)
}
The getNearbyObjects() method retrieves nearby rendered objects based on a given payload containing type and distance parameters. It calculates the distance between the camera position and the objects' positions and returns a categorized list of nearby objects.
Function Signature
function getNearbyObjects(payload: NearbyPayload): NearbyObjects
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | NearbyPayload | yes | none | '3DX' or 'SLIDESHOW' or 'VIDEO' |
Example:
import * as atwin from 'architwin'
...
const payload = {
type: "ALL",
distance: 10
} as NearbyPayload
// gets ALL object types within a 10 meter range
const nearByObjects:NearbyObjects = atwin.getNearbyObjects(payload)
...
The addMediaScreen() method is asynchronous function allows you to add a media screen to the space. The media screen displays a media content specified by the mediaUrl parameter. You can customize the media screen's position, scale, and rotation using the transform parameter. Additional options such as readonly mode and autoplay can also be configured. This function logs information about the provided parameters and performs media handling.
Function Signature
async function addMediaScreen(
mediaUrl?: string,
transform?: { position: Vector3, scale: Vector3, rotation: Vector3 },
readonly?: boolean,
autoplay?: boolean
): Promise<IShowcaseObject>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
mediaUrl | string | no | ||
transform | { position: Vector3, scale: Vector3, rotation: Vector3 } | no | ||
readonly | boolean | no | ||
autoplay | boolean | no |
Example:
import * as atwin from 'architwin'
const mediaUrl = 'https://example.com/media/sample.mp4';
const transform = {
position: new Vector3(0, 0, 0),
scale: new Vector3(1, 1, 1),
rotation: new Vector3(0, 0, 0)
};
const readonly = true;
const autoplay = false;
awtwin.addMediaScreen(mediaUrl, transform, readonly, autoplay)
.then(showcaseObject => {
console.log('Media screen added:', showcaseObject);
})
.catch(error => {
console.error('Error adding media screen:', error);
});
The setTransformMode() asynchronous void function sets the transform mode for a specific type of transformation. The mode parameter defines the transformation mode, which can be translation, rotation, or scaling.
Function Signature
async function setTransformMode(mode: TRANSFORM_TYPE | string): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
mode | TRANSFORM_TYPE or string | yes | none | 'translate' or 'scale' or 'rotate' |
Example:
import * as atwin from 'architwin'
const desiredMode = TRANSFORM_TYPE.ROTATE;
atwin.setTransformMode(desiredMode)
.then(() => {
console.log('Transform mode set successfully:', desiredMode);
})
.catch(error => {
console.error('Error setting transform mode:', error);
});
The revertTransform() function allows you to revert transformations applied to a selected object. The function retrieves previous or next transformation data from the history, applies it to the selected object, and updates the internal state.
Function Signature
function revertTransform(action: string = 'undo'): boolean
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
action | string | yes | none | 'undo' or 'redo' |
Example:
import * as atwin from 'architwin'
// Revert to the previous state
if (awtwin.revertTransform('undo')) {
console.log('Reverted to previous state.');
} else {
console.log('No further undo actions available.');
}
// Reapply a reverted state
if (atwin.revertTransform('redo')) {
console.log('Reapplied a reverted state.');
} else {
console.log('No further redo actions available.');
}
Use this function to remove transformation controls and associated components from the scene. It stops the transformation control node and potentially cancels any input control component, if available. The function ensures that the transformation controls are properly removed to maintain the integrity of the scene.
Function Signature
function removeTransformControls(): void
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
none | none | none | none | none |
Example:
import * as atwin from 'architwin'
atwin.removeTransformControls();
This function is used to set the animation state of a specific model object in the scene. It allows you to play or stop the animation associated with the specified model using the provided action parameter. The function locates the animation state path corresponding to the given modelId and updates it accordingly.
Function Signature
function setAnimationState(action: string, modelId: number): void
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
action | string | yes | none | 'play' or 'stop' |
modelId | number | yes | none | ID of the model |
Example:
import * as atwin from 'architwin'
const action = 'play';
const modelId = 123;
setAnimationState(action, modelId);
Use this function to display the dimensions of a chosen object within a 3D space. The function computes the object's width, height, and depth through its bounding box and showcases this data as 3D text labels strategically positioned around the object.
Function Signature
function showObjectDimensions(selected: IObjectData): void
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
selected | IObjectData | yes |
Example:
import * as atwin from 'architwin'
atwin.showObjectDimensions(selectedObject)
Generate a duplicate of a showcase object asynchronously, with the option to include positional and rotational offsets. The function generates a fresh ID for the duplicated object, applies provided positional and rotational adjustments, and integrates the object into the scene.
Function Signature
async function copyObject(
payload: IShowcaseObject,
position_offset: Vector3 = undefined,
rotation_offset: Vector3 = undefined
): Promise<IShowcaseObject>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | IShowcaseObject | yes | ||
position_offset | Vector3 | yes | undefined | |
rotation_offset | Vector3 | yes | undefined |
Example:
import * as atwin from 'architwin'
const objectToCopy = /* the object to be copied */;
const positionOffset = new Vector3(1, 0, 1);
const rotationOffset = new Vector3(0, Math.PI / 2, 0);
atwin.copyObject(objectToCopy, positionOffset, rotationOffset)
.then(copiedObject => {
console.log('Object copied:', copiedObject);
})
.catch(error => {
console.error('Error copying object:', error);
});
Use asynchronous function to delete an existing 3D object. The deletion target is determined by the id
parameter value.
Function Signature
async function deleteObject(id: number): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
id | number | yes |
Example:
import * as atwin from 'architwin'
const objectId = /* specify the object's ID */;
atwin.deleteObject(objectId)
.then(() => {
console.log('Object deleted successfully.');
})
.catch(error => {
console.error('Error deleting object:', error);
});
To remove a designated object from a 3D space use deleteObjectFromSpace(). Provide an IObjectData
object as input, and the function will eliminate the object from the scene. Additionally, it undertakes essential cleanup tasks like halting animations and removing linked markup elements.
Function Signature
async function deleteObjectFromSpace(target: IObjectData): Promise<number>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
target | IObjectData | yes |
Example:
import * as atwin from 'architwin'
const targetObject = /* specify the target object */;
atwin.deleteObjectFromSpace(targetObject)
.then(deletedObjectId => {
console.log(`Object with ID ${deletedObjectId} deleted from the space.`);
})
.catch(error => {
console.error('Error deleting object:', error);
});
To replace a particular object within a 3D space with a fresh one use replaceObject() method. Provide an I3DObject
payload for the new object, an IObjectData target for the object to be replaced, and optional configuration choices. The function eliminates the target object from the scene and introduces the new object in its designated position.
Function Signature
async function replaceObject(payload: I3DObject, target: IObjectData, options: Object = null): Promise<IShowcaseObject>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | I3DObject | yes | ||
target | IObjectData | yes | ||
options | Object | yes | null |
Example:
import * as atwin from 'architwin'
const newObjectPayload = /* specify the new object's payload */;
const targetObject = /* specify the target object to be replaced */;
const replacementOptions = /* specify optional replacement options */;
atwin.replaceObject(newObjectPayload, targetObject, replacementOptions)
.then(replacedObject => {
console.log('Object replaced:', replacedObject);
})
.catch(error => {
console.error('Error replacing object:', error);
});
To introduce a text markup screen into the 3D space use the addTextMarkupScreen() method. The function generates a 3D object based on the supplied title and message. The screen's placement, scaling, and rotation align with the designated transformation parameters.
Function Signature
async function addTextMarkupScreen(
title: string = '',
message: string,
textScreenName: string,
transform: { position: Vector3, scale: Vector3, rotation: Vector3 },
textColor: string = 'black',
backgroundColor: string = '#fff'
): Promise<IShowcaseObject>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
title | string | yes | ' ' | |
message | string | yes | ||
textScreenName | string | yes | ||
transform | { position: Vector3, scale: Vector3, rotation: Vector3 } | yes | ||
textColor | string | yes | 'black' | |
backgroundColor | string | yes | '#fff' |
Example:
import * as atwin from 'architwin'
To set the content of a text markup screen within a 3D space use the setTextMarkupScreenContent(). The function modifies multiple properties of the screen, including its title, text content, text color, and background color.
Function Signature
function setTextMarkupScreenContent(
showcase_id: number,
title: string = '',
text: string = '',
textColor: string = '',
backgroundColor: string = ''
): void
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
showcase_id | number | yes | ' ' | |
title | string | yes | ' ' | |
text | string | yes | ' ' | |
textColor | string | yes | ' ' | |
backgroundColor | string | yes | ' ' |
Example:
import * as atwin from 'architwin'
const showcaseId = /* specify the showcase ID */;
const newTitle = 'New Title';
const newText = 'Updated content.';
const newTextColor = 'blue';
const newBackgroundColor = 'white';
atwin.setTextMarkupScreenContent(showcaseId, newTitle, newText, newTextColor, newBackgroundColor);
The getNearestSweepFromObject method will calculates the distance between the object's position and each sweep's position and returns the ID and index of the closest sweep.
Function Signature
function getNearestSweepFromObject(objectId: number): { sweepId: string, index: number } | undefined
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
objectId | number | yes |
Example:
import * as atwin from 'architwin'
const objectIdToFind = 123; // Replace with the actual object ID
const nearestSweep = atwin.getNearestSweepFromObject(objectIdToFind);
if (nearestSweep) {
console.log('Nearest Sweep ID:', nearestSweep.sweepId);
console.log('Nearest Sweep Index:', nearestSweep.index);
} else {
console.error('No nearest sweeps found for the object.');
}
Stores the selected object captured by the ClickSpy class attached to the object upon creation in show3dObjects() function. ClickSpy is not attached if viewMode is set to public. Please take note that you cannot set an object as selected if it has not been rendered into the 3D space.
Function Signature
function setSelectedObject(data: IShowcaseObject, node: Scene.INode, component: Scene.IComponent, type: string): void
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
data | IShowcaseObject | yes | The data of the showcase object | |
node | Scene.INode | yes | The node of the object | |
component | Scene.IComponent | yes | The component of the object | |
type | string | yes | The type of the object |
Example:
import * as atwin from 'architwin'
const spaceObject: IShowcaseObject = {id: 123, showcase_id: 123,...}; // Replace with the actual showcase object data
const selectedObjectPayload = atwin.get3DXObjects().find((obj) => obj.object.id == spaceObject.id)
if (selectedObjectPayload && selectedObjectPayload.type) {
atwin.setSelectedObject(selectedObjectPayload.object, selectedObjectPayload.node, selectedObjectPayload.component, selectedObjectPayload.type)
}
Returns information about the selected object.
Function Signature
function getSelectedObject(): IObjectData
Example:
import * as atwin from 'architwin'
const selectedObj = atwin.getSelectedObject()
console.log("Selected object: ", selectedObj)
This function clears the current selected object and sets it to null.
Function Signature
function clearSelectedObject(): void
Example:
import * as atwin from 'architwin'
atwin.clearSelectedObject()
This function will navigate and move to the object's position.
Function Signature
function goToModel(objectId: number): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
objectId | numer | yes | ID of the object |
Example:
import * as atwin from 'architwin'
const objectId = 123 // Replace with the actual object id
await atwin.goToModel(objectId)
Returns array of objects, each conforming to the IObjectData data type.
Function Signature
function get3DXObjects(): Array<IObjectData>
Example:
import * as atwin from 'architwin'
const objects = atwin.get3DXObjects();
// Now 'objects' contains an array of 3D objects
This function will set or update a library of 3D models asynchronously.
Function Signature
function setLibrary(libraryModels: Array<I3DObject>): Promise<Array<I3DObject>>
Parameter Table
parameter | type | required | values |
---|---|---|---|
libraryModels | Array | yes |
Example:
import * as atwin from 'architwin'
const libraryModels = [{ // Replace with actual data
id: '123',
upload_file: 'PNG',
upload_filename: 'test'
}];
await atwin.setLibrary(libraryModels)
.then(updatedLibrary => {
// Handle the updated library of 3D objects
})
.catch(error => {
// Handle any errors that occurred during the asynchronous operation
});
This function serves the purpose of retrieving a library of 3D objects, possibly with the option to refetch the library if needed. Returns array of objects, each conforming to the IObjectData data type.
Function Signature
function getLibrary(refetch?: boolean): Promise<Array<I3DObject>>
Parameter Table
parameter | type | required | values |
---|---|---|---|
refetch | boolean | optional | true or false |
Example:
import * as atwin from 'architwin'
// Refetch is not needed
await atwin.getLibrary()
// Refetch is needed
await atwin.getLibrary(true)
.then(library => {
// Handle the retrieved library of 3D objects
})
.catch(error => {
// Handle any errors that occurred during the asynchronous operation
});
This function handles the disposal or cleanup of a specific 3D object asynchronously.It returns a promise that resolves to the object ID of the disposed target.
Function Signature
function disposeModel(target: IObjectData): Promise<number>
Parameter Table
parameter | type | required | values |
---|---|---|---|
target | IObjectData | yes |
Example:
import * as atwin from 'architwin'
await atwin.disposeModel(target)
.then(objectID => {
// Handle the disposal process completion, possibly based on the returned object ID
})
.catch(error => {
// Handle any errors that occurred during the disposal process
});
Facilitates the creation of a virtual meeting within the specified 3D space. It allows the host to provide details such as the meeting topic, and participant name. Meeting password is auto-generated upon creation.
Function Signature
function createMeeting(topic: string, base_url: string): Promise<IMeeting>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
topic | string | yes | The name or topic of the meeting | |
base_url | string | yes | The base URL of the application |
Example:
import * as atwin from 'architwin'
// create meeting
const topic = "Space Introduction"
const baseUrl = window.location.href
await atwin.meet.createMeeting(topic, baseUrl)
A method by which a participant gains access to an existing virtual conference. This involves receiving a meeting link from the host and using it to enter the virtual conference environment.
Function Signature
function joinMeeting(payload: IMeetingPayload): Promise<boolean>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
payload | IMeetingPayload | yes |
IMeetingPayload has data of:
- topic : string - The topic of the meeting.
- password : string - Password of the meeting.
- role : string - Participant's role: HOST or GUEST.
- participant_fullname : string - Participant's name.
Example:
import * as atwin from 'architwin'
// Replace with actual meeting payload data
const meetingPayload: IMeetingPayload = {
topic: 'Space Introduction',
password: '1234',
role: 'HOST',
participant_fullname: 'Adam'
}
// join meeting
await atwin.meet.joinMeeting(meetingPayload);
This method allows participants to exit an ongoing virtual meeting. This functionality ensures that users can gracefully disconnect from a meeting without disrupting other participants.
Function Signature
function leaveMeeting(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.leaveMeeting();
This method is used to activate a participant's video feed, allowing others in the meeting to see them.
Function Signature
function startVideo(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.startVideo();
This method deactivates the participant's camera, halting the transmission of their video feed to other meeting participants.
Function Signature
function stopVideo(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.stopVideo();
This method is used to activate a participant's local camera feed, capturing video from the participant's device's built-in camera.
Function Signature
function startLocalVideo(VideoElement?: HTMLVideoElement | null): Promise<boolean>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
VideoElement | HTMLVideoElement | optional | HTMLVideoElement of local video canvas |
Example:
import * as atwin from 'architwin'
// With Video Element
// Replace with actual video element
let premeetVideo: HTMLVideoElement;
premeetVideo = document.getElementById("at-premeet-video") as HTMLVideoElement;
await atwin.meet.startLocalVideo(premeetVideo);
// Without Video Element
await atwin.meet.startLocalVideo();
This method is used to deactivate or pause the transmission of a participant's video feed captured from their local camera.
Function Signature
function stopLocalVideo(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.stopLocalVideo();
This method activates the microphone of the participant.
Function Signature
function startAudio(): Promise<void>
Example:
import * as atwin from 'architwin'
await atwin.meet.startAudio();
This method deactivates the microphone of the participant.
Function Signature
function stopAudio(): Promise<void>
Example:
import * as atwin from 'architwin'
await atwin.meet.stopAudio();
This method allows participants to temporarily disable their microphone, preventing their audio from transmitting to other participants in the meeting.
Function Signature
function muteAudio(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.muteAudio();
This method allows participants to enable their microphone after muting it, thereby restoring the transmission of their audio to other participants in the meeting.
Function Signature
function unMuteAudio(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.unMuteAudio();
This method allows a participant to disable their microphone locally on their device. Unlike muting audio universally, which affects all participants, muting local audio only affects the participant who initiates it.
Function Signature
function muteLocalAudio(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.muteLocalAudio();
This method reactivates the participant's microphone on their local device.
Function Signature
function unMuteLocalAudio(): Promise<boolean>
Example:
import * as atwin from 'architwin'
await atwin.meet.unMuteLocalAudio();
This method retrieves information about the audio and video devices available on your computer. This includes listing all connected microphones, speakers, and cameras.
Function Signature
function getDevices(): Promise<{
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}>
Example:
import * as atwin from 'architwin'
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
let activeMic: MediaDevice
let activeCamera: MediaDevice
let activeSpeaker: MediaDevice
try {
// get mounted devices
mountedDevices = await atwin.meet.getDevices();
// get active devices
activeMic = mountedDevices.mics[0];
activeCamera = mountedDevices.cameras[0];
activeSpeaker = mountedDevices.speakers[0];
} catch (error) {
console.error("getMountedDevices error: ", error);
}
This method allows participants to change the microphone input source on their device during a meeting.
Function Signature
function switchMicrophone(deviceId: string): Promise<void>
Example:
import * as atwin from 'architwin'
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
// get mounted devices
mountedDevices = await atwin.meet.getDevices();
let activeMic: MediaDevice
// Assume selectedAudio value is an item from mountedDevices mics list
for (let item in mountedDevices.mics) {
if(mountedDevices.mics[item].deviceId == selectedAudio){
activeMic = mountedDevices.mics[item];
await atwin.meet.switchMicrophone(activeMic.deviceId)
}
}
Thnis method allows participants to change the output audio device, typically speakers or headphones, during a meeting.
Function Signature
function switchSpeaker(deviceId: string): Promise<void>
Example:
import * as atwin from 'architwin'
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
// get mounted devices
mountedDevices = await atwin.meet.getDevices();
let activeSpeaker: MediaDevice
// Assume selectedSpeaker value is an item from mountedDevices speakers list
for (let item in mountedDevices.speakers) {
if(mountedDevices.speakers[item].deviceId == selectedSpeaker){
activeSpeaker = mountedDevices.speakers[item];
await atwin.meet.switchSpeaker(activeSpeaker.deviceId)
}
}
This method allows users to change their video input source during a meeting. This feature lets users switch between different cameras connected to their device, such as built-in webcams, external USB cameras, or other video input devices.
Function Signature
function switchCamera(deviceId: string): Promise<void>
Example:
import * as atwin from 'architwin'
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
// get mounted devices
mountedDevices = await atwin.meet.getDevices();
let activeCamera: MediaDevice
// Assume selectedCamera value is an item from mountedDevices cameras list
for (let item in mountedDevices.cameras) {
if(mountedDevices.cameras[item].deviceId == selectedCamera){
activeCamera = mountedDevices.cameras[item];
await atwin.meet.switchCamera(activeCamera.deviceId)
}
}
This method retrieves a list of all available microphones connected to the user's device.
Function Signature
function getMicList(): Promise<MediaDevice[]>
Example:
import * as atwin from 'architwin'
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
mountedDevices.mics = await atwin.meet.getMicList();
This method retrieves a list of all available audio output devices, such as speakers and headphones, connected to the user's device.
Function Signature
function getSpeakerList(): Promise<MediaDevice[]>
Example:
import * as atwin from 'architwin'
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
mountedDevices.speakers = await atwin.meet.getSpeakerList();
This method retrieves a list of all available cameras connected to the user's device.
Function Signature
function getCameraList(): Promise<MediaDevice[]>
Example:
import * as atwin from 'architwin'
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
mountedDevices.cameras = await atwin.meet.getCameraList();
This method initializes and creates a video track from the user's local camera. If no deviceId is provided, it defaults to the primary camera. This function returns a promise that resolves to an object containing the created localVideoTrack
and a boolean isVideoOn
indicating the status of the video.
Function Signature
function createLocalVideoTrack(deviceId?: string): Promise<{
localVideoTrack: LocalVideoTrack;
isVideoOn: boolean;
}>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
deviceId | string | optional | ID of the device |
Example:
import * as atwin from 'architwin'
// Variables
let activeCamera: MediaDevice
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
let localVideo: {
localVideoTrack: LocalVideoTrack;
isVideoOn: boolean;
}
// get devices
mountedDevices = await atwin.meet.getDevices();
// set active camera
activeCamera = mountedDevices.cameras[0];
// create local video track
localVideo = await atwin.meet.createLocalVideoTrack(activeCamera.deviceId);
This method initializes and creates an audio track from the user's local microphone. If no deviceId or deviceType is provided, it defaults to the primary microphone. It returns a promise that resolves to an object containing the localAudioTrack
and a boolean isMuted
indicating if the audio is muted.
Function Signature
function createLocalAudioTrack(deviceId?: string, deviceType?: string): Promise<{
localAudioTrack: LocalAudioTrack;
isMuted: boolean;
}>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
deviceId | string | optional | ID of the device | |
deviceType | string | optional | Type of audio device |
Example:
import * as atwin from 'architwin'
// Variables
let activeMic: MediaDevice
let mountedDevices: {
mics: MediaDevice[];
speakers: MediaDevice[];
cameras: MediaDevice[];
}
let localAudio: {
localAudioTrack: LocalAudioTrack;
isMuted: boolean;
}
// get devices
mountedDevices = await atwin.meet.getDevices();
// set active camera
activeMic = mountedDevices.mics[0];
// create local video track
localAudio = await atwin.meet.createLocalAudioTrack(activeMic.deviceId);
This method reactivates the participant's microphone on their local device.
Function Signature
function initializeHTMLElements(
videoElement: HTMLVideoElement | null,
canvasElement: HTMLCanvasElement | null,
paticipantCanvas: HTMLCanvasElement | null): Promise<void>
Parameter Table
parameter | type | required | default | values |
---|---|---|---|---|
videoElement | HTMLVideoElement | yes | null | (self) Local video element |
canvasElement | HTMLCanvasElement | yes | null | (self) Local canvas element |
paticipantCanvas | HTMLCanvasElement | yes | null | (remote) Participant canvas element |
Example:
import * as atwin from 'architwin'
// Replace with actual HTML elements
const videoElement = document.getElementById("at-self-video") as HTMLVideoElement;
const canvasElement = document.getElementById("at-self-canvas") as HTMLCanvasElement;
const participantCanvas = document.getElementById("at-participant-canvas") as HTMLCanvasElement;
await atwin.meet.initializeHTMLElements(videoElement, canvasElement, participantCanvas);