# XREAL Markers

## Introduction

Introducing XREAL Markers, a novel set of 'interactive' image tracking cards designed to facilitate virtual and real-world interaction. By manipulating the magnetic sliders on the cards, users can engage in dynamic gameplay experiences. The cards are available in three distinct colors: green for bidirectional functionality, blue for tridirectional, and orange for six-directional capabilities. Developers are encouraged to leverage the cards' interactive features to innovate and enhance both new and existing applications. Additionally, we invite you to explore the sample application '[Spatial Life](https://nreal-public.nreal.ai/download/Application/spatiallife0619.apk),' thoughtfully crafted by the XREAL design team.

<figure><img src="/files/XnKfAUrRR1pEZXpjYVqB" alt=""><figcaption></figcaption></figure>

## Requirement <a href="#developerguide" id="developerguide"></a>

> To ensure optimal performance and compatibility when using the Spatial Life application, the following hardware and software specifications must be met:

* Android phones listed in[ Device Compatibility](/nrsdk/nrsdk-fundamentals/xreal-devices/compatibility.md) or Beam Pro.
* XREAL Air 2 Ultra
* [Nebula 3.8.0](https://play.google.com/store/apps/details?id=ai.nreal.nebula.universal\&hl=en_US\&gl=US)
* XREAL Markers&#x20;

> For developers interested in creating applications akin to Spatial Life, with feature coaster image tracking, additional resource is required:

<details>

<summary>NRSDKForUnity Experimental </summary>

2024.06.19

Regular updates released with the normal version.

* [NRSDKForUnity\_Experimental\_Release\_2.2.1.unitypackage](https://nreal-public.nreal.ai/download/NRSDKForUnity_2.2.1_Release_20240619/NRSDKForUnityAndroid_Experimental_2.2.1.unitypackage)&#x20;

2024.04.18&#x20;

Fixed: The problem of not being recognized after switching back from the background.

* [NRSDKForUnity\_Experimental\_Release\_2.2.1.unitypackage](< https://nreal-public.nreal.ai/download/NRSDKForUnity_2.2.0_Release_20240418/NRSDKForUnityAndroid_Experimental_2.2.1.unitypackage>)    &#x20;

2024.03.29&#x20;

* [NRSDKForUnity\_Experimental\_Release\_2.2.0.unitypackage](<https://nreal-public.nreal.ai/download/NRSDKForUnity_2.2.0_Release_20240329/NRSDKForUnityAndroid_Experimental_2.2.0.unitypackage&#xA;>)    &#x20;

</details>

> Developers who don’t have Marker cards can download and print this PDF file for use.

{% file src="/files/wuNE6bj1pfZEFoYAbnFF" %}

Usage Instructions:

* Please print the Marker images on matte A4 paper in color to ensure accurate output size.
* When printing, do not enlarge the image; print at 100% scale.
* Cut out the Marker along the black border and attach it to a rigid cardboard.
* Within the camera’s recognition range, only one card of the same color should appear.

## Developer Guide <a href="#developerguide" id="developerguide"></a>

> Developers who don’t have Marker cards can download and print this PDF file for use.

{% file src="/files/Vc0s19sVf7eeyQqYXcoI" %}

Usage Instructions:

* Please print the Marker images on matte A4 paper in color to ensure accurate output size.
* When printing, do not enlarge the image; print at 100% scale.
* Cut out the Marker along the black border and attach it to a rigid cardboard.
* Within the camera’s recognition range, only one card of the same color should appear.

## Developer Guide <a href="#developerguide" id="developerguide"></a>

Learn how to use the Coasters Image Tracking feature in your own apps.

* Create a new project in Unity.&#x20;

> Need help setting up? Try [Getting Started with NRSDK](/nrsdk/nrsdk-fundamentals/quickstart-for-android.md) first

* Click NRSDK -> CoastersTrackingModule -> Install

<figure><img src="/files/Dg2ly91a2agFsNUDHEaO" alt=""><figcaption></figcaption></figure>

> Note that the coasters image tracking is not compatible with the original image tracking. If you want to use the old version SDK, click uninstall.

* Open scene **`CoastersimageTracking`**

<figure><img src="/files/HSaUfW5wVfLLceXK0Zcw" alt=""><figcaption></figcaption></figure>

* Modify your application logic as needed. The editor includes a simulator for image tracking, demonstrated in the screenshot below. This simulator provides 11 buttons, each corresponding to one of the 11 images. By clicking these buttons, you can simulate the tracking effect for the respective image.

  <figure><img src="/files/Z5ceYt6ylNMZ4Aouk0hk" alt=""><figcaption></figcaption></figure>
* The Marker feature uses a trained data sample. The sample resource address is shown in the figure below. It needs to be specified in the SessionConfig resource.

<figure><img src="/files/LVqfH9EcfSp4GcoG2Y7W" alt=""><figcaption></figcaption></figure>

* Set the ImageTrackingMode to enable.

<figure><img src="/files/Z5f1goYkoqrg036wMcDZ" alt=""><figcaption></figcaption></figure>

* Before building an APK, please add the following lines inside the `<application>` element of your `AndroidManifest.xml`

{% code overflow="wrap" %}

```xml
<uses-library android:name="libOpenCL.so" android:required="false"/>
<uses-library android:name="libcdsprpc.so" android:required="false"/>
```

{% endcode %}

## Usage

### Get the current tracked Image list.

{% code overflow="wrap" %}

```csharp
NRFrame.GetTrackables<NRTrackableImage>(m_TempTrackingImages, NRTrackableQueryFilter.All);
```

{% endcode %}

### Get the tracking status of Image

> In Marker, the `GetTrackingState` method will only return two states: **Tracking** and **Paused**.

{% code overflow="wrap" %}

```csharp
NRTrackableImage.GetTrackingState() 

    /// <summary> Device Tracking State. </summary>
    public enum TrackingState
    {
        /// <summary>
        /// TRACKING means the object is being tracked and its state is valid.
        /// </summary>
        Tracking = 0,

        /// <summary>
        /// PAUSED indicates that NRSDK has paused tracking, 
        /// and the related data is not accurate.  
        /// </summary>
        Paused = 1,

        /// <summary>
        /// STOPPED means that NRSDK has stopped tracking, and will never resume tracking. 
        /// </summary>
        Stopped = 2
    }
```

{% endcode %}

### Get the ID of the Image

> In Marker, the value range of ID is \[0,10], corresponding to different states of Marker cards.

```csharp
NRTrackableImage.GetCoastersDataBaseIndex()
```

### Get image pose and size information

```csharp
// The length in the X direction of the image
NRTrackableImage.ExtentX
// The length in the Z direction of the image
NRTrackableImage.ExtentZ
// Get the pose of the center of the image
NRTrackableImage.GetCenterPose
```

### Enable and disable ImageTracking functionality

{% code overflow="wrap" %}

```csharp
/// <summary> Enables the image tracking. </summary>
public void EnableImageTracking()
{
    var config = NRSessionManager.Instance.NRSessionBehaviour.SessionConfig;
    config.ImageTrackingMode = TrackableImageFindingMode.ENABLE;
    NRSessionManager.Instance.SetConfiguration(config);
}

/// <summary> Disables the image tracking. </summary>
public void DisableImageTracking()
{
    var config = NRSessionManager.Instance.NRSessionBehaviour.SessionConfig;
    config.ImageTrackingMode = TrackableImageFindingMode.DISABLE;
    NRSessionManager.Instance.SetConfiguration(config);
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xreal.gitbook.io/nrsdk/development/image-tracking/xreal-markers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.