# A-Frame Attributes

{% content-ref url="<https://app.gitbook.com/o/QMsd5hT6sxA9FBIB03yh/s/3UKy7VHRJWrNarYaMp13/>" %}
[Blippar Documentation Centre](https://app.gitbook.com/o/QMsd5hT6sxA9FBIB03yh/s/3UKy7VHRJWrNarYaMp13/)
{% endcontent-ref %}

## Introduction

These are Blippar WebAR SDK’s custom HTML attributes that are used with A-Frame’s Entity and Scene. They are available to use after the WebAR SDK script has been loaded.

## A-Frame

### webar-camera

**Usage**

```html
<a-camera webar-camera> </a-camera>
```

or

```html
<a-entity camera webar-camera> </a-entity>
```

**Description**

When A-Frame’s \<a-entity camera> or \<a-camera> is added with the **webar-camera** attribute, it becomes the WebAR camera for surface tracking.

**Example**

```html
<a-camera webar-camera></a-camera>
```

{% hint style="info" %}
Only a single A-Frame camera is supported.
{% endhint %}

### **webar-loadmonitor**

**Usage**

```html
<a-entity webar-loadmonitor> </a-entity>
```

**Used by the entities that are loading an asset.**

**Description**

Monitors the loaded state of an asset in an A-Frame entity. The initial loading progress bar will be displayed until all of these assets are loaded and after the camera video appears on screen.

For faster loading times and to ensure entities have been fully loaded before showing the scene the *elType* property should be defined, default value is 'none'. Values are shown in the table below.

**Properties**

| Property      | Value                            |
| ------------- | -------------------------------- |
| ***elType:*** | \<one of the elType enum values> |

**Enum Values**

<table><thead><tr><th width="383">elType enum values</th><th>A-Frame’s Event listened</th></tr></thead><tbody><tr><td><em><mark style="color:blue;">glb</mark></em></td><td>model-loaded</td></tr><tr><td><em><mark style="color:blue;">obj</mark></em></td><td>model-loaded</td></tr><tr><td><em><mark style="color:blue;">asset</mark></em></td><td>loaded</td></tr><tr><td><em><mark style="color:blue;">texture</mark></em></td><td>materialtextureloaded</td></tr><tr><td><em><mark style="color:blue;">video</mark></em></td><td>materialvideoloadeddata</td></tr><tr><td><em><mark style="color:blue;">none</mark></em></td><td>Waits for 500 ms</td></tr></tbody></table>

**Example**

```html
<a-assets>
  <a-asset-item 
    id="astronaut" 
    src="models/astronaut.glb">
  </a-asset-item>
</a-assets>

<a-entity
  gltf-model="#astronaut" id="astronaut_1"
  rotation="0 0 0" position="0 0 0" scale="0.25 0.25 0.25"
  webar-loadmonitor="elType: glb">
</a-entity>
```

### **webar-marker (Marker Tracking)** <a href="#h_01fmhm1q251zaxy9hfwtb8rccq" id="h_01fmhm1q251zaxy9hfwtb8rccq"></a>

**Usage**

```html
<a-entity webar-marker="id: dddddddd-uuuu-mmmm-mmmm-yyyyyyy11111"> </a-entity>
<a-entity webar-marker="id: dddddddd-uuuu-mmmm-mmmm-yyyyyyy22222"> </a-entity>
...
```

To be used with a parent entity of the 3D model entities that have to be displayed on a marker image.

**Description**

When an A-Frame’s topmost parent a-entity in a scene is added with the <mark style="color:red;">webar-marker</mark> attribute, it becomes the placeholder for the 3D models that have to be displayed over the image of the corresponding marker id specified as the value of the <mark style="color:blue;">id:</mark> property.

Up to 10 markers can be uploaded per WebAR SDK Project (or license) in the Blippar Marker Manager. Each marker image can be linked to an AFrame's <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-marker</mark>=<mark style="color:blue;">"id: \<marker\_id>"</mark><mark style="color:orange;">></mark> by replacing <mark style="color:blue;">\<marker\_id></mark> with a valid marker id obtained from the Blippar Marker manager after uploading an image.

The number of <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-marker</mark><mark style="color:blue;">="id: \<marker\_id></mark><mark style="color:orange;">"></mark> elements should match with the number of marker images uploaded in the Blippar Marker Manager. Each <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-marker</mark><mark style="color:blue;">="id: \<marker\_id></mark><mark style="color:orange;">"></mark> should have a unique <mark style="color:blue;">\<marker\_id></mark> obtained for each uploaded image in the Blippar Marker Manager.

#### **Properties**

<table><thead><tr><th>Property</th><th width="401">Value</th></tr></thead><tbody><tr><td><em><mark style="color:blue;">id:</mark></em></td><td>Marker id value obtained from the Blippar Manager after uploading an image.</td></tr></tbody></table>

{% hint style="info" %}

* When the <mark style="color:red;">webar-mode</mark><mark style="color:blue;">="marker-tracking"</mark> attribute is set in the WebAR SDK \<script> tag, at least one \<a-entity webar-marker="id: \<marker\_id>"> element is expected.
* If any of the marker images uploaded to Blippar Marker Manager is not linked with a <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-marker</mark><mark style="color:blue;">="id: ..."</mark><mark style="color:orange;">></mark> element, then any one of the models from the existing <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-marker</mark><mark style="color:blue;">="id: \<marker\_id>"</mark><mark style="color:orange;">></mark> in the scene will be displayed when scanning that image for marker tracking.
  {% endhint %}

**Example**

```html
<a-entity webar-marker="id: dddddddd-uuuu-mmmm-mmmm-yyyyyyy11111">
  <a-entity gltf-model="..."></a-entity>
  <a-entity geometry="..."></a-entity>
</a-entity>

<a-entity webar-marker="id: dddddddd-uuuu-mmmm-mmmm-yyyyyyy22222">
 <a-entity gltf-model="..."></a-entity>
 <a-entity geometry="..."></a-entity>
</a-entity>

...
```

### **webar-scene** <a href="#h_01fg3tbjvzpg5aqt19k5fmzg9z" id="h_01fg3tbjvzpg5aqt19k5fmzg9z"></a>

**Usage**

```html
<a-scene webar-scene="key: ..."></a-scene>
```

**Description**

When A-Frame’s a-scene is added with the webar-scene attribute, it becomes the WebAR scene for surface tracking.

**Properties**

<table><thead><tr><th>Property</th><th width="401">Value</th></tr></thead><tbody><tr><td><em><mark style="color:blue;">Key:</mark></em></td><td>&#x3C;License key purchased from Blippar></td></tr></tbody></table>

**Example**

```html
<a-scene
webar-scene="key:xxxxxxxx-1111-2222-3333-yyyyyyyyyyyy"
vr-mode-ui="enabled: false"
device-orientation-permission-ui="enabled: false"
loading-screen="enabled: false">
```

{% hint style="info" %}

* In the above example, **‘xxxxxxxx-1111-2222-3333-yyyyyyyyyyyy’,** has to be replaced with your website domain’s license.
* The license key can only be used on a HTTPS server that has the same public domain name for which the license was purchased or for a local HTTPS server that has the same private IP address as the domain name. Please see the [Local Development Guide ](https://docs.blippar.com/webar-sdk/v.1.7.1/publish-your-creation/develop-locally)for more details.
* Please use the values of the attributes ‘vr-mode-ui’, ‘device-orientation-permission-ui’ and ‘loading-screen’ as shown in the above example.
  {% endhint %}

### **webar-ux-control**

**Usage**

```html
<a-entity webar-ux-control> </a-entity>
```

**Description**

Enhances the AR experience by adding a stage cursor that allows users to place the AR model precisely by tapping on the screen. It activates a stage cursor for model placement (<mark style="color:blue;">`stageCursorUX: true`</mark>) and allows intuitive user interactions with the model through rotation and scaling (<mark style="color:blue;">`userGestureRotation: true; userGestureScale: true`</mark>).

To utilize the <mark style="color:orange;">`webar-ux-control`</mark> functionality effectively, it is essential to configure this element as a child of the <mark style="color:orange;">`webar-stage`</mark>. Additionally, all other entities, such as the scene's 3D models, must be nested as children within this structure to ensure proper implementation of the <mark style="color:orange;">`webar-ux-control`</mark> features.

**Attributes**

| Attribute               | Value     |
| ----------------------- | --------- |
| ***stageCursorUX***     | *boolean* |
| **userGestureRotation** | *boolean* |
| **userGestureScale**    | *boolean* |

**Example**

```html
<body>
   
   ...

    <a-entity webar-stage>
       <a-entity webar-ux-control="stageCursorUX: true; userGestureRotation: true; userGestureScale: true">
       <!-- Place 3D AR models here -->
       </a-entity>
    </a-entity>

  </a-scene>
</body>
```

### **webar-stage (Surface Tracking)** <a href="#h_01fg3tc9hebhd2tjw0z1ncp5g3" id="h_01fg3tc9hebhd2tjw0z1ncp5g3"></a>

**Usage**

```html
<a-entity webar-stage> </a-entity>
```

To be used once with a parent entity of all of the 3D model entities that have to be displayed on the surface tracking scene.

**Description**

When an A-Frame’s topmost parent a-entity in a scene is added with the webar-stage attribute, it becomes a stage for the 3D models that have to be displayed on the surface tracking WebAR scene. In other words, all the 3D model entities have to be added as children to this <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-stage</mark><mark style="color:orange;">></mark> element.

**Note**

Only one <mark style="color:orange;">\<a-entity</mark> <mark style="color:red;">webar-stage</mark><mark style="color:orange;">></mark> is supported.

**Example**

```html
<a-entity webar-stage>
  <a-entity gltf-model="..."></a-entity>
  <a-entity geometry="..."></a-entity>
</a-entity>
```

### **webar-facemesh (Face Tracking)** <a href="#h_webar_facemesh" id="h_webar_facemesh"></a>

**Usage**

```html
<a-plane webar-facemesh> </a-plane>
```

To be used once with a \<a-plane> element .

**Description**

When an A-Frame’s topmost parent a-entity in a scene is added with the webar-facemesh attribute, it becomes a masked mesh for the tracked face WebAR scene. It can be used to apply image or video textures, occluder or any desired material to this <mark style="color:blue;">\<a-entity</mark> <mark style="color:red;">webar-facemesh</mark><mark style="color:blue;">></mark> element, in order to create AR experiences like lipstick try-on, realtime face swap, etc.

<figure><img src="https://content.gitbook.com/content/MNoA4M7dz4DXv12sDZUk/blobs/GOdw8TpOcsJIlVvtJnaT/webar-facemesh.png" alt=""><figcaption></figcaption></figure>

**Note**

Only one <mark style="color:blue;">\<a-entity</mark> <mark style="color:red;">webar-facemesh</mark><mark style="color:blue;">></mark> is supported.

**Example**

```html
<a-entity webar-facemesh material="src: #liptexture; side: front; alphaTest: 0; color: #E32531; shader: flat; transparent: true; opacity: 1;"></a-entity>
```

Face mesh has to use the following Canonical Face model layout as its texture UV map.

<figure><img src="https://content.gitbook.com/content/MNoA4M7dz4DXv12sDZUk/blobs/pFEoko1pt00aQd3PoQgm/canonical_face_model_uv_visualization.png" alt=""><figcaption></figcaption></figure>

Sample Face mesh textures are shown below:

<figure><img src="https://content.gitbook.com/content/MNoA4M7dz4DXv12sDZUk/blobs/3XN7Dqyesw4h3NmzPXLJ/oldface.png" alt=""><figcaption><p>Lip mask texture example</p></figcaption></figure>

<figure><img src="https://content.gitbook.com/content/MNoA4M7dz4DXv12sDZUk/blobs/NI7xPNd6jIE4D7HyaTd0/lipmask.png" alt=""><figcaption><p>Face swap texture example</p></figcaption></figure>

### **webar-face (Face Tracking)** <a href="#h_webar_face" id="h_webar_face"></a>

**Usage**

```html
<a-entity webar-face> </a-entity>
```

To be used once with a parent entity of all of the 3D model entities that have to be positioned w\.r.t the tracked face.

**Description**

When an A-Frame’s topmost parent a-entity in a scene is added with the webar-face attribute, it becomes a stage for the 3D models that have to be displayed on the face tracking WebAR scene. In other words, all the 3D model entities have to be added as children to this <mark style="color:blue;">\<a-entity</mark> <mark style="color:red;">webar-face</mark><mark style="color:blue;">> element.</mark>. The center point between the line connecting the eyes, shown as the red dot in the image, is the origin of the element.

<figure><img src="https://content.gitbook.com/content/MNoA4M7dz4DXv12sDZUk/blobs/eDvMg7xHan7IVxa4u8u4/webar-face.png" alt=""><figcaption></figcaption></figure>

**Note**

Only one <mark style="color:blue;">\<a-entity</mark> <mark style="color:red;">webar-face</mark><mark style="color:blue;">></mark> is supported.

**Example**

```html
<a-entity webar-face>
  <a-entity gltf-model="..."></a-entity>
</a-entity>
```

### **id="webar-video-plane" (Face Tracking)** <a href="#h_id_webar_videoplane" id="h_id_webar_videoplane"></a>

**Usage**

```html
<a-entity id="webar-video-plane" color="#ffffff"> </a-entity>
```

To be used once with a \<a-plane> entity. This is an optional id attribute. If not provided, sdk displays the normal webcam video layer in the AR scene backdrop by default. **Description**

When an A-Frame’s topmost parent a-plane in a scene is added with the id="webar-video-plane" attribute, it becomes the webcam video layer displayed on the backdrop of face tracking WebAR scene. It can be used only to change the color of the webcam video background to suit the experience, for example, add color="#ff0000" attribute to show a bluish video. It's visibility can be also be set to false to display a white background(default color of the a-scene).

**Note**

Only one <mark style="color:blue;">\<a-entity</mark> <mark style="color:red;">id="webar-video-plane"</mark><mark style="color:blue;">></mark> is supported.

**Example**

```html
  <a-plane id="webar-video-plane" color="#ff0000" visible="true"></a-plane>
```