import{AmbientLight,DirectionalLight,Matrix4,PerspectiveCamera,Scene,WebGLRenderer,}from"three";import{GLTFLoader}from"three/examples/jsm/loaders/GLTFLoader";letmap:google.maps.Map;constmapOptions={tilt:0,heading:0,zoom:18,center:{lat:35.6594945,lng:139.6999859},mapId:"15431d2b469f209e",// disable interactions due to animation loop and moveCameradisableDefaultUI:true,gestureHandling:"none",keyboardShortcuts:false,};functioninitMap():void{constmapDiv=document.getElementById("map")asHTMLElement;map=newgoogle.maps.Map(mapDiv,mapOptions);initWebglOverlayView(map);}functioninitWebglOverlayView(map:google.maps.Map):void{letscene,renderer,camera,loader;constwebglOverlayView=newgoogle.maps.WebGLOverlayView();webglOverlayView.onAdd=()=>{// Set up the scene.scene=newScene();camera=newPerspectiveCamera();constambientLight=newAmbientLight(0xffffff,0.75);// Soft white light.scene.add(ambientLight);constdirectionalLight=newDirectionalLight(0xffffff,0.25);directionalLight.position.set(0.5,-1,0.5);scene.add(directionalLight);// Load the model.loader=newGLTFLoader();constsource="https://raw.githubusercontent.com/googlemaps/js-samples/main/assets/pin.gltf";loader.load(source,(gltf)=>{gltf.scene.scale.set(10,10,10);gltf.scene.rotation.x=Math.PI;// Rotations are in radians.scene.add(gltf.scene);});};webglOverlayView.onContextRestored=({gl})=>{// Create the js renderer, using the// maps's WebGL rendering context.renderer=newWebGLRenderer({canvas:gl.canvas,context:gl,...gl.getContextAttributes(),});renderer.autoClear=false;// Wait to move the camera until the 3D model loads.loader.manager.onLoad=()=>{renderer.setAnimationLoop(()=>{webglOverlayView.requestRedraw();const{tilt,heading,zoom}=mapOptions;map.moveCamera({tilt,heading,zoom});// Rotate the map 360 degrees.if(mapOptions.tilt<67.5){mapOptions.tilt+=0.5;}elseif(mapOptions.heading<=360){mapOptions.heading+=0.2;mapOptions.zoom-=0.0005;}else{renderer.setAnimationLoop(null);}});};};webglOverlayView.onDraw=({gl,transformer}):void=>{constlatLngAltitudeLiteral:google.maps.LatLngAltitudeLiteral={lat:mapOptions.center.lat,lng:mapOptions.center.lng,altitude:100,};// Update camera matrix to ensure the model is georeferenced correctly on the map.constmatrix=transformer.fromLatLngAltitude(latLngAltitudeLiteral);camera.projectionMatrix=newMatrix4().fromArray(matrix);webglOverlayView.requestRedraw();renderer.render(scene,camera);// Sometimes it is necessary to reset the GL state.renderer.resetState();};webglOverlayView.setMap(map);}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
import{AmbientLight,DirectionalLight,Matrix4,PerspectiveCamera,Scene,WebGLRenderer,}from"three";import{GLTFLoader}from"three/examples/jsm/loaders/GLTFLoader";letmap;constmapOptions={tilt:0,heading:0,zoom:18,center:{lat:35.6594945,lng:139.6999859},mapId:"15431d2b469f209e",// disable interactions due to animation loop and moveCameradisableDefaultUI:true,gestureHandling:"none",keyboardShortcuts:false,};functioninitMap(){constmapDiv=document.getElementById("map");map=newgoogle.maps.Map(mapDiv,mapOptions);initWebglOverlayView(map);}functioninitWebglOverlayView(map){letscene,renderer,camera,loader;constwebglOverlayView=newgoogle.maps.WebGLOverlayView();webglOverlayView.onAdd=()=>{// Set up the scene.scene=newScene();camera=newPerspectiveCamera();constambientLight=newAmbientLight(0xffffff,0.75);// Soft white light.scene.add(ambientLight);constdirectionalLight=newDirectionalLight(0xffffff,0.25);directionalLight.position.set(0.5,-1,0.5);scene.add(directionalLight);// Load the model.loader=newGLTFLoader();constsource="https://raw.githubusercontent.com/googlemaps/js-samples/main/assets/pin.gltf";loader.load(source,(gltf)=>{gltf.scene.scale.set(10,10,10);gltf.scene.rotation.x=Math.PI;// Rotations are in radians.scene.add(gltf.scene);});};webglOverlayView.onContextRestored=({gl})=>{// Create the js renderer, using the// maps's WebGL rendering context.renderer=newWebGLRenderer({canvas:gl.canvas,context:gl,...gl.getContextAttributes(),});renderer.autoClear=false;// Wait to move the camera until the 3D model loads.loader.manager.onLoad=()=>{renderer.setAnimationLoop(()=>{webglOverlayView.requestRedraw();const{tilt,heading,zoom}=mapOptions;map.moveCamera({tilt,heading,zoom});// Rotate the map 360 degrees.if(mapOptions.tilt<67.5){mapOptions.tilt+=0.5;}elseif(mapOptions.heading<=360){mapOptions.heading+=0.2;mapOptions.zoom-=0.0005;}else{renderer.setAnimationLoop(null);}});};};webglOverlayView.onDraw=({gl,transformer})=>{constlatLngAltitudeLiteral={lat:mapOptions.center.lat,lng:mapOptions.center.lng,altitude:100,};// Update camera matrix to ensure the model is georeferenced correctly on the map.constmatrix=transformer.fromLatLngAltitude(latLngAltitudeLiteral);camera.projectionMatrix=newMatrix4().fromArray(matrix);webglOverlayView.requestRedraw();renderer.render(scene,camera);// Sometimes it is necessary to reset the GL state.renderer.resetState();};webglOverlayView.setMap(map);}window.initMap=initMap;
/** Always set the map height explicitly to define the size of the div element* that contains the map.*/#map{height:100%;}/** Optional: Makes the sample page fill the window.*/html,body{height:100%;margin:0;padding:0;}#map{pointer-events:none;}
<html>
<head>
<title>Simple WebGL Overlay</title>
<script src="https://unpkg.com/three@0.129.0/build/three.min.js"></script>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<div id="map" class="map"></div>
<!--
The `defer` attribute causes the script to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises. See
https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
defer
></script>
</body>
</html>
Git and Node.js are required to run this sample locally. Follow theseinstructionsto install Node.js and NPM. The following commands clone, install dependencies and start the sample application.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis example showcases the use of \u003ccode\u003eWebGLOverlayView\u003c/code\u003e to render a 3D model with animation on a Google Map.\u003c/p\u003e\n"],["\u003cp\u003eIt uses the Three.js library for 3D rendering and a GLTF model of a pin as the displayed object.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eWebGLOverlayView\u003c/code\u003e handles the integration between the 3D scene and the map, ensuring proper georeferencing and rendering.\u003c/p\u003e\n"],["\u003cp\u003eThe code includes a simple animation loop that rotates the map and the 3D model, providing a dynamic visual experience.\u003c/p\u003e\n"],["\u003cp\u003eUsers can interact with the provided code snippets in Typescript, JavaScript, CSS, and HTML, and there's an option to try a live sample or clone the repository for local execution.\u003c/p\u003e\n"]]],[],null,["# WebGL Overlay (native API)\n\nThis example demonstrates using the `WebGLOverlayView` to display a 3D image\nwith animation on a vector map.\n\nRead the [documentation](/maps/documentation/javascript/webgl/webgl-overlay-view). \n\n### TypeScript\n\n```typescript\nimport {\n AmbientLight,\n DirectionalLight,\n Matrix4,\n PerspectiveCamera,\n Scene,\n WebGLRenderer,\n} from \"three\";\n\nimport { GLTFLoader } from \"three/examples/jsm/loaders/GLTFLoader\";\n\nlet map: google.maps.Map;\n\nconst mapOptions = {\n tilt: 0,\n heading: 0,\n zoom: 18,\n center: { lat: 35.6594945, lng: 139.6999859 },\n mapId: \"15431d2b469f209e\",\n // disable interactions due to animation loop and moveCamera\n disableDefaultUI: true,\n gestureHandling: \"none\",\n keyboardShortcuts: false,\n};\n\nfunction initMap(): void {\n const mapDiv = document.getElementById(\"map\") as HTMLElement;\n map = new google.maps.Map(mapDiv, mapOptions);\n initWebglOverlayView(map);\n}\n\nfunction initWebglOverlayView(map: google.maps.Map): void {\n let scene, renderer, camera, loader;\n const webglOverlayView = new google.maps.WebGLOverlayView();\n\n webglOverlayView.onAdd = () =\u003e {\n // Set up the scene.\n\n scene = new Scene();\n\n camera = new PerspectiveCamera();\n\n const ambientLight = new AmbientLight(0xffffff, 0.75); // Soft white light.\n scene.add(ambientLight);\n\n const directionalLight = new DirectionalLight(0xffffff, 0.25);\n directionalLight.position.set(0.5, -1, 0.5);\n scene.add(directionalLight);\n\n // Load the model.\n loader = new GLTFLoader();\n const source =\n \"https://raw.githubusercontent.com/googlemaps/js-samples/main/assets/pin.gltf\";\n loader.load(source, (gltf) =\u003e {\n gltf.scene.scale.set(10, 10, 10);\n gltf.scene.rotation.x = Math.PI; // Rotations are in radians.\n scene.add(gltf.scene);\n });\n };\n\n webglOverlayView.onContextRestored = ({ gl }) =\u003e {\n // Create the js renderer, using the\n // maps's WebGL rendering context.\n renderer = new WebGLRenderer({\n canvas: gl.canvas,\n context: gl,\n ...gl.getContextAttributes(),\n });\n renderer.autoClear = false;\n\n // Wait to move the camera until the 3D model loads.\n loader.manager.onLoad = () =\u003e {\n renderer.setAnimationLoop(() =\u003e {\n webglOverlayView.requestRedraw();\n const { tilt, heading, zoom } = mapOptions;\n map.moveCamera({ tilt, heading, zoom });\n\n // Rotate the map 360 degrees.\n if (mapOptions.tilt \u003c 67.5) {\n mapOptions.tilt += 0.5;\n } else if (mapOptions.heading \u003c= 360) {\n mapOptions.heading += 0.2;\n mapOptions.zoom -= 0.0005;\n } else {\n renderer.setAnimationLoop(null);\n }\n });\n };\n };\n\n webglOverlayView.onDraw = ({ gl, transformer }): void =\u003e {\n const latLngAltitudeLiteral: google.maps.LatLngAltitudeLiteral = {\n lat: mapOptions.center.lat,\n lng: mapOptions.center.lng,\n altitude: 100,\n };\n\n // Update camera matrix to ensure the model is georeferenced correctly on the map.\n const matrix = transformer.fromLatLngAltitude(latLngAltitudeLiteral);\n camera.projectionMatrix = new Matrix4().fromArray(matrix);\n\n webglOverlayView.requestRedraw();\n renderer.render(scene, camera);\n\n // Sometimes it is necessary to reset the GL state.\n renderer.resetState();\n };\n webglOverlayView.setMap(map);\n}\n\ndeclare global {\n interface Window {\n initMap: () =\u003e void;\n }\n}\nwindow.initMap = initMap;https://github.com/googlemaps/js-samples/blob/2683f7366fb27829401945d2a7e27d77ed2df8e5/samples/webgl-overlay-simple/index.ts#L8-L133\n```\n| **Note:** Read the [guide](/maps/documentation/javascript/using-typescript) on using TypeScript and Google Maps.\n\n### JavaScript\n\n```javascript\nimport {\n AmbientLight,\n DirectionalLight,\n Matrix4,\n PerspectiveCamera,\n Scene,\n WebGLRenderer,\n} from \"three\";\nimport { GLTFLoader } from \"three/examples/jsm/loaders/GLTFLoader\";\nlet map;\nconst mapOptions = {\n tilt: 0,\n heading: 0,\n zoom: 18,\n center: { lat: 35.6594945, lng: 139.6999859 },\n mapId: \"15431d2b469f209e\",\n // disable interactions due to animation loop and moveCamera\n disableDefaultUI: true,\n gestureHandling: \"none\",\n keyboardShortcuts: false,\n};\n\nfunction initMap() {\n const mapDiv = document.getElementById(\"map\");\n\n map = new google.maps.Map(mapDiv, mapOptions);\n initWebglOverlayView(map);\n}\n\nfunction initWebglOverlayView(map) {\n let scene, renderer, camera, loader;\n const webglOverlayView = new google.maps.WebGLOverlayView();\n\n webglOverlayView.onAdd = () =\u003e {\n // Set up the scene.\n scene = new Scene();\n camera = new PerspectiveCamera();\n\n const ambientLight = new AmbientLight(0xffffff, 0.75); // Soft white light.\n\n scene.add(ambientLight);\n\n const directionalLight = new DirectionalLight(0xffffff, 0.25);\n\n directionalLight.position.set(0.5, -1, 0.5);\n scene.add(directionalLight);\n // Load the model.\n loader = new GLTFLoader();\n\n const source =\n \"https://raw.githubusercontent.com/googlemaps/js-samples/main/assets/pin.gltf\";\n\n loader.load(source, (gltf) =\u003e {\n gltf.scene.scale.set(10, 10, 10);\n gltf.scene.rotation.x = Math.PI; // Rotations are in radians.\n scene.add(gltf.scene);\n });\n };\n\n webglOverlayView.onContextRestored = ({ gl }) =\u003e {\n // Create the js renderer, using the\n // maps's WebGL rendering context.\n renderer = new WebGLRenderer({\n canvas: gl.canvas,\n context: gl,\n ...gl.getContextAttributes(),\n });\n renderer.autoClear = false;\n // Wait to move the camera until the 3D model loads.\n loader.manager.onLoad = () =\u003e {\n renderer.setAnimationLoop(() =\u003e {\n webglOverlayView.requestRedraw();\n\n const { tilt, heading, zoom } = mapOptions;\n\n map.moveCamera({ tilt, heading, zoom });\n // Rotate the map 360 degrees.\n if (mapOptions.tilt \u003c 67.5) {\n mapOptions.tilt += 0.5;\n } else if (mapOptions.heading \u003c= 360) {\n mapOptions.heading += 0.2;\n mapOptions.zoom -= 0.0005;\n } else {\n renderer.setAnimationLoop(null);\n }\n });\n };\n };\n\n webglOverlayView.onDraw = ({ gl, transformer }) =\u003e {\n const latLngAltitudeLiteral = {\n lat: mapOptions.center.lat,\n lng: mapOptions.center.lng,\n altitude: 100,\n };\n // Update camera matrix to ensure the model is georeferenced correctly on the map.\n const matrix = transformer.fromLatLngAltitude(latLngAltitudeLiteral);\n\n camera.projectionMatrix = new Matrix4().fromArray(matrix);\n webglOverlayView.requestRedraw();\n renderer.render(scene, camera);\n // Sometimes it is necessary to reset the GL state.\n renderer.resetState();\n };\n\n webglOverlayView.setMap(map);\n}\n\nwindow.initMap = initMap;https://github.com/googlemaps/js-samples/blob/2683f7366fb27829401945d2a7e27d77ed2df8e5/dist/samples/webgl-overlay-simple/docs/index.js#L7-L125\n```\n| **Note:** The JavaScript is compiled from the TypeScript snippet.\n\n### CSS\n\n```css\n/* \n * Always set the map height explicitly to define the size of the div element\n * that contains the map. \n */\n#map {\n height: 100%;\n}\n\n/* \n * Optional: Makes the sample page fill the window. \n */\nhtml,\nbody {\n height: 100%;\n margin: 0;\n padding: 0;\n}\n\n#map {\n pointer-events: none;\n}\nhttps://github.com/googlemaps/js-samples/blob/2683f7366fb27829401945d2a7e27d77ed2df8e5/dist/samples/webgl-overlay-simple/docs/style.css#L7-L28\n```\n\n### HTML\n\n```html\n\u003chtml\u003e\n \u003chead\u003e\n \u003ctitle\u003eSimple WebGL Overlay\u003c/title\u003e\n\n \u003cscript src=\"https://unpkg.com/three@0.129.0/build/three.min.js\"\u003e\u003c/script\u003e\n\n \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"./style.css\" /\u003e\n \u003cscript type=\"module\" src=\"./index.js\"\u003e\u003c/script\u003e\n \u003c/head\u003e\n \u003cbody\u003e\n \u003cdiv id=\"map\" class=\"map\"\u003e\u003c/div\u003e\n\n \u003c!-- \n The `defer` attribute causes the script to execute after the full HTML\n document has been parsed. For non-blocking uses, avoiding race conditions,\n and consistent behavior across browsers, consider loading using Promises. See\n https://developers.google.com/maps/documentation/javascript/load-maps-js-api\n for more information.\n --\u003e\n \u003cscript\n src=\"https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly\"\n defer\n \u003e\u003c/script\u003e\n \u003c/body\u003e\n\u003c/html\u003ehttps://github.com/googlemaps/js-samples/blob/2683f7366fb27829401945d2a7e27d77ed2df8e5/dist/samples/webgl-overlay-simple/docs/index.html#L8-L32\n```\n\n### Try Sample\n\n[Google Cloud Shell](https://ssh.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Fgooglemaps%2Fjs-samples&cloudshell_git_branch=sample-webgl-overlay-simple&cloudshell_tutorial=cloud_shell_instructions.md&cloudshell_workspace=.)\n\n### Clone Sample\n\n\nGit and Node.js are required to run this sample locally. Follow these [instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to install Node.js and NPM. The following commands clone, install dependencies and start the sample application. \n\n git clone -b sample-webgl-overlay-simple https://github.com/googlemaps/js-samples.git\n cd js-samples\n npm i\n npm start\n\n\nOther samples can be tried by switching to any branch beginning with `sample-`\u003cvar translate=\"no\"\u003eSAMPLE_NAME\u003c/var\u003e. \n\n git checkout sample-\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nx\"\u003eSAMPLE_NAME\u003c/span\u003e\u003c/var\u003e\n npm i\n npm start"]]
