iOS Native

MultiSet VPS API Integration Guide for iOS Apps

Overview

This guide outlines the process for integrating MultiSet's Visual Positioning System (VPS) REST API with iOS applications using Swift and ARKit. The integration enables spatial localization within predefined maps or map sets.

Prerequisites

• Xcode 14.0+

• iOS 15.0+ target

• Swift 5.0+

• ARKit framework

• Active MultiSet developer account with API credentials

• Map ID or Map Set ID from the MultiSet platform

Authentication Flow

1. Obtain API Credentials: Store your client ID (username) and client secret (password) securely

2. Request Access Token:

   • Endpoint: https://api.multiset.ai/v1/m2m/token

   • Method: POST

   • Authentication: Basic Auth with username encoded in Base64

   • Response: JSON containing access token and expiration time

Configuration

Create a configuration model to store:

• Base URLs for authentication and VPS queries

• Map/MapSet IDs

• API credentials

• Selection mechanism for switching between Map and MapSet modes

ARKit Integration

1. Setup ARKit Session:

   • Configure ARWorldTrackingConfiguration

   • Initialize AR session with appropriate frame semantics

   • Set up session delegate to monitor tracking state

2. Create AR View:

   • Implement a UIViewRepresentable wrapper for ARView

   • Configure world alignment to gravity

   • Add visual cues (like coordinate axes) to represent the world origin

Localization Process

1. Capture Current Frame:

   • Access current ARFrame from AR session

   • Store current camera pose (position and rotation)

2. Process Camera Image:

   • Resize captured image to appropriate dimensions (e.g., 960×720)

   • Adjust camera intrinsics accordingly based on scaling factors

   • Convert resized image to JPEG format

3. Prepare API Request:

   • Endpoint: https://api.multiset.ai/v1/vps/map/query-form

   • Method: POST

   • Headers: Bearer token from authentication step

   • Format: Multipart form data with parameters and image

   • Parameters:

     • mapId or mapSetId (depending on localization mode)

     • isRightHanded: typically "true" for ARKit

     • Camera intrinsics: px, py, fx, fy

     • Image dimensions: width, height

     • Image data with field name "queryImage"

4. Process API Response:

   • Parse JSON response containing:

     • Boolean indicating if pose was found

     • Position (x, y, z coordinates)

     • Rotation (quaternion as x, y, z, w)

     • Confidence score

     • Map IDs used for localization

5. Transform Coordinate Systems:

   • Convert from MultiSet coordinate system to ARKit coordinate system

   • Apply necessary transformations to account for different handedness

   • Calculate final pose in AR world space

6. Visualize Results:

   • Update position and rotation of visual indicators (gizmos)

   • Provide user feedback about successful localization

MultiSet iOS Native SDK

Additionally, you can use the iOS Native SDK here: https://github.com/MultiSet-AI/multiset-ios-sdk