Google Maps ThreeJS Overlay View and Utilities

Description

Add three.js objects to Google Maps Platform JS. The library provides a ThreeJSOverlayView class extending google.maps.WebGLOverlayView and utility functions such as latLngToMeters, latLngToVector3, and latLngToVector3Relative, for converting latitude and longitude to vectors in the mercator coordinate space.

Note: This library requires the beta version of Google Maps Platform JavaScript.

Install

Available via npm as the package @googlemaps/three.

npm i @googlemaps/three

Alternatively you may add the umd package directly to the html document using the unpkg link.

<script src="https://unpkg.com/@googlemaps/three/dist/index.min.js"></script>

When adding via unpkg, the package can be accessed at google.maps.plugins.three. A version can be specified by using https://unpkg.com/@googlemaps/three@VERSION/dist/....

If you get the error, Uncaught ReferenceError: three is not defined, please see this discussion.

Documentation

Checkout the the reference documentation.

Note: All methods and objects in this library follow a default up axis of (0, 1, 0), y up, matching that of three.js.

Note: You must pass a reference to THREE in the constructor of the ThreeJSOverlayView class. It may be beneficial to pass a subset of THREE to better enable tree shaking.

Example

The following example provides a skeleton for adding objects to the map with this library.

import * as THREE from 'three';
const map = new google.maps.Map(document.getElementById("map"), mapOptions);
// instantiate a ThreeJS Scene
const scene = new THREE.Scene();

// Create a box mesh
const box = new Mesh(
  new BoxBufferGeometry(10, 50, 10),
  new MeshNormalMaterial(),
);

// set position at center of map
box.position.copy(latLngToVector3(mapOptions.center));
// set position vertically
box.position.setY(25);

// add box mesh to the scene
scene.add(box);

// instantiate the ThreeJS Overlay with the scene and map
new ThreeJSOverlayView({
  scene,
  map,
  THREE,
});

// rotate the box using requestAnimationFrame
const animate = () => {
  box.rotateY(MathUtils.degToRad(0.1));

  requestAnimationFrame(animate);
};

// start animation loop
requestAnimationFrame(animate);

This adds a box to the map.

Demos