Javascript Functions
Refer various functions applicable for WebAR SDK integration
The WebAR’s functions are accessed through the global variable WEBARSDK, which is available after the WebAR SDK script has been loaded. The functions in this page are compatible with A-Frame, BabylonJS & Playcanvas integration if not otherwise specified.
AddMarkerElement()
Usage
Description
Associate a specific marker id with an aframe entity's id. When the marker id's image is detected, then the associated aframe entity will be displayed over the marker image.
This API only works with AFrame renderer.
Parameters
Returns
-
Example
DisableAutoScale() (deprecated)
Usage
Description
Disables the auto scaling which happens only object is being anchored, only once. (API only works with "Surface-Tracking")
If auto scale is enabled(recommended), the AR object is scaled in such a way that it fits the screen, otherwise the AR object would appear based on the detected surface's extent(which would not be consistent).
This API is deprecated, use API "SetAutoScale()" instead.
Returns
-
Example
DisableTracking()
Usage
Description
This function is defined for a portal experience and is used to disable tracking, after the mobile device approaches a portal door, and to start the gyro camera if required. The parameter enableGyroCam is supported only in AFrame rendering engine. It will be ignored for other rendering engines.
Parameters
Returns
-
Example
EnableTrackingOnDesktop()
Usage
Description
This function is specifically designed to enable desktop tracking for face tracking scenarios. This function is particularly useful in instances where the application initially starts in a 'lazy-mode' and subsequently determines which tracking mode to initiate. EnableTrackingOnDesktop()
activates the face tracking capabilities of the SDK when running on a desktop environment. It is supported only in AFrame rendering engine for face tracking mode. It will be ignored for other rendering engines.
Additionally, desktop tracking can also be controlled via the enable-tracking-on-desktop
attribute.
Parameters
Returns
-
Example
GetActiveMarkerId()
Usage
Description
Gets the active marker id i.e. UUID of the current detected marker.
Parameters
-
Returns
Example
GetCurrentPose()
Usage
Description
Returns a 4x4 matrix that transforms a stage 3D-object into world-coordinates. Matrix should be accessed in ‘row-major’ order. Please note that tracking assumes a Static-Camera-With-A-Moving-Stage by default. However, it can be changed to Moving-Camera-With-A-Static-Stage using attribute 'static-camera'.
Parameters
-
Returns
Example
GetCurrentPosition()
Usage
Description
Returns the position of the stage/camera object based on attribute 'static-camera'. Please note that tracking assumes a Static-Camera-With-A-Moving-Stage by default. However, it can be changed to Moving-Camera-With-A-Static-Stage using attribute 'static-camera'.
Parameters
-
Returns
Example
GetCurrentRotation()
Usage
Description
Returns a 4x4 pure rotation matrix of the stage/camera object based on attribute 'static-camera'. It is the orientation of stage/camera with respect to the world.
Parameters
-
Returns
Example
GetCurrentScale()
Usage
Description
Returns the scale of the stage object.
Parameters
-
Returns
Example
GetLoadingProgress()
Usage
Description
Returns the app loading progress as a percentage. User may find this useful while creating custom splash screen to create custom animation for loading progress.
Parameters
-
Returns
Example
GetMouthOpenedMagnitude()
Usage
Description
Returns the magnitude of the distance between the upper and lower lips when the mouth is opened. For example, it can be used to trigger some animation of the webar-face model, if the magnitude is greater than 0.2.
Parameters
-
Returns
Example
RemoveMarkerElement()
Usage
Description
Removes the association of a marker id with an entity in the scene and the user will not be able to see any AR object when the marker id's image is detected.
This API only works with AFrame renderer.
Parameters
Returns
-
Example
Init()
Usage
Description
If the SDK script attribute auto-init is set to 'false', then tracking has to be started manually by calling Init() method. For example, this will be useful when the user has to display some information in an overlaid html div, and only after the user clicks a button to enter into the 'Surface Tracking' or 'Marker Tracking' experience.
InitBabylonJs()
Usage
Description
This function is used to initialise the SDK with BabylonJs scene Objects for Surface Tracking or Marker Tracking experience.
Parameters
Returns
-
Example
Babylon.Js Example. Refer Section on surface tracking and marker tracking.
SetAppReadyCallback()
Usage
Description
This function is used to set a callback function when app is completely loaded. For example, this callback function can be used to fade out the custom animation of splash screen.
Parameters
Returns
-
Example
SetARModelPlaceCallback()
Usage
Description
The SetARModelPlaceCallback
function is designed to register a callback function that triggers when an AR model is successfully placed within the scene. This allows developers to define custom behavior that occurs immediately after the model placement, such as initiating animations, logging events, or enabling additional UI elements.
Parameters
This function's utility is predicated on the webar-ux-control
being properly set up with stageCursorUX
set to true
in the scene. Without this configuration, the reset button—and consequently the reset callback—will not function. (Only for AFrame & BabylonJS)
Returns
-
Example
SetAutoMarkerDetectionStyle()
Usage
Description
This function is used to overlay auto marker detection default style, user can use custom user experience to enhance visuals. User can also pass a flag to disable the scan instruction text
Parameters
Returns
-
Example
SetAutoScale()
Usage
Description
Auto Scale is enabled by default. To disable the auto scale, pass boolean 'false' in the argument and call this function after Init().
What is Auto Scaling in context of 'Marker Tracking' & 'Surface Tracking'?
**Marker Tracking:**The scaling is applied in such a way that a (1,1) unit plane fits the width/height of the marker(where unit is meter).
**Surface Tracking:**It scales the AR object based on distance from the camera
Parameters
Returns
-
Example
SetEyesMeshFilled()
Usage
Description
If set to false, the eyes area of the facemesh appears hollow .i.e no texture/material is rendered on the both the eyes area. If set to true, eyes of the facemesh appears closed.
Parameters
Returns
-
Example
SetFaceScaleFactor()
Usage
Description
This function configures the scale at which AR objects are displayed relative to the user’s face in a web-based AR experience. It computes a scale factor based on the bounding box dimensions of a reference model (e.g., human-head) and applies this scale factor to the webar-face
and webar-face-pivot
entities. As a result, all AR objects that are children of these entities will have their scale and position adjusted according to the scale factor, ensuring the AR objects appear proportionally shrinked or enlarged as necessary.
Parameters
Returns
-
Example
SetGuideAnimation()
Usage
Description
This function is used to set custom guide animations for surface tracking and marker tracking (only with scan button). Please note that it only supports lottie animations json format.(https://lottiefiles.com)
Parameters
Returns
-
Example
SetGuideViewCallbacks()
Usage
Description
This API gives a callback once the surface tracking experience loads (Splash screen) and when the default Hand with phone animation guide starts(startGuideViewCallback) and then stops/hides (stopGuideViewCallback) after a surface is detected.
If you want to display a custom Hand with phone/Surface detection guide, set the SDK attribute show-guide-view="false", and use the two callback parameters passed via startGuideViewCallback and stopGuideViewCallback, to show and then hide it.
Other cases of using these callbacks are:
A custom loading splash/progress full screen div element can be overlaid and can be removed/hidden after startGuideViewCallback is received
Start the animation of a 3D model after stopGuideViewCallback is received.
Example
SetMarkerDetectedCallback()
Usage
Description
This is used to set a callback function when the 3D object appears on the screen after a marker image is detected. For example, this callback function can be used to start the animation of the 3D model.
Parameters
Returns
-
Example
SetMarkerLostCallback()
Usage
Description
This is used to set a callback function when a marker image tracking is lost.
Parameters
Returns
-
Example
SetMouthMeshFilled()
Usage
Description
If set to false, the mouth area of the facemesh appears hollow .i.e no texture/material is rendered on the mouth area. If set to true, mouth of the facemesh is closed.
Parameters
Returns
-
Example
SetPortalEntryCallback()
Usage
Description
This is a portal experience and is used to set a callback function when the mobile device approaches a 3D portal/door entrance.
Parameters
The callback function for when the mobile device approaches a 3D object.
Returns
-
Example
SetResetButtonCallback()
Usage
Description
This function is designed to link a user-defined callback to the reset button's action within an AR interface. When the reset button is pressed, the specified callback function is executed, allowing developers to implement custom logic such as resetting the scene, clearing user progress, or other application-specific reset behavior.
Parameters
This function's utility is predicated on the webar-ux-control
being properly set up with stageCursorUX
set to true
in the scene. Without this configuration, the reset button—and consequently the reset callback—will not function. (Only for AFrame & BabylonJS)
Returns
-
Example
SetResetButtonVisibility()
Usage
Description
The SetResetButtonVisibility
function controls the display of the reset button within the AR interface. It provides the ability to dynamically show or hide the reset button based on the needs of the AR experience or user preferences.
Parameters
Returns
-
Example
SetStageReadyCallback()
Usage
Description
This function is used to set a callback function when the object appears for the first time on screen after the surface. For example, this callback function can be used to start the animation of the 3D model.
Parameters
This is the callback function that gets called when the 3D object appears on screen for the first time after the surface has been detected.
Returns
-
Example
SetTrackingQualityChangeCallback()
Usage
Description
This is used to set a callback function when either 'Surface' or 'Marker' tracking quality gets changed.
Parameters
Returns
-
Example
SetTrackingStartedCallback()
Usage
Description
This function is used to set a callback function which gives a callback when either 'Surface' or 'Marker' tracking has started.
Parameters
Returns
-
Example
SetTrackingStoppedCallback()
Usage
Description
This function is used to set a callback function which gives a callback when either 'Surface' or 'Marker' tracking has stopped.
Parameters
Returns
-
Example
StartTracking()
Usage
Description
This function is used to start the tracking, if tracking has stopped or param 'auto-start' is set to 'false'. It either starts Surface or Marker Tracking based on the 'webar-mode' attribute.
auto-init is associated with initializing the sdk core whereas auto-start enables the user to control when to start the tracking in the app.
Parameters
Returns
-
Example
StopTracking()
Usage
Description
This function is used to stop the tracking, if tracking has already started.
auto-init is associated with initializing the sdk core whereas auto-start enables the user to control when to start the tracking in the app.
Parameters
Returns
-
Example
SetUserGestureRotation()
Usage
Description
This function allows you to enable or disable user rotation.
Parameters
Returns
-
Example
SetUserGestureScale()
Usage
Description
This function enables or disables user scaling.
Parameters
Returns
-
Example
SetWebARMode()
Usage
Description
This function is used to set the webar mode at a delayed stage of application. It provides a dynamic loading using lazy initialisation. It should be called only-if webar-mode script attribute is specified with 'lazy-mode'.
This method has to be called before StartTracking().
Parameters
Returns
-
Example
TakeSnapShot()
Usage
Description
This function is used to capture a snapshot of the AR experience.
Only for Playcanvas! To get the snapshot API to work correctly in Playcanvas rendering engine, enable Preserve Drawing Buffer flag. Go to Playcanvas Project Editor, then navigate to project SETTINGS > RENDERING tab and make sure "Preserve Drawing Buffer" is checked.
Parameters
Returns
-
Example