> For the complete documentation index, see [llms.txt](https://multiset.gitbook.io/multiset/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multiset.gitbook.io/multiset/native-support/android-native/sample-activities/multisetlocalizationactivity.md).

# MultiSetLocalizationActivity

## Overview

The `MultiSetLocalizationActivity` is a unified AR localization activity that supports both single-frame and multi-frame localization modes. The mode is selected at launch time via an intent extra.

## Description

This is the unified AR localization activity that handles both single-frame and multi-frame localization modes in a single implementation.

**Single-frame mode** is ideal for:

* Quick localization with low latency
* Environments with distinct visual features
* Limited network bandwidth scenarios

**Multi-frame mode** is ideal for:

* Higher accuracy requirements
* Environments with repetitive or sparse visual features
* When the user can move the device slightly during capture

The activity handles:

* AR session management using ARCore and Sceneform
* Single-frame and multi-frame capture and processing
* Localization animation with visual feedback
* Localization API requests
* Pose calculation and gizmo positioning
* 3D mesh visualization with radial reveal animation
* Background localization
* GPS hint integration

***

## Launching the Activity

The localization mode is passed via intent extra:

```kotlin
val intent = Intent(this, MultiSetLocalizationActivity::class.java)
intent.putExtra(
    MultiSetLocalizationActivity.EXTRA_LOCALIZATION_MODE,
    LocalizationMode.MULTI_FRAME.name  // or LocalizationMode.SINGLE_FRAME.name
)
startActivity(intent)
```

### Intent Extras

| Extra                     | Type     | Description                                                     |
| ------------------------- | -------- | --------------------------------------------------------------- |
| `EXTRA_LOCALIZATION_MODE` | `String` | The localization mode name: `"SINGLE_FRAME"` or `"MULTI_FRAME"` |

***

## Key Features

### Localization Animation

Both modes display an animated phone icon with visual feedback during capture, guiding users to move their device for better coverage.

### Auto-Localization

When `LocalizationConfig.autoLocalize` is enabled, localization starts automatically after the AR session is ready.

### Background Localization

When `LocalizationConfig.backgroundLocalization` is enabled, the activity periodically sends localization requests to refine positioning.

### Relocalization

When `LocalizationConfig.relocalization` is enabled, automatic relocalization is triggered when AR tracking state becomes PAUSED or STOPPED.

### GPS Hint

When `LocalizationConfig.enableGeoHint` is enabled, GPS coordinates are captured and sent as a hint to improve localization accuracy for large-scale maps.

### Localization Hints

Before sending a query, the activity reads optional localization hints from `LocalizationConfig` to narrow the search space:

* `hintMapCodes` — restricts a **mapSet** query to a subset of maps (ignored for single-map localization).
* `hintPosition` (`"x,y,z"`) and `hintFloorHeight` (`"floor,ceiling"`) — bias the search around a known area.
* `hintRadius` and `use2DFiltering` — spatial filters applied only when a geo hint or `hintPosition` is present.

See [LocalizationConfig → Localization Hints](/multiset/native-support/android-native/api-reference/localizationconfig.md#localization-hints) for the full reference.

### Mesh Visualization

When `LocalizationConfig.enableMeshVisualization` is enabled, a 3D mesh overlay with radial reveal animation is rendered after successful localization.

### Multi-Frame Capture

In multi-frame mode, captures multiple frames (configurable via `LocalizationConfig.numberOfFrames`) with intervals between captures (configurable via `LocalizationConfig.frameCaptureIntervalMs`). Each frame includes:

* Image data (JPEG compressed)
* Camera position (X, Y, Z)
* Camera rotation (quaternion)

***

## Public Methods

### localizeFrame()

Manually triggers the localization process.

**Declaration:**

```kotlin
fun localizeFrame()
```

**Description:** Captures frame(s) from the AR camera and sends to the MultiSet API for localization. In single-frame mode, captures one frame. In multi-frame mode, captures the configured number of frames at the configured interval.

**Usage:**

```kotlin
binding.localizeButton.setOnClickListener {
    localizeFrame()
}
```

***

### resetWorldOrigin()

Resets the AR world origin and clears the current localization.

**Declaration:**

```kotlin
fun resetWorldOrigin()
```

**Description:**

* Pauses and reconfigures the AR session
* Cancels any ongoing localization or background jobs
* Clears captured images
* Removes the mesh visualization
* Resets the gizmo position
* Optionally restarts auto-localization

***

## State Management

| Property                          | Type                     | Description                                     |
| --------------------------------- | ------------------------ | ----------------------------------------------- |
| `isLocalizing`                    | `Boolean`                | Whether localization is in progress             |
| `isFirstLocalization`             | `Boolean`                | Whether this is the first localization attempt  |
| `isBackgroundLocalizationRequest` | `Boolean`                | Whether current request is from background      |
| `lastTrackingState`               | `TrackingState`          | Previous AR tracking state                      |
| `isSessionConfigured`             | `Boolean`                | Whether AR session has been configured          |
| `capturedImages`                  | `MutableList<ImageData>` | List of captured frames (multi-frame mode)      |
| `uploadData`                      | `UploadData?`            | Camera intrinsics for upload (multi-frame mode) |

***

## Configuration

The activity reads configuration from `LocalizationConfig`:

```kotlin
LocalizationConfig.autoLocalize = true
LocalizationConfig.backgroundLocalization = true
LocalizationConfig.backgroundLocalizationIntervalSeconds = 30f
LocalizationConfig.relocalization = true
LocalizationConfig.numberOfFrames = 4                    // multi-frame only
LocalizationConfig.frameCaptureIntervalMs = 500L         // multi-frame only
LocalizationConfig.confidenceCheck = true
LocalizationConfig.confidenceThreshold = 0.3f            // valid range 0.2 - 0.8
LocalizationConfig.firstLocalizationUntilSuccess = true
LocalizationConfig.showAlerts = true
LocalizationConfig.enableMeshVisualization = true
LocalizationConfig.enableGeoHint = false
LocalizationConfig.includeGeoCoordinatesInResponse = false

// Localization hints (optional) — narrow the search before the query
LocalizationConfig.hintMapCodes = emptyList()            // mapSet: subset of maps
LocalizationConfig.hintPosition = ""                     // "x,y,z"
LocalizationConfig.hintFloorHeight = ""                  // "floor,ceiling"
LocalizationConfig.hintRadius = 25                       // meters (1 - 100)
LocalizationConfig.use2DFiltering = false

LocalizationConfig.imageQuality = 90
```

***

## Usage Examples

### Single-Frame Localization

```kotlin
// Configure for single-frame
LocalizationConfig.autoLocalize = true
LocalizationConfig.enableMeshVisualization = true
LocalizationConfig.validate()

// Launch activity
val intent = Intent(this, MultiSetLocalizationActivity::class.java)
intent.putExtra(
    MultiSetLocalizationActivity.EXTRA_LOCALIZATION_MODE,
    LocalizationMode.SINGLE_FRAME.name
)
startActivity(intent)
```

### Multi-Frame Localization

```kotlin
// Configure for multi-frame
LocalizationConfig.numberOfFrames = 5
LocalizationConfig.frameCaptureIntervalMs = 600L
LocalizationConfig.autoLocalize = true
LocalizationConfig.backgroundLocalization = true
LocalizationConfig.enableMeshVisualization = true
LocalizationConfig.validate()

// Launch activity
val intent = Intent(this, MultiSetLocalizationActivity::class.java)
intent.putExtra(
    MultiSetLocalizationActivity.EXTRA_LOCALIZATION_MODE,
    LocalizationMode.MULTI_FRAME.name
)
startActivity(intent)
```

***

## Related

* [MainActivity](/multiset/native-support/android-native/sample-activities/mainactivity.md)
* [LocalizationConfig](/multiset/native-support/android-native/api-reference/localizationconfig.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://multiset.gitbook.io/multiset/native-support/android-native/sample-activities/multisetlocalizationactivity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.