# ObjectTrackingConfig

## Object Tracking Configuration

The `ObjectTrackingConfig` is a singleton object that provides centralized configuration for the MultiSet SDK object tracking behavior. It controls how the `ObjectTrackingActivity` detects and tracks pre-registered physical objects in AR.

## Description

This configuration object allows you to customize object tracking behavior before launching `ObjectTrackingActivity`. Settings include object code registration, auto-tracking triggers, background tracking intervals, confidence thresholds, and image quality. All settings can be modified at runtime and validated using the `validate()` method.

***

## Properties

### Object Codes

| Property      | Type            | Default        | Description                                                                                                                                                                      |
| ------------- | --------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `objectCodes` | `Array<String>` | `emptyArray()` | List of object codes to track. Set before launching `ObjectTrackingActivity`. Maximum **10 codes**. Object codes are assigned when registering objects in the MultiSet platform. |

```kotlin
ObjectTrackingConfig.objectCodes = arrayOf("OBJ_001", "OBJ_002")
```

***

### Tracking Behavior

| Property                    | Type      | Default | Description                                                                                                                                                                 |
| --------------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoTracking`              | `Boolean` | `true`  | Whether to automatically start tracking when the AR session begins. If `false`, the user must tap the capture button manually.                                              |
| `backgroundTracking`        | `Boolean` | `true`  | Whether to continue tracking in the background after first success. Keeps the object pose updated over time.                                                                |
| `bgTrackingDurationSeconds` | `Float`   | `15f`   | Interval between background tracking attempts in seconds. Valid range: **5 – 30 seconds**.                                                                                  |
| `restartTracking`           | `Boolean` | `true`  | Whether to restart tracking when AR tracking state is lost (PAUSED or STOPPED).                                                                                             |
| `firstTrackingUntilSuccess` | `Boolean` | `true`  | Keep retrying silently until the first tracking attempt succeeds. Failed results will not be reported to `onObjectTrackingFailure` until at least one success has occurred. |
| `captureDelayMs`            | `Long`    | `1000L` | Delay in milliseconds before capturing a frame after a tracking trigger. Allows the device camera to stabilize.                                                             |

***

### Confidence Settings

| Property              | Type      | Default | Description                                                                                                                          |
| --------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `confidenceCheck`     | `Boolean` | `true`  | Whether to check the confidence threshold before accepting a tracking result. Results below the threshold are discarded and retried. |
| `confidenceThreshold` | `Float`   | `0.3f`  | Minimum confidence score required to accept a tracking result. Valid range: **0.2 – 0.8**.                                           |

***

### UI Settings

| Property     | Type      | Default | Description                                                            |
| ------------ | --------- | ------- | ---------------------------------------------------------------------- |
| `showAlerts` | `Boolean` | `true`  | Whether to show toast messages for tracking status (success, failure). |

***

### Image Quality Settings

| Property       | Type  | Default | Description                                                                                                                              |
| -------------- | ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `imageQuality` | `Int` | `80`    | JPEG quality for frames sent to the tracking API. Higher quality improves accuracy but increases upload size. Valid range: **50 – 100**. |

***

## Methods

### resetToDefaults()

Resets all settings to their default values.

**Declaration:**

```kotlin
fun resetToDefaults()
```

**Description:** Calling this method resets all configuration properties to factory defaults. Useful to ensure a clean state before customizing specific settings.

**Example:**

```kotlin
ObjectTrackingConfig.resetToDefaults()

// Now customize only what you need
ObjectTrackingConfig.objectCodes = arrayOf("OBJ_001")
ObjectTrackingConfig.confidenceThreshold = 0.5f
```

***

### validate()

Applies validated bounds to all numeric settings.

**Declaration:**

```kotlin
fun validate()
```

**Description:** Clamps all numeric properties to their valid ranges and truncates `objectCodes` to a maximum of 10 entries. Call this after modifying any settings and before launching `ObjectTrackingActivity`.

**Validation Rules:**

| Property                    | Valid Range    | Clamped to             |
| --------------------------- | -------------- | ---------------------- |
| `bgTrackingDurationSeconds` | 5 – 30         | `coerceIn(5f, 30f)`    |
| `confidenceThreshold`       | 0.2 – 0.8      | `coerceIn(0.2f, 0.8f)` |
| `imageQuality`              | 50 – 100       | `coerceIn(50, 100)`    |
| `objectCodes`               | max 10 entries | first 10 retained      |

**Example:**

```kotlin
ObjectTrackingConfig.confidenceThreshold = 0.9f  // out of range
ObjectTrackingConfig.validate()
// confidenceThreshold is now clamped to 0.8f
```

***

## Configuration Flow

```
1. Set ObjectTrackingConfig.objectCodes
         ↓
2. Customize tracking behavior properties
         ↓
3. Call ObjectTrackingConfig.validate()
         ↓
4. Launch ObjectTrackingActivity with object codes
         ↓
5. Activity reads configuration in onCreate()
         ↓
6. Tracking behavior follows configuration
```

***

## Best Practices

1. **Always call `validate()`** after modifying settings to ensure values are within valid ranges.
2. **Keep `firstTrackingUntilSuccess = true`** for the best first-time user experience. The activity will silently retry until a confident result is obtained.
3. **Tune `confidenceThreshold`** based on your environment:
   * Start with `0.3f` (default)
   * Increase to `0.5f – 0.6f` for environments with many similar objects
   * Decrease toward `0.2f` for difficult lighting conditions
4. **Use `bgTrackingDurationSeconds` of 10–20 seconds** for most use cases. Lower values give more frequent updates but consume more battery and network.
5. **Set `objectCodes` from `multiset.properties`** via `BuildConfig` rather than hardcoding them in your app, to keep object codes configurable per environment.
6. **Register your objects** on the MultiSet platform before using their codes. Unregistered codes will result in tracking failures.

***

## Related

* [ObjectTrackingActivity](https://docs.multiset.ai/native-support/android-native/sample-activities/objecttrackingactivity)
* [MainActivity](https://docs.multiset.ai/native-support/android-native/sample-activities/mainactivity)
* [LocalizationConfig](https://docs.multiset.ai/native-support/android-native/api-reference/localizationconfig)


---

# 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://docs.multiset.ai/native-support/android-native/api-reference/objecttrackingconfig.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.