> 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/unity-sdk/on-device-localization.md).

# On-Device Localization

On-Device Localization allows your application to determine its position and orientation using the processing power of the device itself, without sending image data to the MultiSet Server. By downloading Offline Bundle for maps/mapsets and caching it locally, the device performs all localization processing internally.

### Overview & Use Cases

Unlike Cloud Localization, which relies on a network request to resolve Pose, On-Device Localization offers a self-contained solution. However, because high-fidelity 3D maps contain significant data, this method requires balancing storage usage against network independence.

#### Benefits

* **Zero Network Latency:** Eliminates uncertainty caused by fluctuating network speeds.
* **Offline Capability:** ideal for environments with no internet access (e.g., underground mines, remote industrial sites, high-security facilities).
* **Privacy & Security:** Camera frames are processed locally and never leave the device.

#### Considerations

* **Storage Impact:** Offline map bundles can range in the **100s of MBs**. This significantly increases the application size or the storage footprint on the user's device.
* **Hardware Dependency:** Response time relies entirely on the device's hardware.
  * High-end devices (e.g., latest iPhone/iPad): \~3-4 seconds.
  * Older devices: May experience slightly longer processing times.

**This solution is ideal for:** Restricted environments, enterprise applications where app size is not a constraint, or scenarios where map data changes infrequently.

{% hint style="success" %}

* On-Device Localization will support all existing maps that work with On-Cloud Localization
* On-Device Maps can be downloaded at runtime or included in your build (Streaming Asset)
* The current size recommendation for single maps is 50,000 sq feet for on-device (multiple maps can be combined to cover larger areas)
* On-Device Localization is supported on both **iOS** and **Android**
  {% endhint %}

### Prerequisites

* **Enterprise Plan:** On-Device Localization is an Enterprise-only feature. Please contact support to enable this on your account.
* **MultiSet-OnDevice Package:** This feature is delivered in a separate Unity package (**MultiSet-OnDevice.unitypackage**) containing the native iOS/Android binaries, prefabs, and sample scenes. Import it on top of the standard MultiSet Unity SDK. See [Importing the On-Device Package](/multiset/unity-sdk/on-device-localization/importing-the-on-device-package.md).
* **Registered App Identifier:** Your app's iOS Bundle ID and Android Package Name must be registered on the Developer Portal and match your Unity project's Bundle Identifier. Only apps with a matching identifier can download and run offline maps/objects. See [Register Your App Identifier](/multiset/unity-sdk/on-device-localization/importing-the-on-device-package.md#register-your-app-identifier-bundle-id).

### Setup Guide

#### Step 1: Request Offline Bundle Processing

Before Unity can utilize a map offline, the map data must be compiled into a specialized bundle format.

1. Log in to the **MultiSet Developer Portal**.
2. Navigate to your Map or MapSet.
3. Click **Offline Map** and click on **Request Processing**
4. The system will begin compiling the data. This typically takes **5–15 minutes** depending on the map size.
5. You will receive an email notification when processing is complete.

<figure><img src="/files/x5oCOy1V6gLxPUlXea0O" alt="" width="563"><figcaption></figcaption></figure>

Once finished, the portal will generate two files:

* **Offline Bundle (.bytes):** The raw map data.
* **Metadata File:** Configuration data required by the SDK.

<figure><img src="/files/4be0SCrPOiXg5kh2pxkZ" alt="" width="563"><figcaption></figcaption></figure>

> **Note:** You do not necessarily need to download these files manually, Unity SDK will configure these files in the Editor or in Runtime

#### Step 2: Unity Configuration

In your Unity Project, open the scene where you wish to enable localization.

1. Locate or open the **OnDeviceLocalization** scene from **MultiSet-OnDevice/Scenes/OnDeviceLocalization**.
2. Select the **OnDeviceLocalizationManager** GameObject and set the **Map or Mapset Code** on its component.
3. Set the **Localization Type** to Map (or MapSet depending on your use case).

<figure><img src="/files/OPTv0osUHddonuSGTxUw" alt="" width="390"><figcaption></figcaption></figure>

#### Step 3: Bundle Management Modes

You must decide how the device retrieves the heavy map data. This is controlled via the **Offline Bundle Download Mode** setting.

**Option A: Editor Mode (Embedded)**

The map bundle is downloaded inside the Unity Editor and built directly into the application (.apk/.ipa).

* **Pros:** Instant localization upon first launch; no runtime download needed.
* **Cons:** drastically increases the initial app download size.
* **Workflow:** Select **Editor** mode. The SDK will allow you to import the downloaded bundle files into your StreamingAssets or designated resource folder.

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

**Option B: Runtime Mode (On-Demand)**

The application is built without the map data. The SDK downloads the bundle from the MultiSet servers during the first run.

* **Pros:** Keeps the initial app install size small.
* **Cons:** Users must wait for the download to complete before the first localization can occur.
* **Workflow:** Select **Runtime** mode. The SDK handles the downloading and caching automatically.

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

> **Caching:** In both modes, files are cached locally on the device. Once the map is on the device, it does **not** need to be downloaded again unless the map is updated.

### Licensing & First Run

While the primary goal is "Offline" usage, there is a one-time requirement for internet connectivity.

> **Important:** On the very first launch of the application (or the first time the On-Device module is initialized), the device requires an active internet connection to **verify your account and registered App Identifier** and to **download the map/object assets**. This process may take some time depending on the map size.

* **First Run:** Internet Required (account/App Identifier verification + map/object asset download when using Runtime mode).
* **Subsequent Runs:** No Internet Required. The license token and assets are cached locally.

### Performance Tuning

The Localization Interval or Duration sliders in the Inspector control how frequently the device attempts to resolve its Pose.

* Since calculations are CPU/GPU intensive, setting this too aggressively may drain battery life.
* A gap of 20 to 40 seconds is recommended for most walking navigation scenarios.

### Build for iOS / Android

Before building the app for iOS or Android, make sure the scene is set up:

1. The **OnDeviceLocalization** scene (or your localization scene) is added to **Build Settings**.
2. The **Map or Mapset Code** is set on the **OnDeviceLocalizationManager** component.
3. If using **Editor** bundle mode, the offline bundle and metadata have been downloaded (the build will be stopped with a clear error if a bundle is missing). If using **Runtime** mode, the bundle is downloaded on first run instead.

On iOS, the `multiset_ios.framework` ships with the package and is configured automatically (see [Importing the On-Device Package](/multiset/unity-sdk/on-device-localization/importing-the-on-device-package.md)). For general build instructions, see [Building Steps](/multiset/unity-sdk/building-steps.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/unity-sdk/on-device-localization.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.