feat: require reference to THREE in constructor (#380)

BREAKING CHANGE: requires passing THREE to ThreeJSOverlayView({THREE})

README.md

@@ -41,14 +41,17 @@ Checkout the the reference [documentation](https://googlemaps.github.io/js-three
 
 <img src="https://storage.googleapis.com/geo-devrel-public-buckets/orientation.jpg" alt="orientation of axes" width="400"/>
 
+> 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.
 
 ```js
+import * as THREE from 'three';
 const map = new google.maps.Map(document.getElementById("map"), mapOptions);
 // instantiate a ThreeJS Scene
-const scene = new Scene();
+const scene = new THREE.Scene();
 
 // Create a box mesh
 const box = new Mesh(
@@ -68,6 +71,7 @@ scene.add(box);
 new ThreeJSOverlayView({
   scene,
   map,
+  THREE,
 });
 
 // rotate the box using requestAnimationFrame

examples/anchor.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { AxesHelper, Scene } from "three";
+import * as THREE from "three";
 import { LOADER_OPTIONS, MAP_ID } from "./config";
 import { ThreeJSOverlayView, WORLD_SIZE } from "../src";
 
@@ -33,14 +33,15 @@ const mapOptions = {
 
 new Loader(LOADER_OPTIONS).load().then(() => {
   const map = new google.maps.Map(document.getElementById("map"), mapOptions);
-  const scene = new Scene();
+  const scene = new THREE.Scene();
 
-  scene.add(new AxesHelper(WORLD_SIZE));
+  scene.add(new THREE.AxesHelper(WORLD_SIZE));
 
   // add ThreeJS Overlay view anchored to center of map
   new ThreeJSOverlayView({
     anchor: { ...mapOptions.center, altitude: 0 },
     scene,
     map,
+    THREE,
   });
 });

examples/basic.ts

@@ -14,13 +14,7 @@
  * limitations under the License.
  */
 
-import {
-  BoxBufferGeometry,
-  MathUtils,
-  Mesh,
-  MeshNormalMaterial,
-  Scene,
-} from "three";
+import * as THREE from "three";
 import { LOADER_OPTIONS, MAP_ID } from "./config";
 import { ThreeJSOverlayView, latLngToVector3 } from "../src";
 
@@ -41,12 +35,12 @@ new Loader(LOADER_OPTIONS).load().then(() => {
   // instantiate the map
   const map = new google.maps.Map(document.getElementById("map"), mapOptions);
   // instantiate a ThreeJS Scene
-  const scene = new Scene();
+  const scene = new THREE.Scene();
 
   // Create a box mesh
-  const box = new Mesh(
-    new BoxBufferGeometry(10, 50, 10),
-    new MeshNormalMaterial()
+  const box = new THREE.Mesh(
+    new THREE.BoxBufferGeometry(10, 50, 10),
+    new THREE.MeshNormalMaterial()
   );
 
   // set position at center of map
@@ -61,11 +55,12 @@ new Loader(LOADER_OPTIONS).load().then(() => {
   const overlay = new ThreeJSOverlayView({
     scene,
     map,
+    THREE,
   });
 
   // rotate the box using requestAnimationFrame
   const animate = () => {
-    box.rotateY(MathUtils.degToRad(0.1));
+    box.rotateY(THREE.MathUtils.degToRad(0.1));
 
     requestAnimationFrame(animate);
   };

examples/hemispheres.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { BoxBufferGeometry, Mesh, MeshNormalMaterial, Scene } from "three";
+import * as THREE from "three";
 import { LOADER_OPTIONS, MAP_ID } from "./config";
 import { ThreeJSOverlayView, latLngToVector3 } from "../src";
 
@@ -34,7 +34,7 @@ new Loader(LOADER_OPTIONS).load().then(() => {
   // instantiate the map
   const map = new google.maps.Map(document.getElementById("map"), mapOptions);
   // instantiate a ThreeJS Scene
-  const scene = new Scene();
+  const scene = new THREE.Scene();
 
   [
     { lat: 45, lng: -90 },
@@ -43,9 +43,9 @@ new Loader(LOADER_OPTIONS).load().then(() => {
     { lat: -45, lng: 90 },
   ].forEach((latLng: google.maps.LatLngLiteral) => {
     // Create a box mesh
-    const box = new Mesh(
-      new BoxBufferGeometry(10, 50, 10),
-      new MeshNormalMaterial()
+    const box = new THREE.Mesh(
+      new THREE.BoxBufferGeometry(10, 50, 10),
+      new THREE.MeshNormalMaterial()
     );
 
     box.scale.multiplyScalar(10000);
@@ -63,5 +63,6 @@ new Loader(LOADER_OPTIONS).load().then(() => {
   const overlay = new ThreeJSOverlayView({
     scene,
     map,
+    THREE,
   });
 });

examples/orientation.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { AxesHelper, Scene } from "three";
+import * as THREE from "three";
 import { LOADER_OPTIONS, MAP_ID } from "./config";
 import { ThreeJSOverlayView, WORLD_SIZE } from "../src";
 
@@ -33,12 +33,13 @@ const mapOptions = {
 
 new Loader(LOADER_OPTIONS).load().then(() => {
   const map = new google.maps.Map(document.getElementById("map"), mapOptions);
-  const scene = new Scene();
+  const scene = new THREE.Scene();
 
-  scene.add(new AxesHelper(WORLD_SIZE));
+  scene.add(new THREE.AxesHelper(WORLD_SIZE));
 
   new ThreeJSOverlayView({
     scene,
     map,
+    THREE,
   });
 });

examples/treeshake.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  Scene,
+  WebGLRenderer,
+  PerspectiveCamera,
+  PCFSoftShadowMap,
+  sRGBEncoding,
+  Mesh,
+  BoxBufferGeometry,
+  MeshNormalMaterial,
+  MathUtils,
+} from "three";
+
+import { LOADER_OPTIONS, MAP_ID } from "./config";
+import { ThreeJSOverlayView, latLngToVector3 } from "../src";
+
+import { Loader } from "@googlemaps/js-api-loader";
+
+const mapOptions = {
+  center: {
+    lng: -122.34378755092621,
+    lat: 47.607465080615476,
+  },
+  mapId: MAP_ID,
+  zoom: 15,
+  heading: 45,
+  tilt: 67,
+};
+
+new Loader(LOADER_OPTIONS).load().then(() => {
+  // instantiate the map
+  const map = new google.maps.Map(document.getElementById("map"), mapOptions);
+  // instantiate a ThreeJS Scene
+  const scene = new 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
+  const overlay = new ThreeJSOverlayView({
+    scene,
+    map,
+    THREE: {
+      Scene,
+      WebGLRenderer,
+      PerspectiveCamera,
+      PCFSoftShadowMap,
+      sRGBEncoding,
+    },
+  });
+
+  // rotate the box using requestAnimationFrame
+  const animate = () => {
+    box.rotateY(MathUtils.degToRad(0.1));
+
+    requestAnimationFrame(animate);
+  };
+
+  requestAnimationFrame(animate);
+});