Three Vue3Three Vue3
指南
在线演示
AI 智能体
  • English
  • 简体中文
GitHub
指南
在线演示
AI 智能体
  • English
  • 简体中文
GitHub
    • 快速开始
    • 场景
    • 参数总线
    • 天空盒
    • 模型加载器

      • 组件加载器
      • 函数加载器
    • 弹出窗口
    • 标注
    • 动态元素
    • 动画
    • 模型旋转器
    • 拾取
    • 相机自适应
    • 网格模型

      • 波动圆
      • 流动线网格
    • 效果

      • 自然

        • 雨
        • 雪
        • 海洋水面
        • 互动水池
        • 沙滩漫步
      • 天空与大气

        • 天空穹顶
        • 高度雾
        • 星云星系
      • 光照

        • 泛光
        • 扫光
        • 灯光渐变
        • 光柱
        • 雷达扫描
        • 信号波
        • 力场护盾
      • 粒子与精灵

        • 烟花
        • 文字烟花
        • 光晕精灵
    • 地理

      • 地理参考系
        • 概念
        • 默认用法
        • Scene 配置项
        • 物体定位
        • GeoReference 方法
        • 基准面工具函数
        • 投影工具函数
      • GeoObject 地理对象
      • GeoJsonLayer 图层
      • 瓦片图层

类型

类 + Scene 配置项

概念

GeoReference 将坐标参考系、大地基准面和轴约定绑定到一个固定的局部原点。转换链路如下:

地理坐标 (lng, lat, alt)
  -> 基准面归一化到 WGS84
  -> 局部切平面(float64 米制)
  -> 围绕局部原点重新中心化
  -> ENU -> three.js 轴映射(东:+X,北:-Z,上:+Y)
  -> THREE.Vector3(float32)

局部原点保证了场景坐标始终很小。Web Mercator 的绝对坐标约为 1.3e7 米,直接使用 three.js 的 float32 坐标在城市场景中会产生明显抖动;重新中心化后,所有物体都位于距 (0, 0, 0) 几公里以内。

每个 Scene 都存在一个 GeoReference。不传入任何 GIS 配置时,它使用以 (0, 0) 为中心的 WGS84/等距圆柱默认值,对普通的非地理场景是完全无副作用的空操作,因此该功能是完全可选的。

默认用法

点击我查看代码
<template>
  <tv-scene
    class="scene"
    bg-color="rgb(40, 42, 54)"
    :origin="ORIGIN"
    :grid-helper="GRID"
    @created="created"
  />
</template>

<script lang="ts" setup>
import { onBeforeUnmount } from 'vue'
import * as THREE from 'three'
import type { GeoPoint } from 'three-vue3'

// 北京天安门(WGS84)。
const ORIGIN: GeoPoint = { lng: 116.397, lat: 39.909 }
const GRID = { size: 1200, divisions: 24, colorCenterLine: 0x4a6fa5, colorGrid: 0x2f3e5c }

const PLACES: { point: GeoPoint; color: number }[] = [
  { point: ORIGIN, color: 0xffd166 },
  { point: { lng: 116.4005, lat: 39.909 }, color: 0x4fc3f7 },
  { point: { lng: 116.397, lat: 39.9117 }, color: 0x81c784 },
  { point: { lng: 116.3935, lat: 39.9063 }, color: 0xe57373 }
]

const objects: THREE.Mesh<THREE.SphereGeometry, THREE.MeshBasicMaterial>[] = []
let disposed = false

const created = (scene: THREE.Scene, { camera }: { camera: THREE.Camera }) => {
  if (disposed) return

  scene.setPosition(camera, { x: 0, y: 500, z: 700 })
  camera.lookAt(0, 0, 0)

  PLACES.forEach(({ point, color }) => {
    const radius = 35
    const geometry = new THREE.SphereGeometry(radius, 24, 16)
    const material = new THREE.MeshBasicMaterial({ color })
    const marker = new THREE.Mesh(geometry, material)
    scene.setPosition(marker, point)
    marker.position.y = radius
    scene.add(marker)
    objects.push(marker)
  })
}

onBeforeUnmount(() => {
  disposed = true
  objects.forEach((object) => {
    object.removeFromParent()
    object.geometry.dispose()
    object.material.dispose()
  })
  objects.length = 0
})
</script>

<style>
.scene {
  margin-top: 10px;
  margin-bottom: 16px;
  width: 100%;
  height: 300px;
}
</style>

Scene 配置项

属性类型默认值描述
originGeoPoint{ lng: 0, lat: 0, alt: 0 }局部切平面原点,所有场景坐标都相对于它
crs'EPSG:4326' | 'EPSG:3857''EPSG:4326'平面模型:等距圆柱切平面或重新中心化的 Web Mercator
datum'WGS84' | 'GCJ02' | 'BD09''WGS84'传入场景的坐标所使用的基准面
axesAxesMapping{ east: 'x', north: '-z', up: 'y' }将 ENU 基映射到带符号的 three.js 轴
geoGeoReference—直接传入预先构建的参考系,替代 origin/crs/datum/axes

Scene 构建出的参考系可在 created 回调中通过 components.geo 获取,也可通过 useScene().geo 获取。它同时会绑定到 scene 自身,因此大多数代码完全不需要显式提到 geo。

物体定位

每个 Scene 都会把自己的 GeoReference 绑定到 scene 实例上,并安装一个统一的定位方法 scene.setPosition(object, position, datum?)。由于 scene 已经持有参考系,定位时只需给出坐标本身,无需再把参考系传来传去;mesh、group 和 camera 都是 THREE.Object3D,所以同一个调用写法可以定位任意对象。

position 接受所有常用形态(ScenePosition):

坐标形态含义
{ lng, lat, alt? }地理点,经 scene 参考系投影
[lng, lat]地理点元组,高度默认 0
[lng, lat, alt]地理点元组
THREE.Vector3局部米坐标,原样使用、不投影
{ x, y, z? }局部米坐标对象,z 默认 0
const created = (scene) => {
  // 下面四种都是地理坐标,统一经由 scene 自身的参考系投影。
  scene.setPosition(mesh, { lng: 116.397, lat: 39.909 })
  scene.setPosition(mesh, { lng: 116.397, lat: 39.909, alt: 35 })
  scene.setPosition(mesh, [116.397, 39.909])
  scene.setPosition(mesh, [116.397, 39.909, 35])

  // GCJ02/BD09 输入可按次传入 datum 覆盖场景的 datum。
  scene.setPosition(mesh, [116.403, 39.915], 'GCJ02')

  // 相机与 mesh 使用完全相同的调用。
  scene.setPosition(camera, [116.397428, 39.90923, 120])

  // 局部米坐标原样使用,不做投影。
  scene.setPosition(helper, new THREE.Vector3(10, 0, -5))
  scene.setPosition(helper, { x: 10, y: 0, z: -5 })
}

方法会返回传入的对象,支持链式调用。自行 new THREE.Scene() 创建的场景没有该方法;可调用一次 bindSceneGeo(scene, geo) 安装,或通过 getSceneGeo(scene) 读取参考系。如果场景已安装方法但没有绑定参考系,地理元组/对象会回退为本地坐标,把 lng/lat/alt 直接写到 x/y/z,因此该调用在任何场景下都是安全的。

辅助函数签名描述
scene.setPosition(object: Object3D, position: ScenePosition, datum?: DatumType) => Object3D定位任意对象;地理输入自动投影,局部米坐标原样使用
scene.getGeo() => GeoReference | undefined读取绑定在 scene 上的参考系
bindSceneGeo(scene: Scene, geo?: GeoReference) => Scene在 scene 上安装定位方法,并可选绑定参考系
getSceneGeo(scene: Scene) => GeoReference | undefinedscene.getGeo() 的函数形式
ensureSceneGeo(scene: Scene) => Scene为缺少定位方法的 scene 补装该方法

GeoReference 方法

名称参数描述
constructor(origin?: GeoPoint, options?: GeoReferenceOptions) => GeoReference构建参考系及其切平面
toLocal(p: GeoPoint, datum?: DatumType, target?: Vector3) => Vector3地理坐标 -> 局部米制坐标
toGeo(v: Vector3, datum?: DatumType, target?: GeoPoint) => GeoPoint局部米制坐标 -> 地理坐标
setPosition(object: Object3D, p: GeoPoint, datum?: DatumType) => Object3D将已有物体放置到指定地理位置
distance(a: GeoPoint, b: GeoPoint, datum?: DatumType) => number平面距离(米)
import { GeoReference } from 'three-vue3'
import type { GeoPoint } from 'three-vue3'

const origin: GeoPoint = { lng: 116.397, lat: 39.909 }
const geo = new GeoReference(origin, { crs: 'EPSG:4326', datum: 'WGS84' })

// 相对于原点的局部米制坐标(内部使用 float64 计算)。
const local = geo.toLocal({ lng: 116.4005, lat: 39.909 })

// 反向转换;混合多种数据源时可按次传入 datum。
const back = geo.toGeo(local)

// GCJ02(高德/腾讯)输入会被自动归一化。
const fromMars = geo.toLocal({ lng: 116.403, lat: 39.915 }, 'GCJ02')

基准面工具函数

国内地图服务使用加密基准面;若不转换就与原始 GPS(WGS84)数据混用,在中国境内会产生 50–600 米的偏移。

函数签名描述
toWGS84(p: GeoPoint, from: DatumType) => GeoPoint将 GCJ02/BD09 转为 WGS84
fromWGS84(p: GeoPoint, to: DatumType) => GeoPoint将 WGS84 转为 GCJ02/BD09
convertDatum(p: GeoPoint, from: DatumType, to: DatumType) => GeoPoint任意基准面之间互转
wgs84ToGcj02 / gcj02ToWgs84(p: GeoPoint) => GeoPointWGS84 与 GCJ02 直接互转
gcj02ToBd09 / bd09ToGcj02(p: GeoPoint) => GeoPointGCJ02 与 BD09 直接互转

GCJ02 -> WGS84 的反解采用定点迭代;BD09 闭式反解存在几厘米的固有残差。

投影工具函数

函数描述
mercatorProject(p)EPSG:4326 经纬度 -> EPSG:3857 Web Mercator 米
mercatorUnproject(v)EPSG:3857 米 -> EPSG:4326 经纬度
createLocalPlane(code, origin)为任一 CRS 构建重新中心化的 LocalPlane
在 GitHub 上编辑此页
Last Updated:
Contributors: Shing Rui, ruixinglong
Next
GeoObject 地理对象