npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@maptiler/ar-control

v2.1.2

Published

AR Control for MapTiler SDK

Downloads

73

Readme

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! screenshot of the project's 3D view

Install

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>

Setup

The AR control requires to be used with our SDK (which is an extension of MapLibre).

// Get a free token at https://cloud.maptiler.com
// with a generous free tier!
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 
  })
})

Events

There are two events:

  • computeStart happens when the AR control starts computing the the 3D model, as soon as the AR button is clicked.
  • computeEnd happens when the AR control is done computing the model and is about to display it

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:

  • showButton (boolean): Shows the AR button if true, hide it otherwise. Default: true.
  • background (string): Background color (or any css-compatible string for gradient or image url). Default: "#FFFFFF" (white).
  • closeButtonClassName (string): CSS class to add to the close button on the AR modal. If none is provided, a default inline style is added Default: none.
  • closeButtonContent (string | HTMLElement): Content to add to the close button. If the content is a string, it is added as .innerHTML. If it's a DOM element, it is added as .appendChild(). Default: "Close".
  • arButtonClassName (string): CSS class to add to the AR button on the AR modal. If none is provided, a default inline style is added. Default: none
  • arButtonContent (string | HTMLElement): Content to add to the AR button. If the content is a string, it is added as .innerHTML. If it's a DOM element, it is added as .appendChild(). Default: "Close".
  • edgeColor (string): Color of the 3D model edges. Default: "#0eaeff" (grayish teal)
  • logo (string): a URL to a logo placed at the bottom of the 3D view when AR mode is not enabled. By default, the logo will have an height of 60 pixel and be placed at the bottom left corner with a margin of 10 pixels.
  • logoHeight(number): the height of the logo in pixels (if any). Default: 60
  • logoClass (string): CSS class to add to the class list of the <img> element holding the logo (if any). If used, the .logoHeight as well as the default styling will no longer be applied.
  • activateAR (boolean): When the platform allows, setting this to true automatically activates the AR mode as soon as the data is ready. Quick Look on iOS is likely to allow this, while WebXR on Android is not likeley to. Default: false
  • highRes (boolean): increases the resolution of the texture. Will most likely have no effect on iOS due to some format limitation. Default: false.

Methods

  • .run(): programmatically run the computation of the 3D model. This can be used in replacement of a click on the control
  • .close(): programmatically closes the overlay containing the 3D model
  • .updateLogo(src: string): updates the src of the logo. This can only be used if the .logo option was set in the constructor. Can be coupled with the computeStart event to refresh the information, for isntance a dynamically generated QR code that would contain info about the place being processed.

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

License

See LICENSE.md