Table of Contents

ARize XR Viewer

ARize XR Viewer is a JavaScript library that provides tools for viewing and manipulating 3D objects on the web and incorporating them into AR experiences using a device’s camera. The library offers a variety of features for working with 3D models, including material manipulation, animations, variants, and more.

One of the unique features of ARize is its ability to optimize 3D models for AR automatically. This feature makes it easy to create high-quality AR experiences without requiring in-depth technical knowledge. Additionally, the library includes customizable templates with pre-built user interfaces and interactive features for creating AR experiences.

Overall, ARize is a powerful tool for creating immersive 3D experiences on the web and in AR. It focuses on ease of use and optimization for AR performance.

The ARize XR Viewer JavaScript library is currently available through CDN. To add the latest stable release to your project, add the following script between the <head> and </head> tags on your HTML page.

Installation overview

CDN

ARize XR viewer JS library is available through CDN at the moment.

To add the latest stable release to your project, add the following script in between <head> and </head> of your HTML page

				
					<script src="https://arize.eden.com.co/xrviewerlibjs/arize-xr-viewer.min.js"></script>

if you would like to access a specific release version, use the following structure:

				
					<script src="https://arize.eden.com.co/xrviewerlibjs/[Version]/arize-xr-viewer.min.js"></script>

Getting Started

Once you install the library using the CDN address mentioned in the last section, you need to initialize the library within a script tag in your HTML or a javascript file in your project and pass a ‘div’ id and GLB file address to the start function as an object.

Example:

				
					arize.start("div ID", { glbURL: 'FileAddress' });

divID: By passing an ID of an element in your HTML, the ARize XR library automatically creates a canvas in that element and matches the div’s size.

glbURL: The address of the 3D file that you want it to show on your web page

Settings

The ARize XR library is fully customizable; pass on any setting options below to the start function, and it will apply. 

AR Scaling

This setting defines whether the user can pinch to scale the object in AR view or not.

The default value is “fixed”;

Usage:
  • arScaling: “fixed” Prevent the user from scaling (useful for furniture, home goods, and size-sensitive objects)
  • arScaling: “flexible”Allows the user to scale the object.

Show Variant Button

This setting determines whether to show a dropdown list of the object’s variants (Click here to see what variants are) in your 3D viewer or canvas.

The default value is “fixed” in case the model has variants. If not, the dropdown will be rendered.;

Usage:
  • showVariantBtn: “true” Will render a dropdown with a list of variants if there are any.
  • showVariantBtn: “false”Will not render the dropdown list of variants, even if the objects include different variants.

Show AR Button

This setting determines whether to show a button inside your canvas that will trigger the AR view once clicked.

The default value is “true”.

Usage:
  • showARBtn: “true” Rendering a button in your canvas to trigger the AR view.
  • showARBtn: “false”does not render the button to activate the AR (This is useful if you want to implement your user flow and style for the AR trigger button, as you can call the function to launch the AR view programmatically).

Important note:

If showARBtn is set to "true", the general theme of your website will be applied to its style

Show Button Text

As the name suggests using this setting, you can customize the text you want to show on AR Button in case showARBtn is set to true;

The default value is “View AR”.

Usage:
  • aRButtonText: “Your custom text”

GLB URL

This setting fetches the 3D file to render in the viewer from a local address or a URL

The default value for this setting is a simple cube with the ARize logo on it.

Usage:
  • glbURL: “Local address”

or

  • glbURL : “URL address”

Environment/reflection Map

This setting is the environment map for your 3D objects.
(Click here for details about the environment and reflection maps)

envMap affects reflective objects and or materials.

Different types of environment maps affect the appearance of your object in the scene; it can make it look more photo-realistic or more.

The default value of this setting is “envNeutral”.

Usage:

Currently, we have prepared four different environment maps built-in into the library.

  • envMap: “envNeutral” Neutral white bright room
  • envMap: “envHelipad” Helicopter pad on top of a building between skylines
  • envMap: “envTropicalBeach” Tropical beach including blue ocean reflection
  • envMap: “envWinterFrost1” White snowy winter landscape

Progress Bar Color

This setting determines the color of the loading animation

The default value is “#007bfa”.

Usage:

Use Hex color code to use your desired color that matches your brand.

  • progressBarColor: “[HexColorCode]”

Play Animation Automatically (autoAnimationPlay)

If this setting exists. The system will play the specified animation automatically after the asset is loaded in the scene.

The default value is “false”.

Usage:

Use Hex color code to use your desired color that matches your brand.

  • “autoAnimationPlay”: “AnimationName”

You can also set the “autoAnimationPlay” to “true”, in case the asset has only one animation, the system will automatically play and loop the animation after the asset is loaded in the scene.

Shadow Intensity

This setting determines the intensity of the object’s shadow in the scene.

The minimum value is 0, meaning no shadow; the maximum value is 1, meaning hard shadow.

The default value is “0.5”.

Usage:
  • shadowIntensity:”[value between 0 – 1]”

Presentation & Presentation property

This setting determines that if the object is left with no interaction (Click, hover, drag, touch, pinch, etc) for a certain amount of seconds, the object will start rotating at a certain speed. The default value is “true”.
Usage:
  • presentation: “false”/ “true”
  • presentationSpeed: “0.2” Determine the rotation speed of the object.
  • presentationDelay: “3” Determines how many seconds the object needs to be without interaction to start the rotation.

onGlbReady

This setting determines a call-back function to call once the 3D object is loaded in the scene.

Usage:
  • onGlbReady: “[Your function]”

onScreenShotReady(base64)

This setting determines a call-back function to call once the screenshot from the 3D object is taken and ready. The callback will also include a base64 image that can be saved or processed as you wish
Usage:
  • onScreenShotReady: “[Your function]”

Exposure

This setting determines the ambient light intensity of the scene. It makes the scene brighter or darker.

The default value is “1” for natural ambient brightness.

Usage:
  • exposure: “1”

postCameraEffect

This setting determines post-processing camera effect for the orbit camera.

The default value is “false” for natural camera rendering

Currently, there are 5 post-processing effect available.

Usage:
  • postCameraEffect: “bloom”
  • postCameraEffect: “brightnessContrast”
  • postCameraEffect: “hueSaturation”
  • postCameraEffect: “vignette”
  • postCameraEffect: “sepia”

Code Example

You only need to specify the settings you want to change and pass them with the settings object while calling the start function. The rest will have their default value.

In case you would like to customize all the settings above, the start function should look something like the code below:

				
					const settings = {
      	arScaling: "fixed",
      	progressBarColor: "#007BFA",
      	contentType: "singleObject",
      	showVariant: "true",
	    showARButton: "true",
      	aRButtonText: "View AR",
	    glbURL:"",
      	envMap: "default",
      	shadowIntensity: "0.5",
      	presentation: "true",
      	presentationSpeed: "1",
      	presentationDelay: "5",
	    exposure: "1",
	    postCameraEffect: "effectName"/"false"
	    onGlbReady: [function here],
	    onScreenShotReady: [functoin here]
};

arize.start("div ID", { settings });

API

List of Properties

glbAsset

Includes loaded GLB with all its properties like animations, variants, etc.

Example:
  • arize.glbAsset Returns the glbAsset object

OrbitCamera

Includes the camera object, controlled but user input.

Example:
  • arize.OrbitCamera Returns the orbit camera object

rootEntity

Includes the loaded 3D mesh in the scene with all its children, materials, textures, transform, etc.

Example:
  • arize.rootEntity Returns the object of the entity

Functions

startGLB(“fileName”, url)

Loads a new GLB 3D asset in the scene and replaces the current one
Usage:
  • arize.startGLB(“URL”, “fileName”)

ChangeEnvMap(“EnvMapName”)

Changes the environment/reflection map in real-time.

Usage:
  • arize.changeEnvMap(“envNeutral”)
  • arize.changeEnvMap(“envHelipad”)
  • arize.changeEnvMap(“envTropicalBeach”)
  • arize.changeEnvMap(“envWinterFrost1”)

Variants

getListOfVariants(glbAsset)

returns a list of variants inside of the glbAsset
Usage:
  • arize.getListOfVariants(arize.glbAsset)

setVariant(“variantName”)

Set the variant to the glb asset in real-time
Usage:
  • arize.setVariant(‘Variant Name’)
Example:
  • arize.setVariant(‘midnight’)
  • arize.setVariant(‘beach’)
  • arize.setVariant(‘street’)

Material Manipulation

changeMatColor(diffuseMatProperty, red, green, blue, alpha)

You can use this function to change the color of the target material of your 3D asset. You must pass your target material using arize.rootEntity and the RGBA value separately. The RGBA values are between 0-1
Usage:
  • arize.changeMatColor(arize.rootEntity.render.meshInstances[0].material.diffuse, 1,0,0,1)

updateTexture(targetMaterial, “Texture File Address”)

You can use this function to change the texture of the target material of your 3D asset. You must pass your target material using the arize.rootEntity and the address to the texture file. Remember that the smaller the file size of the texture, the faster it will load.
Usage:
  • arize.updateTexture(arize.rootEntity.children[0].render.meshInstances[0].material, ‘file address’);

arize.updateAoMap(targetMaterial, “fileAddress”)

You can use this function to change the AO Map of the target material of your 3D asset. You must pass your target material using the arize.rootEntity and the address to the texture file. Remember that the smaller the file size of the texture, the faster it will load.
Usage:
  • arize.updateAoMap(arize.rootEntity.children[0].render.meshInstances[0].material, ‘file address’);

arize.updateGlossMap(targetMaterial, “fileAddress”)

You can use this function to change the Metallic Map of the target material of your 3D asset. You must pass your target material using the arize.rootEntity and the address to the texture file. Remember that the smaller the file size of the texture, the faster it will load.
Usage:
  • arize.updateGlossMap(arize.rootEntity.children[0].render.meshInstances[0].material, ‘file address’);

arize.updateNormalMap(targetMaterial, “fileAddress”)

You can use this function to update the Normal Map of the target material of your 3D asset. You must pass your target material using the arize.rootEntity and the address to the texture file. Remember that the smaller the file size of the texture, the faster it will load.
Usage:
  • arize.updateNormalMap(arize.rootEntity.children[0].render.meshInstances[0].material, ‘file address’);

arize.updateOpacityMap(targetMaterial, “fileAddress”)

You can use this function to change the Opacity Map of the target material of your 3D asset. You must pass your target material using the arize.rootEntity and the address to the texture file. Remember that the smaller the file size of the texture, the faster it will load.
Usage:
  • arize.updateOpacityMap(arize.rootEntity.children[0].render.meshInstances[0].material, ‘file address’);

arize.updateSpecularMap(targetMaterial, “fileAddress”)

you can use this function To change the roughness map of your object. You must pass your target material using the arize.rootEntity and the address to the texture file. Remember that the smaller the file size of the texture, the faster it will load.
Usage:
  • arize.updateSpecularMap(arize.rootEntity.children[0].render.meshInstances[0].material, ‘file address’);

arize.updateEmissiveMap(targetMaterial, “fileAddress”)

You can use this function to change your object’s emissive map. You must pass your target material using the arize.rootEntity and the address to the texture file. Remember that the smaller the file size of the texture, the faster it will load.
Usage:
  • arize.updateEmissiveMap(arize.rootEntity.children[0].render.meshInstances[0].material, ‘file address’);

Camera

arize.getOrbitCameraTransform()

To get the orbit camera transform, use this function.

Usage:
  • arize.getOrbitCameraTransform()

returns an array containing Pitch, Yaw, and the Distance of the orbit camera in order.

The Pitch, Ya and Distance values are relative to the 3D object in the scene

arize.moveOrbitCameraTo(targetPitch, targetYaw. targetDistance)

To move the orbit camera to a specific angle and distance relative to the 3D object first, you should set your camera in the desired position and call arize.getOrbitCameraTransform(), save the values returned by the function, and then set your camera to those values once an event is fired (button click, touch, keyboard key, etc.) This function is helpful if you would like to highlight a specific part of your 3D object. For example, you would like to show the handle of a 3D bag from a closer distance, or you want a slight zoom once the 3D object is loaded. arize.moveOrbitCameraTo(target pitch, targetYaw. target distance) smoothly transitions the camera to the target pitch, yaw, and distance.
Usage:
  • arize.moveOrbitCameraTo(targetPitch, targetYaw. targetDistance)

Important note:

The Target distance cannot be a minus value.
There is a maximum distance from the object which is by default the distance that the model is loaded.

arize.firePresentationSequence(delay, CameraPosArray)

This function will move the camera to each index of camera pose delay with a specific delay (delay amount is in milliseconds).

CameraPoseArray is an array of objects containing a Pitch, Yaw, and target distance.

Important to mention that there are 17 default positions ready in the function. If you want to use the ready one, call the function with the delay and skip the CameraPoseArray.

Example of CameraPosArray: 
				
					
let CameraPoseArray = [];
    listOfPose.push({pitch: 0, yaw: 0, distance});
    listOfPose.push({pitch: 90, yaw: 0, distance});
    listOfPose.push({pitch: -90, yaw: 0, distance});
    listOfPose.push({pitch: 0, yaw: 90, distance});
    listOfPose.push({pitch: 0, yaw: -90, distance});
Usage:
  • arize.firePresentationSequence(2000 [any other number in miliseconds], CameraPoseArray)
  • arize.firePresentationSequence(2000) -> Use the preset CameraPoseArray

arize.orbitCamera.pitchAngleMax

This property defines the maximum angle the camera can move up and on top of the model by the user.
Usage:
  • arize.orbitCamera.pitchAngleMax = [number]

arize.orbitCamera.pitchAngleMin

This property defines the minimum the camera can move down and under the model by the user.
Usage:
  • arize.orbitCamera.pitchAngleMin = [number]

arize.setPostCameraEffect(“effect name”)

This functions set a post proccessing effect on the realtime rendering camera. at the moment there are 5 effects avaliable.
Usage:
  • arize.setPostCameraEffect(“bloom”)
    • To adjust the properties for the bloom effect use the following code:
  • arize.orbitCamera.entity.script.bloom.bloomIntensity = [number]
  • arize.orbitCamera.entity.script.bloom.blurAmount = [number]


  • arize.setPostCameraEffect(“brightnessContrast”)
    • To adjust the properties of the the brightness and contrast effect use the following code:
  • arize.orbitCamera.entity.script.brightnessContrast.brightness = [number]
  • arize.orbitCamera.entity.script.brightnessContrast.contrast = [number]


  • arize.setPostCameraEffect(“hueSaturation”)
    • To adjust the properties of the hue and saturation effect use the following code:
  • arize.orbitCamera.entity.script.hueSaturation.hue = [number]
  • arize.orbitCamera.entity.script.hueSaturation.saturation = [number]


  • arize.setPostCameraEffect(“vignette”)
To adjust the properties of the vignette effect use the following code:
  • arize.orbitCamera.entity.script.vignette.darkness = [number]
  • arize.orbitCamera.entity.script.vignette.offset = [number]


  • arize.setPostCameraEffect(“sepia”)
    • To adjust the properties of the vignette effect use the following code:
  • arize.orbitCamera.entity.script.sepia.amount = [number]

    • arize.orbitCamera.entity.script.destroy(“effect name”)

    This property removes the post camera effect from the camera.
    Usage:
    • arize.orbitCamera.entity.script.destroy(“effect name”)

    Animation

    arize.getListofAnim(glbAsset)

    This functions returns a list of animations within your GLB asset
    Usage:
    • arize.getListofAnim(arize.glbAsset)
    Playing multiple animations
    It’s important to mention that if you are having a file with multiple animations, at first you need to have an ideal animation, once you call that using the function below, then you can call the function below and the loop parameter then will be in effect for the animation you call. The first animation (idle) will always be looping, hence we suggest having and playing that first automatically if you would like to give your users the ability to change the current playing animation in real time.

    arize.startAnim(arize.glbAsset.resource.animations[index],loop)

    This function plays a specific animation with the possibility to be looped.

    Usage:
    • arize.startAnim(arize.glbAsset.resource.animations[index],true) Play in loop
    • arize.startAnim(arize.glbAsset.resource.animations[index], false) Play only once

    arize.pauseAnim()

    Pause the current playing animation

    Usage:
    • arize.pauseAnim()

    arize.resumeAnim()

    Resume the current playing animation

    Usage:
    • arize.resumeAnim();

    Important note:

    If you want to play different animations of the same model, you must have an idle animation in an idle still pose and play that first. The system will play that in a loop; once that is playing, you can switch to different animations and decide whether you want them to be looped.
    This will be fixed in the future version and is caused by the current limitation of GLB files.

    Miscellaneous

    arize.launchAR(arize.rootEntity, arize.glbAsset)

    You can call this function to trigger the AR experience from a button or any custom button on your website. You must pass the arize.rootEntity and arize.glbAsset to this function to launch the AR experience. Works on android and iOS.
    Usage:
    • arize.launchAR(arize.rootEntity, arize.glbAsset)

    arize.setShadow(Intensity)

    Control the intensity of the shadow of your object in real time. Intensity should be a number between 0 – 1
    Usage:
    • arize.setShadow(0.5)

    arize.rootEntity.setEulerAngles(X, Y, Z)

    You can rotate the object with a specified degree around the X, Y, and Z axes using this function. The object will rotate around its anchor point.
    Usage:
    • arize.rootEntity.setEulerAngles(X, Y, Z)

    Limitations

    Currently at this moment of time you cannot have a an animated and modified model at the same time.
    Animations in AR will loop constantly, The first animation always is the one being played in AR

    arize.saveScreenshot

    This is a simple property to determine when the system takes ascreen shot to automatically prompt the saving of the screenshot into the users machine. The default value of this property is set to true
    Usage:
    • arize.saveScreenshot: “false”/ “true”

    setPresentation

    This function determines the presentation property in real time.
    Usage:
    • setPresentation(“true/false”, delay, speed)
    • delay: The number of seconds that the model has to be left without any interaction for the presentation to start
    • speed: the speed factor that determines the spinning speed of the 3D asset in the scene, in case the presentation is set to “true.”

    arize.takeScreenshot()

    This function invokes an operation to take a screenshot of whatever the camera is rendering in the scene.

    Usage:
    • arize.takeScreenshot()

    arize.takeSequenceScreenshot(saveOneByOne, delay, cameraListPos)

    This function will move the camera to each index of camera pose delay with a specific delay (delay amount is in milliseconds) and takes a screenshot.

    You can set the function to prompt the user to save the taken screenshots individually or trigger the “onScreenShotReady” call back by setting it to “true” or “false”.

    CameraPoseArray is an array of objects containing a Pitch, Yaw, and target distance.

    Important to mention that there are 17 default positions ready in the function. In case you want to use the ready one call the function with the delay and skip the CameraPoseArray.

    Example of CameraPosArray: 
    				
					
let CameraPoseArray = [];
    listOfPose.push({pitch: 0, yaw: 0, distance});
    listOfPose.push({pitch: 90, yaw: 0, distance});
    listOfPose.push({pitch: -90, yaw: 0, distance});
    listOfPose.push({pitch: 0, yaw: 90, distance});
    listOfPose.push({pitch: 0, yaw: -90, distance});
    Usage:
    • arize.takeSequenceScreenshot(true, 2000[any other number in miliseconds], cameraPoseArray) –> Save the screenshots one by one
    • arize.takeSequenceScreenshot(false, 2000[any other number in miliseconds], cameraPoseArray) –> Trigger “OnScreenShotReady” every time a screenshot is ready
    • arize.takeSequenceScreenshot(false/true, 2000) –> Use the preset CameraPosArray

    arize.setRefUrl(“url”)

    This function sets the URL of the QR code that is shown when invoking the launch AR button on the desktop. The default value for the QR reference URL is the address of the web page where the API is implemented
    Usage:
    • arize.setRefUrl(“url”)

    arize.destroy()

    This function removes the canvas and the elements created by the XR Viewer API from the document

    This is useful to mono page applications where the elements and components are dynamically created and destroyed in real-time without the page being reloaded.
    Usage:
    • arize.destroy()

    Support

    If you spot any issues or encounter a bug while developing with the ARize XR Viwer javascript library, refer to this GitHub repository below to report problems and request features.

    Github Repo: ARizeXRViewerJS repository on github

    License

    Copyright (c) 2023 ARize Group B.V
    This API was developed with the sole purpose of making 3D easy. Developed with love for those individuals or companies who are love 3D and want to use it in an easier, faster and more effective way!

    Notifications...

    Reset