Developer

Appearance

General

rooomSpaces Viewer API general functions for 3D virtual environments. Load interactive spaces, control navigation, take screenshots, manage fullscreen, and handle space viewer lifecycle.

Core Viewer Control ​

load ​

load(spaceId: string, [callback: Function])

Loads a virtual space by ID.

js
api.load('SPACE_ID', function(){
  console.log('Space loaded');
});

start ​

start([callback: Function])

Starts the viewer and initializes the 3D environment.

js
api.start(function(){
  console.log('Viewer started successfully');
});

stop ​

stop([callback: Function])

Stops the viewer and cleans up resources. Use this when you need to completely shut down the viewer instance.

js
api.stop(function(){
  console.log('Viewer stopped');
});

getViewerId ​

getViewerId([callback: Function])

Returns the current viewer ID (token) that identifies this viewer instance.

js
api.getViewerId(function (id) {
  console.log('Viewer ID is', id);
});

Rendering Control ​

startRender ​

startRender([callback: Function])

Starts the rendering loop for the 3D scene. This enables continuous updates and animations in the virtual environment.

js
api.startRender(function(){
  console.log('Rendering started');
});

stopRender ​

stopRender([callback: Function])

Stops the rendering loop to pause all visual updates. This can be used to save performance when the viewer is not actively being viewed.

js
api.stopRender(function(){
  console.log('Rendering stopped');
});

Screenshot & Visual ​

getScreenshot ​

getScreenshot(size: [width: number, height: number] | number, callback: Function, [fileType: string])

Takes a screenshot of the current viewer state and returns it as a base64 data URL.

js
api.getScreenshot([1920, 1080], function(base64) {
  console.log('Screenshot captured:', base64);
  downloadImage(base64, 'space-screenshot.png');
});
js
api.getScreenshot([400, 300], function(base64) {
  document.getElementById('thumbnail').src = base64;
}, 'jpg');

pickColor ​

pickColor(position: [x: number, y: number], [callback: Function])

Returns the color value at the specified screen coordinates as a hex color string.

js
api.pickColor([100, 200], function(color){
  console.log('Color at position:', color); // "#ff0000"
});

Focus & Interaction ​

setCanvasFocus ​

setCanvasFocus([callback: Function])

Sets the focus on the viewer canvas element, enabling keyboard and mouse interactions.

js
api.setCanvasFocus(function(){
  console.log('Canvas focus set - ready for user input');
});

Coordinate Conversion ​

getWorldToScreenCoordinates ​

getWorldToScreenCoordinates(coords: [x: number, y: number, z: number], [callback: Function])

Converts 3D world coordinates to 2D screen coordinates.

js
api.getWorldToScreenCoordinates([1, 1, 1], function(screenCoords) {
  console.log('Screen position:', screenCoords); // [100, 200]
});

getScreenToWorldCoordinates ​

getScreenToWorldCoordinates(coords: [x: number, y: number], [callback: Function])

Converts 2D screen coordinates to 3D world coordinates.

js
api.getScreenToWorldCoordinates([100, 200], function(worldCoords) {
  console.log('World position:', worldCoords); // [1, 1, 1]
});

Best Practices ​

Essential Functions for Every Implementation:

  1. load() - Initialize your space
  2. start() - Begin the viewer experience
  3. getScreenshot() - Capture the current view
  4. setCanvasFocus() - Ensure proper user interaction

Performance Optimization:

  • Use stopRender() when viewer is not visible to save resources
  • Call startRender() to resume animations
  • Use coordinate conversion for efficient UI positioning

User Experience:

  • Call setCanvasFocus() after closing modals to restore keyboard/mouse input
  • Use pickColor() for interactive color-based features