SXRWeb Standalone A-Frame Plugin

10min
This document explains how to use the Sense of Space hologram A-Frame component and how to use the standalone A-Frame integration. 
This guide is only for use with the Hologram format .sxrweb, and not the SxrWeb Geometry Streaming.
A-Frame Usage
Make sure the hologram component is available. You can get from https://assets.senseofspace.io/jsplugins/1.0.15/soshologram_aframe.js﻿
e.g. <script src="https://assets.senseofspace.io/jsplugins/1.0.15/soshologram_aframe.js"></script>
After you have the code available, you can add an aframe component for the hologram as follows
HTML
<a-entity soshologram="source:https://stream.senseofspace.io/myname/myhologram/hologram.sxrweb" id="hologram1"></a-entity>
<a-entity soshologram="source:https://stream.senseofspace.io/myname/myhologram/hologram.sxrweb" id="hologram1"></a-entity>
﻿
The soshologram component has the following paramters:
source: the url of the hologram file
use8thWallSource: set this to true if your source is stored in 8thwall and you want to use 8th wall's require function to get the final url of the source. The default value is false.
autoinit: automatically initialize the hologram. The default value is true.
loop: loop the volumetric video clip. The default value is true.
mutedautoplay: automatically start the playback of the volumetric video in a muted state. The defalt value is false.
autodecode: automatically start decoding the stream when the hologram is initialized. The default value is true.
Controlling the holograms
You can control the hologram(s) with javascript code using a global object called sosHologramContext
sosHologramContext has the following functions:
switchToHologram(hologram_id, autoplay): Stops all holograms and activates the hologram with the id given in hologram_id
getActiveHolograms(): Returns a list of all active hologram objects
playActiveHolograms(): Plays all active holograms
pauseActiveHolograms(): Pauses all active holograms
activateHologram(hologram_id, autoplay): Activates the hologram with the id hologram_id
stopAll(): Stops (deactivates) all hologras
getHologramObject(hologram_id): Returns the hologram object of the hologram with the id hologram_id
Example:
JS
// stop, deactivate, and hide all holograms
sosHologramContext.stopAll();

// Reload and start playing hologram with id hologram1 (see above)
sosHologramContext.activateHologram("hologram1", true);

// After 10 seconds switch to hologram2
setTimeout(() => {sosHologramContext.switchToHologram("hologram2", true)}, 10000);

// After 20 seconds pause the hologram
setTimeout(() => {sosHologramContext.pauseActiveHolograms()}, 20000);
// stop, deactivate, and hide all holograms
sosHologramContext.stopAll();

// Reload and start playing hologram with id hologram1 (see above)
sosHologramContext.activateHologram("hologram1", true);

// After 10 seconds switch to hologram2
setTimeout(() => {sosHologramContext.switchToHologram("hologram2", true)}, 10000);

// After 20 seconds pause the hologram
setTimeout(() => {sosHologramContext.pauseActiveHolograms()}, 20000);
﻿
﻿
To access the details of the playback of a single hologram you can get the hologram object and control that hologram specifically. Example:
JS
let hologram = sosoHologramContext.getHologramObject("hologram1");
hologram.playHologram(true);
let hologram = sosoHologramContext.getHologramObject("hologram1");
hologram.playHologram(true);
﻿
﻿
The hologram object has the following member functions:
playHologram(): play the hologram.
pauseHologram(): pause the hologram.
getMesh(): return the threejs mesh used by the hologram.
setQuality(integer): Set the hologram quality if not using adaptive streaming (0,1 or 2).
disposeData(): free resources if the hologram is no more used.
decodeData(): start decoding of the geometric data. Only available if autodecode is set to false in soshologram.
getVideoElement(): returns the video element containing the texture of the hologram.
mute()
unmute()
﻿
Additionally the user can define the following (callback) functions in the hologram object to customize the hologram:
createCustomMaterial(ThreeJsTexture): Define your own Threejs material if you wish to use e.g. a custom shader instead of the default shading.
onInitialized(): called when the hologram initialization is done, and it’s ready to be accessed.
onPlayable(): called when hologram is ready to be played.
onBufferProgress(Number): called when the buffering progresses and the estimate (from 0 to 1) of the buffering progress is updated.
﻿
﻿
Three.JS Integration
﻿
Sxrweb three.js player documentation
﻿
Component: soshologram_threejs.js
availeble in https://assets.senseofspace.io/jsplugins/1.0.15/soshologram_threejs.js
Purpose: playing volumetric video in the Sense Of Space sxrweb format.
Prerequisites: Three.js, soshologram.js, hologram data .sxrweb (+ mp4)
Basic architecture:
When soshologram.js code is run, a function named createHologram() is added to window. This way, you can import soshologram.js as a module or simply add a script tag to it to have access to it. Calling window.createHologram will return a hologram object that can easily be integrated into any three.js application, including but not limited to A-Frame.
createHologram() interface:
JS
// Creates as hologram object and returns it.
window.createHologram(
      hologram_url, // URL of the hologram file (.sxrweb)
      hologram_created_callback, // called when hologram is loaded to the point
                                 // that it can be shown, but not necessarily
                                 // played yet. Function with no arguments
      progress_callback, // This is called as loading progresses. Function
                         // with one number parameter, representing the
                         // progress of loading.
      Playable_callback,  // This is called when the hologram has been loaded
                          // enough that it can be played
      loop_mode, // sets the loop mode. Supported values:
                 //    0 or false = don’t loop
                 //    1 or true = ordinary loop
                 //    2 = ping-pong or boomerang mode. Only works for short
                 //        volumetric videos (300 frames or under).
      texture_url_override // Set this to the URL of the texture file you
                           // wish to use, if you want to override the texture
                           // defined in the hologram file. Can be useful if
                           // for some reason the texture files cannot be
                           // placed in the same directory as the sxrweb file
  	);
// Creates as hologram object and returns it.
window.createHologram(
      hologram_url, // URL of the hologram file (.sxrweb)
      hologram_created_callback, // called when hologram is loaded to the point
                                 // that it can be shown, but not necessarily
                                 // played yet. Function with no arguments
      progress_callback, // This is called as loading progresses. Function
                         // with one number parameter, representing the
                         // progress of loading.
      Playable_callback,  // This is called when the hologram has been loaded
                          // enough that it can be played
      loop_mode, // sets the loop mode. Supported values:
                 //    0 or false = don’t loop
                 //    1 or true = ordinary loop
                 //    2 = ping-pong or boomerang mode. Only works for short
                 //        volumetric videos (300 frames or under).
      texture_url_override // Set this to the URL of the texture file you
                           // wish to use, if you want to override the texture
                           // defined in the hologram file. Can be useful if
                           // for some reason the texture files cannot be
                           // placed in the same directory as the sxrweb file
  	);
﻿
﻿
Hologram object interface:

SxrHologram.playHologram(userInteraction)
Tries to play the hologram if there is sufficient data to play it. The argument can be used to indicate if the playing was caused by a user interaction or by automation. Affects muting of the video audio.

SxrHologram.pauseHologram()
Pauses the hologram playback

SxrHologram.getMesh()
Returns a Three.js mesh, that can be added to the scene.

SxrHologram.updateHologram()
Updates the hologram geometry and texture. By default this should be called every frame, or whenever you wish to update the hologram.

SxrHologram.setQuality(quality)
Sets the quality level of the hologram. Supported input values 0=low quality, 1=medium quality, 2= high quality.

SxrHologram.setHologramTime(time)
Sets the hologram time value in seconds. May not work expectedly when streaming the data. Geometry and video is streamed by default if the backend server supports ranges. If you wish to preload everything before playing use blob URLs.

SxrHologram.getVideoElement()
Returns the video element which feeds the texture data to the hologram.

SxrHologram.disposeData()
Call this if you get rid of a hologram in the middle of running your program. Frees resources.
Updated 25 Mar 2024
Did this page help you?
Zappar Integration
Three.JS Integration