@googlemaps/three

中文文档
4.0.13发布于 2024/04/27Apache-2.0TypeScriptESM + CJS零依赖近 30 天下载 4万
中文使用文档
文档目录7 节
  1. 说明
  2. 安装
  3. 文档
  4. 坐标、投影和锁定点
  5. 广播和互动
  6. 示例
  7. 演示文稿

谷歌地图 三JS 重叠视图和公用事业

npm Build Release codecov GitHub contributors semantic-release Discord

说明

添加 3个j google地图平台JS的天体。 这个 图书馆提供 a ThreeJSOverlayView 扩展类 google.maps.WebGLOverlayView 和将地理坐标(纬度/经度)转换为 3.js使用的坐标系统中的矢量.

安装

通过 npm 作为软件包可用 @googlemaps/ 三页。 。 。 .

npm i @googlemaps/three

或者您可以使用 : unpkg 或其他 CDN 类。 在这种情况下,在装入前确保装入3.js 此库 :

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

在通过 unpkg 添加时,该软件包可按 google.maps.plugins.three。可以通过使用 https://unpkg.com/@googlemaps/three@VERSION/dist/...。 。 。 .

第三个选择是通过ES-Module的进口,类似于 三.j. 实例有效。 为此,您首先需要指定 导入图 (例如使用unpkg.com,但它与任何其他CDN一样有效) 或自寄文件 :

<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three/build/three.module.js",
      "@googlemaps/three": "https://unpkg.com/@googlemaps/three/dist/index.esm.js"
    }
  }
</script>

为了支持尚未执行导入图的浏览器,您可以 使用该 s-moule-shims 软件包。 。 。 .

之后,你可以使用 三.js 和 三JS OverlayView 像你什么时候会 使用捆绑机.

<script type="module">
  import * as THREE from "three";
  import { ThreeJSOverlayView } from "@googlemaps/three";

  // ...
</script>

文档

检查引用 文档。 。 。 .

坐标、投影和锁定点

三.js场景中的坐标系统(所谓的"世界") 坐标')是z-up方向的一个右手坐标系统. Y轴正指正向北,x轴正指正向东. 这个 单位为米. 所以重点 new Vector3(0, 50, 10) 为 10 公尺 在地面上,在指定锚地以东50米处.

这个锚点和取向可以在构造器中设定,或者通过使用 setAnchor() 财务报告和审定财务报表 setUpAxis()-方法(注意所有物体位置在 您的场景取决于锚点和方向, 所以他们必须是 当其中任何一个被修改时重算:

import { ThreeJSOverlayView } from "@googlemaps/three";

const overlay = new ThreeJSOverlayView({
  anchor: { lat: 37.7793, lng: -122.4192, altitude: 0 },
  upAxis: "Y",
});

overlay.setAnchor({ lat: 35.680432, lng: 139.769013, altitude: 0 });
overlay.setUpAxis("Z");
// can also be specified as Vector3:
overlay.setUpAxis(new Vector3(0, 0, 1));

本库使用的默认上轴为z轴(+x为东) +y为北),这与通常的y-up方向不同 以三为用.

GPU上所有与位置相关的计算都使用浮点32数字, 将可能的精确度限制在小数点后七点左右。 因为 我们无法使用全球参考系统 精确显示米至厘米范围内的细节.

锚点在这里很重要。 锚指定 地球空间起源地地理坐标(纬度/升/海平面) 坐标系统是,你总是应该定义它接近 物体被放置在现场 - 当然,除非您只与 在全球分布的大型(城市大小)物体.

将锚放近现场物体的另一个原因 一般来说,这是一个好主意: 在谷歌地图中使用的商机地图投影中, 测量表的缩放只有在靠近赤道的区域才准确。 这个 可以通过适用一个取决于 锚的纬度。 这个比例系数计入坐标 在WebGlOverlayView中根据锚的纬度进行计算.

转换坐标

当你需要的不仅仅是你场景中的 单一地理参照物时, 您需要计算这些坐标的世界空间位置。 这个 ThreeJSOverlayView 类为此转换提供了辅助函数 取当前 anchor 财务报告和审定财务报表 upAxis 考虑到:

const coordinates = { lat: 12.34, lng: 56.78 };
const position: Vector3 = overlay.latLngAltitudeToVector3(coordinates);

// alternative: pass the Vector3 to write the position
// to as the second parameter, so to set the position of a mesh:
overlay.latLngAltitudeToVector3(coordinates, mesh.position);

广播和互动

如果您想要在任何 3.j 内容中添加交互性, 通常您会 必须实施线播音。 我们帮你搞定了 ThreeJS OverlayView 提供了一个方法 overlay.raycast() 为了这个 来做 使用它,您首先必须跟踪地图上的鼠标移动情况 :

import { Vector2 } from "three";

// ...

const mapDiv = map.getDiv();
const mousePosition = new Vector2();

map.addListener("mousemove", (ev) => {
  const { domEvent } = ev;
  const { left, top, width, height } = mapDiv.getBoundingClientRect();

  const x = domEvent.clientX - left;
  const y = domEvent.clientY - top;

  mousePosition.x = 2 * (x / width) - 1;
  mousePosition.y = 1 - 2 * (y / height);

  // since the actual raycasting is performed when the next frame is
  // rendered, we have to make sure that it will be called for the next frame.
  overlay.requestRedraw();
});

随着鼠标位置一直更新,您可以使用 raycast() 函数 onBeforeDraw 调用. 在这个例子中,我们更改光标下对象的颜色:

const DEFAULT_COLOR = 0xffffff;
const HIGHLIGHT_COLOR = 0xff0000;

let highlightedObject = null;

overlay.onBeforeDraw = () => {
  const intersections = overlay.raycast(mousePosition);
  if (highlightedObject) {
    highlightedObject.material.color.setHex(DEFAULT_COLOR);
  }

  if (intersections.length === 0) return;

  highlightedObject = intersections[0].object;
  highlightedObject.material.color.setHex(HIGHLIGHT_COLOR);
};

完整的例子可见于 ./examples/raycasting.ts。 。 。 .

示例

下面的例子提供了一个骨架,用来用这个库将对象添加到地图上.

import * as THREE from "three";
import { ThreeJSOverlayView, latLngToVector3 } from "@googlemaps/three";

// when loading via UMD, remove the imports and use this instead:
// const { ThreeJSOverlayView, latLngToVector3 } = google.maps.plugins.three;

const map = new google.maps.Map(document.getElementById("map"), mapOptions);
const overlay = new ThreeJSOverlayView({
  map,
  upAxis: "Y",
  anchor: mapOptions.center,
});

// create a box mesh
const box = new THREE.Mesh(
  new THREE.BoxGeometry(10, 50, 10),
  new THREE.MeshMatcapMaterial()
);
// move the box up so the origin of the box is at the bottom
box.geometry.translateY(25);

// set position at center of map
box.position.copy(overlay.latLngAltitudeToVector3(mapOptions.center));

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

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

  requestAnimationFrame(animate);
};

// start animation loop
requestAnimationFrame(animate);

这在地图上增加了一个框.

threejs box on map

演示文稿

在操作中查看软件包 :

版本与发布记录

@googlemaps/three 共发布 53 个版本,首次发布于 2021/06/03;过去 12 个月发布了 0 个版本。

版本发布日期距今
4.0.13latest2024/04/272 年前
4.0.122024/04/272 年前
4.0.112024/04/152 年前
4.0.102024/03/112 年前
4.0.92024/01/292 年前
4.0.82023/12/252 年前

其他发布通道:beta → 1.0.0-beta.3。

关于 @googlemaps/three 的常见问题

@googlemaps/three 是什么?

[释 (出https://github.com/googlemaps/js-3/workflows/Release/badge.s. 互联网档案馆的存檔,存档日期2013-12-22

如何安装 @googlemaps/three?

在项目目录运行 npm install @googlemaps/three,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:three(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@googlemaps/three 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@googlemaps/three 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@googlemaps/three 可以商用吗?

@googlemaps/three 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@googlemaps/three 的下载量有多少?

根据 npm 官方下载统计,@googlemaps/three 在 2026/10/17 – 2026/11/15 这 30 天内被下载 39,951 次,日均约 1,332 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@googlemaps/three 还在维护吗?

最新版本 4.0.13 发布于 2024/04/27(2 年前);至今共发布 53 个版本,其中过去 12 个月发布了 0 个;首次发布于 2021/06/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。