@terra.gl/core 0.0.1-alpha.6 → 0.0.1-alpha.62

package/dist/README_CN.md

@@ -0,0 +1,201 @@
+# Terra-GL Core
+
+<div align="center">
+
+**基于 Three.js 的高性能 WebGL 三维地图引擎 🌍**
+
+[![npm version](https://img.shields.io/npm/v/@terra.gl/core.svg)](https://www.npmjs.com/package/@terra.gl/core)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+[English](./README.md) | 简体中文
+
+</div>
+
+---
+
+## 📖 简介
+
+Terra-GL Core 是一个基于 Three.js 构建的现代化 WebGL 三维地图引擎核心库。它提供了完整的 GIS 可视化能力，支持瓦片地图加载、矢量要素渲染、三维模型展示等丰富功能,适用于构建智慧城市、数字孪生、地理信息系统等应用场景。
+
+### ✨ 核心特性
+
+- 🚀 **高性能渲染** - 基于 Three.js WebGL 引擎，支持大规模数据可视化
+- 🗺️ **多源瓦片支持** - 兼容 WMTS、ArcGIS、MapBox、天地图等主流瓦片服务
+- 📐 **丰富的要素类型** - 支持点、线、面、标注、模型等多种地理要素
+- 🎨 **灵活的样式系统** - 支持动态样式配置与主题切换
+- 🎯 **完善的事件系统** - 提供地图交互、要素事件等丰富的事件机制
+- 🛠️ **强大的绘制工具** - 内置绘制工具，支持点线面等要素的交互式绘制
+- 🌈 **三维效果增强** - 支持天空盒、阴影、HDR、云层等视觉效果
+- 📱 **UI 组件系统** - 提供信息窗口、工具提示等常用 UI 组件
+- 🔧 **碰撞检测避让** - 智能标注避让，优化密集要素显示效果
+- 📦 **模块化设计** - 清晰的代码结构，易于扩展和维护
+
+---
+
+## 🌟 为什么选择 Terra-GL
+
+### 💪 技术优势
+
+**1. 原生 Three.js 架构**
+- 完全基于 Three.js 构建，无额外渲染层抽象
+- 直接访问 Three.js 场景对象，可自由扩展
+- 充分利用 WebGL 的性能优势
+- 与 Three.js 生态无缝集成
+
+**2. 专业的 GIS 能力**
+- 支持多种坐标系统和投影变换（Web Mercator、WGS84 等）
+- 完整的瓦片地图系统，支持海量数据加载
+- 兼容主流地图服务（WMTS、ArcGIS、MapBox、天地图）
+- 矢量瓦片（MVT）渲染支持
+
+**3. 丰富的可视化能力**
+- 二维矢量要素（点、线、面）与三维模型统一管理
+- 支持 GLTF/GLB 模型加载，带 Draco 压缩
+- 实时阴影、HDR 环境光、后期处理效果
+- 粒子云层、水面波纹等特效支持
+
+**4. 灵活的交互体验**
+- 完善的事件系统（地图事件、要素事件）
+- 内置绘制工具，支持点线面圆等图形绘制
+- 智能碰撞检测与标注避让
+- 信息窗口、工具提示等 UI 组件
+
+**5. 开发友好**
+- TypeScript 编写，完整类型定义
+- 清晰的模块化设计，易于理解和扩展
+- 丰富的示例和文档
+- 支持 ES Module 和 UMD 两种模块格式
+
+### 💡 适用场景
+
+| 场景类型 | 典型应用 | 核心能力 |
+|---------|---------|----------|
+| **🏙️ 智慧城市** | 城市三维建模、BIM 展示、规划方案对比 | 大规模模型渲染、LOD 控制、图层管理 |
+| **🔮 数字孪生** | 工业园区、智慧楼宇、设备监控 | 实时数据绑定、动态更新、状态可视化 |
+| **🗺️ 地理信息** | 地形分析、资源分布、管线管理 | 坐标转换、空间查询、缓冲区分析 |
+| **🚨 应急指挥** | 态势展示、资源调度、路径规划 | 实时轨迹、热力图、动态标绘 |
+
+### ⚡ 性能特点
+
+- **瓦片按需加载** - 根据视野范围动态加载瓦片，支持数万平方公里数据
+- **LOD 层级控制** - 自动根据距离切换模型细节，优化渲染性能
+- **四叉树空间索引** - 快速查询可见要素，提升交互响应速度
+- **WebGL 实例化渲染** - 批量绘制相同几何体，降低 Draw Call
+- **碰撞避让优化** - 智能隐藏重叠标注，保持界面整洁
+
+---
+## 📚 核心模块概述
+
+### 🏗️ 核心架构
+- **🗺️ Map** - 地图容器，统一管理图层、视图、事件
+- **👁️ Viewer** - 基于Three.js的渲染引擎，管理场景、相机、光照
+- **📚 Layer System** - 分层管理瓦片、矢量、模型等数据
+- **📍 Feature** - 点、线、面、模型等地理要素的抽象
+- **🔲 TileSystem** - 支持WMTS、ArcGIS等多源瓦片的动态加载系统
+
+### 🔑 关键特性
+- **⚡ 事件系统** - 完整的地图/要素级事件机制
+- **✏️ 绘制工具** - 内置交互式绘制（点、线、面、圆等）
+- **🎨 UI组件** - InfoWindow、ToolTip等常用组件
+- **🎯 碰撞检测** - 智能标注避让，优化密集场景显示
+- **🎭 样式系统** - 统一的矢量/模型样式配置
+
+[查看详细API文档 →](链接到详细文档)
+
+---
+
+## 🚀 快速开始
+
+### 📦 安装
+
+```bash
+npm install @terra.gl/core three@^0.171.0
+```
+
+### ⚡ 5 分钟上手
+
+```javascript
+import * as terra from '@terra.gl/core';
+
+// 创建地图
+const map = new terra.Map('#map', {
+    center: [116.397428, 39.90923, 1000],  // [经度, 纬度, 相机高度]
+    basemap: {
+        Baselayers: [
+            new terra.WMTSTileLayer('base', {
+                source: new terra.WMTSSource({
+                    urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'
+                }),
+                projection: terra.ProjectFactory.createFromID('3857', 0)
+            })
+        ],
+        minLevel: 1,
+        maxLevel: 18
+    }
+});
+
+// 添加标注
+const label = new terra.Label({
+    geometry: { type: 'Point', coordinates: [116.397428, 39.90923, 0] },
+    style: { text: '北京天安门', fontSize: 16, fontColor: '#ffffff' }
+});
+
+const pointLayer = new terra.PointLayer('points');
+map.addLayer(pointLayer);
+label.addTo(pointLayer);
+```
+
+查看 `example/` 目录获取更多示例。
+
+---
+
+## 🔧 开发
+
+### 🔨 构建
+
+```bash
+# 开发模式（监听文件变化）
+npm run dev
+
+# 生产构建
+npm run build
+
+# 生成 API 文档
+npm run doc
+```
+
+### 📂 项目结构
+
+```
+packages/core/
+├── src/                # 源代码
+├── dist/               # 编译输出
+├── docs/               # API 文档
+├── assets/             # 资源文件
+├── package.json        # 包配置
+├── tsconfig.json       # TypeScript 配置
+├── vite.config.ts      # Vite 构建配置
+└── typedoc.json        # 文档生成配置
+```
+---
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+---
+
+## 🔗 相关链接
+
+- [Three.js 官网](https://threejs.org/)
+- [GeoJSON 规范](https://geojson.org/)
+- [WMTS 标准](https://www.ogc.org/standards/wmts)
+<!-- - [three-tile 官网](https://sxguojf.github.io/three-tile-doc/1.introduce/01.whatIs/) -->
+
+---
+
+<div align="center">
+
+**如果这个项目对你有帮助，请给一个 ⭐️ Star 支持一下！**
+
+</div>

package/dist/assets/terra.css

@@ -0,0 +1,501 @@
+/* 毛玻璃核心样式 - 确保在支持的环境中生效 */
+.terra-infowindow,
+.terra-tooltip {
+  background: rgba(255, 255, 255, 0.8);
+  /* 关键：毛玻璃效果 */
+  backdrop-filter: blur(20px) saturate(180%);
+  -webkit-backdrop-filter: blur(20px) saturate(180%);
+  /* Safari 兼容性处理 */
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  box-shadow:
+    0 8px 32px rgba(0, 0, 0, 0.1),
+    inset 0 1px 0 rgba(255, 255, 255, 0.5);
+  animation: none;
+}
+
+/* 如果 backdrop-filter 不被支持，使用纯色背景作为回退 */
+@supports not (backdrop-filter: blur(20px)) {
+
+  .terra-infowindow,
+  .terra-tooltip {
+    background: rgba(255, 255, 255, 0.95);
+  }
+}
+
+/* ==================== InfoWindow 主容器 ==================== */
+.terra-infowindow {
+  border-radius: 14px;
+  box-sizing: border-box;
+  min-width: 200px;
+  position: absolute;
+  /* 重要：使用 visible 而不是 hidden，让三角指针可以显示 */
+  overflow: visible;
+  /* 增强的毛玻璃层叠效果 */
+  background: linear-gradient(135deg,
+      rgba(255, 255, 255, 0.9) 0%,
+      rgba(255, 255, 255, 0.7) 100%);
+  /* 内部发光边缘 */
+  box-shadow:
+    0 10px 40px rgba(0, 0, 0, 0.12),
+    0 0 0 0.5px rgba(255, 255, 255, 0.3) inset;
+  /* 设置 z-index 确保三角在正确层级 */
+  z-index: 1000;
+  /* 强制关掉任何来源的动画/过渡 */
+  animation: none !important;
+  transition: none !important;
+}
+
+/* 内部容器 - 用于保持圆角裁剪 */
+.terra-infowindow-inner {
+  border-radius: 14px;
+  overflow: hidden;
+  height: 100%;
+  position: relative;
+  z-index: 2;
+  background: inherit;
+  backdrop-filter: inherit;
+  -webkit-backdrop-filter: inherit;
+}
+
+/* ==================== 底部三角指针 ==================== */
+/* 外层阴影三角 */
+.terra-infowindow::before {
+  content: "";
+  position: absolute;
+  bottom: -10px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 0;
+  height: 0;
+  z-index: 1;
+  border-left: 9px solid transparent;
+  border-right: 9px solid transparent;
+  border-top: 10px solid rgba(255, 255, 255, 0.3);
+  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
+  pointer-events: none;
+}
+
+/* 内层毛玻璃三角 */
+.terra-infowindow::after {
+  content: "";
+  position: absolute;
+  bottom: -9px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 0;
+  height: 0;
+  z-index: 2;
+  border-left: 8px solid transparent;
+  border-right: 8px solid transparent;
+  border-top: 9px solid rgba(255, 255, 255, 0.8);
+  /* 继承毛玻璃效果 */
+  /* backdrop-filter: blur(20px) saturate(180%);
+  -webkit-backdrop-filter: blur(20px) saturate(180%); */
+  pointer-events: none;
+}
+
+/* 为不同位置的三角提供样式（如果需要的话） */
+/* 顶部三角 */
+.terra-infowindow.terra-arrow-top::before {
+  top: -10px;
+  bottom: auto;
+  border-top: none;
+  border-bottom: 10px solid rgba(255, 255, 255, 0.3);
+}
+
+.terra-infowindow.terra-arrow-top::after {
+  top: -9px;
+  bottom: auto;
+  border-top: none;
+  border-bottom: 9px solid rgba(255, 255, 255, 0.8);
+}
+
+/* 左侧三角 */
+.terra-infowindow.terra-arrow-left::before {
+  left: -10px;
+  top: 50%;
+  bottom: auto;
+  transform: translateY(-50%);
+  border-top: 9px solid transparent;
+  border-bottom: 9px solid transparent;
+  border-right: 10px solid rgba(255, 255, 255, 0.3);
+  border-left: none;
+}
+
+.terra-infowindow.terra-arrow-left::after {
+  left: -9px;
+  top: 50%;
+  bottom: auto;
+  transform: translateY(-50%);
+  border-top: 8px solid transparent;
+  border-bottom: 8px solid transparent;
+  border-right: 9px solid rgba(255, 255, 255, 0.8);
+  border-left: none;
+}
+
+/* 右侧三角 */
+.terra-infowindow.terra-arrow-right::before {
+  right: -10px;
+  left: auto;
+  top: 50%;
+  bottom: auto;
+  transform: translateY(-50%);
+  border-top: 9px solid transparent;
+  border-bottom: 9px solid transparent;
+  border-left: 10px solid rgba(255, 255, 255, 0.3);
+  border-right: none;
+}
+
+.terra-infowindow.terra-arrow-right::after {
+  right: -9px;
+  left: auto;
+  top: 50%;
+  bottom: auto;
+  transform: translateY(-50%);
+  border-top: 8px solid transparent;
+  border-bottom: 8px solid transparent;
+  border-left: 9px solid rgba(255, 255, 255, 0.8);
+  border-right: none;
+}
+
+/* ==================== 头部区域 ==================== */
+.terra-infowindow-header {
+  display: flex;
+  align-items: center;
+  padding: 0 18px;
+  height: 48px;
+  line-height: 48px;
+  font-size: 16px;
+  font-weight: 600;
+  white-space: nowrap;
+  padding-right: 50px;
+  position: relative;
+  color: #1d1d1f;
+  letter-spacing: -0.2px;
+  border-radius: 14px 14px 0 0;
+  /* 头部更明显的毛玻璃效果 */
+  background: rgba(255, 255, 255, 0.5);
+  backdrop-filter: blur(30px) saturate(200%);
+  -webkit-backdrop-filter: blur(30px) saturate(200%);
+  /* 底部细分割线 */
+  border-bottom: 0.5px solid rgba(0, 0, 0, 0.1);
+  box-shadow: inset 0 -0.5px 0 rgba(255, 255, 255, 0.6);
+}
+
+/* 标题文本 */
+.terra-infowindow-title {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  text-shadow: 0 1px 1px rgba(255, 255, 255, 0.8);
+  font-weight: 600;
+}
+
+/* 关闭按钮 - 圆形毛玻璃按钮 */
+.terra-infowindow-close {
+  position: absolute;
+  top: 50%;
+  right: 10px;
+  transform: translateY(-50%);
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  margin: 0;
+  font-size: 22px;
+  line-height: 24px;
+  text-align: center;
+  color: #666666;
+  cursor: pointer;
+  /* transition: all 0.2s ease; */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 10;
+}
+
+
+
+
+
+/* ==================== 内容区域 ==================== */
+.terra-infowindow-content {
+  font-size: 14px;
+  padding: 18px;
+  min-width: 200px;
+  color: #1d1d1f;
+  line-height: 1.5;
+  background: transparent;
+  border-radius: 0 0 14px 14px;
+  /* 内容区域也有轻微毛玻璃效果 */
+  backdrop-filter: blur(5px);
+  -webkit-backdrop-filter: blur(5px);
+}
+
+/* 内容区域内的链接 */
+.terra-infowindow-content a {
+  color: #0066cc;
+  text-decoration: none;
+  border-bottom: 1px solid rgba(0, 102, 204, 0.2);
+  /* transition: all 0.2s ease; */
+}
+
+.terra-infowindow-content a:hover {
+  color: #0052a3;
+  border-bottom-color: #0052a3;
+}
+
+/* ==================== 工具提示 ==================== */
+.terra-tooltip {
+  display: block;
+  /* 强化的毛玻璃效果 */
+  background: rgba(255, 255, 255, 0.85);
+  backdrop-filter: blur(25px) saturate(180%);
+  -webkit-backdrop-filter: blur(25px) saturate(180%);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 10px;
+  padding: 0 16px;
+  height: 36px;
+  line-height: 36px;
+  font-size: 14px;
+  white-space: nowrap;
+  color: #1d1d1f;
+  /* 多层阴影增强立体感 */
+  box-shadow:
+    0 6px 30px rgba(0, 0, 0, 0.1),
+    0 0 0 0.5px rgba(255, 255, 255, 0.4) inset;
+  font-weight: 500;
+  letter-spacing: -0.1px;
+  /* 文字阴影让文字在毛玻璃上更清晰 */
+  text-shadow: 0 1px 2px rgba(255, 255, 255, 0.8);
+  z-index: 999;
+  position: relative;
+  overflow: visible;
+}
+
+/* ==================== 深色模式 ==================== */
+@media (prefers-color-scheme: dark) {
+
+  .terra-infowindow,
+  .terra-tooltip {
+    background: rgba(28, 28, 30, 0.8);
+    backdrop-filter: blur(30px) saturate(180%);
+    -webkit-backdrop-filter: blur(30px) saturate(180%);
+    border: 1px solid rgba(255, 255, 255, 0.1);
+    color: #ffffff;
+    box-shadow:
+      0 8px 32px rgba(0, 0, 0, 0.3),
+      inset 0 1px 0 rgba(255, 255, 255, 0.1);
+  }
+
+  /* InfoWindow 三角 */
+  .terra-infowindow::before {
+    border-top-color: rgba(255, 255, 255, 0.15);
+  }
+
+  .terra-infowindow::after {
+    border-top-color: rgba(28, 28, 30, 0.8);
+  }
+
+  /* 顶部三角深色模式 */
+  .terra-infowindow.terra-arrow-top::before {
+    border-bottom-color: rgba(255, 255, 255, 0.15);
+  }
+
+  .terra-infowindow.terra-arrow-top::after {
+    border-bottom-color: rgba(28, 28, 30, 0.8);
+  }
+
+  /* 左侧三角深色模式 */
+  .terra-infowindow.terra-arrow-left::before {
+    border-right-color: rgba(255, 255, 255, 0.15);
+  }
+
+  .terra-infowindow.terra-arrow-left::after {
+    border-right-color: rgba(28, 28, 30, 0.8);
+  }
+
+  /* 右侧三角深色模式 */
+  .terra-infowindow.terra-arrow-right::before {
+    border-left-color: rgba(255, 255, 255, 0.15);
+  }
+
+  .terra-infowindow.terra-arrow-right::after {
+    border-left-color: rgba(28, 28, 30, 0.8);
+  }
+
+  /* 头部区域 */
+  .terra-infowindow-header {
+    background: rgba(44, 44, 46, 0.7);
+    color: rgba(255, 255, 255, 0.95);
+    border-bottom: 0.5px solid rgba(255, 255, 255, 0.1);
+    box-shadow: inset 0 -0.5px 0 rgba(255, 255, 255, 0.1);
+  }
+
+  .terra-infowindow-title {
+    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.5);
+  }
+
+  /* 关闭按钮 */
+  .terra-infowindow-close {
+    background: rgba(118, 118, 128, 0.3);
+    border: 0.5px solid rgba(255, 255, 255, 0.1);
+    color: rgba(235, 235, 245, 0.6);
+  }
+
+  .terra-infowindow-close:hover {
+    background: rgba(118, 118, 128, 0.4);
+    color: rgba(235, 235, 245, 0.9);
+  }
+
+  /* 内容区域 */
+  .terra-infowindow-content {
+    color: rgba(235, 235, 245, 0.9);
+  }
+
+  .terra-infowindow-content a {
+    color: #5fa9ff;
+    border-bottom-color: rgba(95, 169, 255, 0.3);
+  }
+
+  .terra-infowindow-content a:hover {
+    color: #8bc1ff;
+    border-bottom-color: #8bc1ff;
+  }
+
+  /* 工具提示 */
+  .terra-tooltip {
+    background: rgba(28, 28, 30, 0.85);
+    border: 1px solid rgba(255, 255, 255, 0.15);
+    color: rgba(255, 255, 255, 0.95);
+    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.5);
+  }
+
+  /* 工具提示三角深色模式 */
+  .terra-tooltip::before {
+    border-top-color: rgba(255, 255, 255, 0.15);
+  }
+
+  .terra-tooltip::after {
+    border-top-color: rgba(28, 28, 30, 0.85);
+  }
+}
+
+/* ==================== 鼠标悬停增强效果 ==================== */
+.terra-infowindow:hover {
+  box-shadow:
+    0 12px 48px rgba(0, 0, 0, 0.15),
+    0 0 0 0.5px rgba(255, 255, 255, 0.4) inset;
+  transform: translateY(-1px);
+  /* transition: all 0.3s ease; */
+}
+
+/* 工具提示悬停效果 */
+.terra-tooltip:hover {
+  box-shadow:
+    0 8px 40px rgba(0, 0, 0, 0.15),
+    0 0 0 0.5px rgba(255, 255, 255, 0.5) inset;
+  transform: translateY(-1px);
+  /* transition: all 0.3s ease; */
+}
+
+/* ==================== 动画效果 ==================== */
+/* @keyframes terra-fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(10px) scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+.terra-infowindow,
+.terra-tooltip {
+  animation: terra-fade-in 0.3s ease-out;
+} */
+
+/* ==================== 响应式设计 ==================== */
+@media (max-width: 768px) {
+  .terra-infowindow {
+    min-width: 180px;
+    max-width: 280px;
+  }
+
+  .terra-infowindow-header {
+    height: 44px;
+    line-height: 44px;
+    font-size: 15px;
+    padding: 0 16px;
+    padding-right: 44px;
+  }
+
+  .terra-infowindow-content {
+    padding: 16px;
+    font-size: 13px;
+  }
+
+  .terra-tooltip {
+    font-size: 13px;
+    height: 32px;
+    line-height: 32px;
+    padding: 0 14px;
+  }
+}
+
+/* 打印样式 */
+@media print {
+
+  .terra-infowindow,
+  .terra-tooltip {
+    background: white;
+    border: 1px solid #ddd;
+    box-shadow: none;
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+  }
+
+  .terra-infowindow::before,
+  .terra-infowindow::after,
+  .terra-tooltip::before,
+  .terra-tooltip::after {
+    display: none;
+  }
+}
+
+
+/* 使用纯色箭头替代毛玻璃箭头 */
+.terra-infowindow::before {
+  content: "";
+  position: absolute;
+  bottom: -10px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 0;
+  height: 0;
+  border-left: 10px solid transparent;
+  border-right: 10px solid transparent;
+  border-top: 10px solid rgba(255, 255, 255, 0.9);
+  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
+  z-index: 1;
+  /* 这里原来有毛玻璃，会导致出现一个矩形模糊块 */
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+  pointer-events: none;
+}
+
+.terra-infowindow::after {
+  content: "";
+  position: absolute;
+  bottom: -11px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 0;
+  height: 0;
+  border-left: 11px solid transparent;
+  border-right: 11px solid transparent;
+  /* 保持完全透明，只起占位，不再画底色 */
+  border-top: 11px solid transparent;
+  z-index: 0;
+  pointer-events: none;
+}