Immersal VPS for Web

Immersal VPS for Web (aka WebAR)

This is a sample of how to use Immersal's Visual Positioning System (VPS) for on-device localization natively on a (mobile) Web browser. It can be used e.g. for persistent and anchored WebAR experiences, and to retrieve the user's position in global coordinates (latitude, longitude, altitude) from the camera image.

What's new (Feb 07, 2025)

• Added Babylon.js sample
• Improved UI for localization testing (split into on-device / on-server modes)
• Improved pose filtering
• Minor bug fixes
• Recompiled Wasm components with Emscripten 4.0.2

Features

• Localizes against Immersal maps created with the Mapper app (App Store, Play Store), BLK2GO, 360 cameras... 100% compatible.
• Very lean JavaScript ES6 module implementation
• WGS84/ECEF support (a localized pose contains the information in global coordinates if the map itself has been saved with GPS coordinates)
• Works in both portrait and landscape orientations
• Supports both Three.js and Babylon.js
• Uses the device IMU for orientation tracking, and continuous localization for translation (position) tracking to emulate SLAM
• Supports either one-shot or continuous localization
• Supports both on-device and on-server localization (through the Immersal REST API)

Compatibility

• iOS Safari
• Android Chrome
• etc., latest versions -- should work on all modern mobile browsers, contact us if it doesn't

Prerequisites

• Immersal Developer account
• Immersal Pro plan subscription
• Modern mobile device with:
  • WebGL support
  • Camera access
  • Orientation sensors

Development Setup

1. HTTPS Setup

Modern browsers require HTTPS for accessing device cameras and sensors. For development, you can:

Using npm:

# Install http-server globally
npm install -g http-server
# Generate self-signed certificate
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
# Start HTTPS server
http-server -S -C cert.pem -K key.pem

2. Configuration

1. Make a copy of js/imConfig_template.js as js/imConfig.js
2. Enter your developer token and map ID(s) in imConfig.js:

export const immersalParams = {
  developerToken: "your_token", // From developer.immersal.com
  mapIds: [your_map_id], // From Immersal Mapper app
  continuousLocalization: true,
  continuousInterval: 16,
  imageDownScale: 0.25,
  solverType: 1,
};

3. Device Setup

For development and testing:

1. iOS Safari:

   • Enable Web Inspector: Settings > Safari > Advanced > Web Inspector
   • Connect iPhone to Mac for debugging
   • Use Safari on Mac: Develop > [Your iPhone] > [Web Page]

2. Android Chrome:

   • Enable USB debugging
   • Chrome on desktop: chrome://inspect

4. Required Permissions

The app requires access to:

• Camera (for localization)
• Device orientation sensors (for rotational tracking)
• HTTPS (required for accessing device features)

5. Troubleshooting

Common issues:

• 400 errors: Check developer token and map ID validity
• Camera not opening: Ensure HTTPS is properly set up
• Localization fails: Verify map ID and check if the area is mapped
• Orientation tracking issues: Check device sensor permissions

Future improvements

• Common API to replace "SLAM tracking" with other tracking implementations (native Android Chrome WebXR/ARCore, App Clips, Zappar World Tracking, 8th Wall World Tracking, etc.)
• Accuracy, speed, and size

Notes

• This is the "standalone version" of Immersal VPS for Web. You can also use it with Zappar's excellent Mattercraft tool, which is using Zappar's proprietary World Tracking (meaning that you don't have to use continuous localization with Immersal, every few seconds is probably enough). See videos: Transforming location based AR experiences through the web with Mattercraft and Immersal, Introducing Mattercraft's New Integration with Immersal VPS
• Support for on-device localization with 8th Wall or WeChat isn't planned at the moment, if you need it, contact us and let's talk.