maptiler-ar-control

Company Logo

AR Control for MapTiler SDK JS

This AR control adds a button on your MapTiler SDK’s Map to create a 3D model of the viewport, including 3D terrain and any layer you have put on top.
If your device is compatible with WebXR or Apple Quick Look, the Enable AR button will show up. Then you can position and interact with the 3D model on your own space!

📖 Documentation   📦 NPM Package   🌐 Website   🔑 Get API Key


Table of Contents

Demo Screenshot
See live interactive demo


📦 Installation

ES module from NPM

npm install @maptiler/sdk @maptiler/ar-control

Then in your code, import the control:

// Import MapTiler SDK
import * as maptilersdk from "@maptiler/sdk";

// Import the AR Control
import * as maptilerarcontrol from "@maptiler/ar-control";
// Or specifically:
import { MaptilerARControl } from "@maptiler/ar-control";

⚠️ with NextJS, the AR control module must be dynamically imported:

const maptilerarcontrol = await import("@maptiler/ar-control");

This must be done in hook that is only executed client side (or inside componentDidMount, in the case of class components). This is due to the AR Control dependency to ModelViewer that needs to acces the global object window. NextJS will attempt SSR, where window is not defined and this will result in an error.

Vanilla JS from CDN (UMD bundles)

<!-- Make sure you enable device pixel ratio greater than 1 -->
<meta name="viewport" content="width=device-width, initial-scale=1">

<!-- Import MapTiler SDK -->
<script src="https://cdn.maptiler.com/maptiler-sdk-js/latest/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/latest/maptiler-sdk.css" rel="stylesheet" />

<!-- Import the AR Control -->
<script src="https://cdn.maptiler.com/maptiler-ar-control/latest/maptiler-ar-control.umd.js"></script>


🚀 Basic Usage

The AR control requires to be used with the MapTiler SDK JS.

maptilersdk.config.apiKey = 'YOUR_MAPTILER_CLOUD_TOKEN';

// Creating a map
const map = new maptilersdk.Map({
  container: 'map',
  style: maptilersdk.MapStyle.OUTDOOR,
  terrain: true,
  hash: true,
  geolocate: true,
});

// Waiting for the map to be ready
map.on("load", (e) => {
  // Creating the control
  const arControl = new maptilerarcontrol.MaptilerARControl();
  
  // Adding the AR control on the top-left corner of the map
  map.addControl(arControl, "top-left");

  arControl.on("computeStart", (e) => {
    // Do something when the control starts to compute the 3D model 
  })

  arControl.on("computeEnd", (e) => {
    // Do something when the control is done computing the 3D model 
  })
})


💡 Related Examples

Check out the full list of MapTiler examples


📘 API Reference

For detailed guides, API reference, and advanced examples, visit our comprehensive documentation:

API documentation

Events

There are two events:

The AR control performs some temporary changes to the map view, so these events are handy to hide those transformations behind a curtain or displaying a message.

In the example, we show a fullscreen overlay with a waiting message at computeStart and hides it at computeEnd, just by dynamically updating the .style.display property of the overlay. Keep in mind that the z-index CSS property of this overlay must be higher than the 3D model view, so greater than 3.
When using React, you may want to replace this logic by a change of state.

Options

The constructor MaptilerARControl accepts an option object to customize the look and feel. Here are the attributes:

Methods

Capacitor integration (iOS)

MapTiler SDK can be used efficiently with CapacitorJS to create beautiful native maps-centric apps. This AR Control has been design to work in such scenario, though a different scenrio is unrolled internaly: there will be no intermediate 3D model and instead Apple Quicklook will directly open.

Your mobile app (or at least the compinent that installed on the mobile device) needs to have these Capacitor dependencies installed:

npm install @capacitor/core @capacitor/filesystem @capacitor-community/file-opener


💬 Support



🤝 Contributing

We love contributions from the community! Whether it’s bug reports, feature requests, or pull requests, all contributions are welcome:


📄 License

This project is licensed under the MapTiler JS Module – see the LICENSE file for details.


🙏 Acknowledgements

This project is built on the shoulders of giants:


Get Your API Key FREE
Start building with 100,000 free map loads per month ・ No credit card required.


💜 Made with love by the MapTiler team

Website • Documentation • GitHub

This site is open source. Improve this page.