# 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)