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:

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.

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:

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:

binding.localizeButton.setOnClickListener {
    localizeFrame()
}

---

resetWorldOrigin()

Resets the AR world origin and clears the current localization.

Declaration:

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:

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 = false
LocalizationConfig.confidenceThreshold = 0.3f
LocalizationConfig.firstLocalizationUntilSuccess = true
LocalizationConfig.showAlerts = true
LocalizationConfig.enableMeshVisualization = true
LocalizationConfig.enableGeoHint = false
LocalizationConfig.includeGeoCoordinatesInResponse = false
LocalizationConfig.imageQuality = 90

---

Usage Examples

Single-Frame Localization

// 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

// 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

• LocalizationConfig