@terra.gl/core 0.0.1-alpha.46 → 0.0.1-alpha.47

package/dist/README.md

@@ -0,0 +1,200 @@
+# Terra-GL Core
+
+<div align="center">
+
+**High-Performance WebGL 3D Map Engine Based on Three.js 🌍**
+
+[![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_CN.md)
+
+</div>
+
+---
+
+## 📖 Introduction
+
+Terra-GL Core is a modern WebGL 3D map engine built on Three.js. It provides complete GIS visualization capabilities, supporting tile map loading, vector feature rendering, 3D model display, and more. Perfect for building smart cities, digital twins, geographic information systems, and other applications.
+
+### ✨ Core Features
+
+- 🚀 **High-Performance Rendering** - Built on Three.js WebGL engine, supports large-scale data visualization
+- 🗺️ **Multi-Source Tile Support** - Compatible with WMTS, ArcGIS, MapBox, Tianditu, and other mainstream tile services
+- 📐 **Rich Feature Types** - Supports points, lines, polygons, labels, models, and other geographic features
+- 🎨 **Flexible Style System** - Dynamic style configuration and theme switching
+- 🎯 **Complete Event System** - Rich event mechanisms for map interaction and feature events
+- 🛠️ **Powerful Drawing Tools** - Built-in drawing tools for interactive creation of points, lines, polygons, etc.
+- 🌈 **3D Effect Enhancement** - Supports skybox, shadows, HDR, clouds, and other visual effects
+- 📱 **UI Component System** - Provides info windows, tooltips, and other common UI components
+- 🔧 **Collision Detection** - Smart label avoidance for optimized dense feature display
+- 📦 **Modular Design** - Clear code structure, easy to extend and maintain
+
+---
+
+## 🌟 Why Choose Terra-GL
+
+### 💪 Technical Advantages
+
+**1. Native Three.js Architecture**
+- Fully built on Three.js with no additional rendering layer abstraction
+- Direct access to Three.js scene objects for free extension
+- Full utilization of WebGL performance advantages
+- Seamless integration with Three.js ecosystem
+
+**2. Professional GIS Capabilities**
+- Support for multiple coordinate systems and projection transformations (Web Mercator, WGS84, etc.)
+- Complete tile map system supporting massive data loading
+- Compatible with mainstream map services (WMTS, ArcGIS, MapBox, Tianditu)
+- Vector tile (MVT) rendering support
+
+**3. Rich Visualization Capabilities**
+- Unified management of 2D vector features (points, lines, polygons) and 3D models
+- GLTF/GLB model loading with Draco compression
+- Real-time shadows, HDR environment lighting, post-processing effects
+- Particle clouds, water ripples, and other special effects support
+
+**4. Flexible Interactive Experience**
+- Complete event system (map events, feature events)
+- Built-in drawing tools supporting points, lines, polygons, circles, etc.
+- Smart collision detection and label avoidance
+- Info windows, tooltips, and other UI components
+
+**5. Developer Friendly**
+- Written in TypeScript with complete type definitions
+- Clear modular design, easy to understand and extend
+- Rich examples and documentation
+- Supports both ES Module and UMD module formats
+
+### 💡 Use Cases
+
+| Category | Typical Applications | Core Capabilities |
+|---------|---------|----------|
+| **🏙️ Smart City** | Urban 3D modeling, BIM display, planning comparison | Large-scale model rendering, LOD control, layer management |
+| **🔮 Digital Twin** | Industrial parks, smart buildings, equipment monitoring | Real-time data binding, dynamic updates, state visualization |
+| **🗺️ GIS** | Terrain analysis, resource distribution, pipeline management | Coordinate conversion, spatial query, buffer analysis |
+| **🚨 Emergency Command** | Situation display, resource scheduling, route planning | Real-time tracking, heatmaps, dynamic plotting |
+
+### ⚡ Performance Features
+
+- **On-Demand Tile Loading** - Dynamically loads tiles based on viewport, supports tens of thousands of square kilometers of data
+- **LOD Level Control** - Automatically switches model detail based on distance, optimizing rendering performance
+- **Quadtree Spatial Indexing** - Fast query of visible features, improving interaction response speed
+- **WebGL Instanced Rendering** - Batch drawing of identical geometries, reducing draw calls
+- **Collision Avoidance Optimization** - Intelligently hides overlapping labels, keeping interface clean
+
+---
+
+## 📚 Core Module Overview
+
+### 🏗️ Core Architecture
+- **🗺️ Map** - Map container, unified management of layers, views, events
+- **👁️ Viewer** - Three.js-based rendering engine, manages scenes, cameras, lighting
+- **📚 Layer System** - Layered management of tiles, vectors, models, and other data
+- **📍 Feature** - Abstraction of geographic elements such as points, lines, polygons, models
+- **🔲 TileSystem** - Dynamic loading system supporting multi-source tiles like WMTS, ArcGIS
+
+### 🔑 Key Features
+- **⚡ Event System** - Complete map/feature-level event mechanism
+- **✏️ Drawing Tools** - Built-in interactive drawing (points, lines, polygons, circles, etc.)
+- **🎨 UI Components** - InfoWindow, ToolTip, and other common components
+- **🎯 Collision Detection** - Smart label avoidance, optimized dense scene display
+- **🎭 Style System** - Unified vector/model style configuration
+
+[View Detailed API Documentation →](link-to-detailed-docs)
+
+---
+## 🚀 Quick Start
+
+### 📦 Installation
+
+```bash
+npm install @terra.gl/core three@^0.171.0
+```
+
+### ⚡ 5-Minute Guide
+
+```javascript
+import * as terra from '@terra.gl/core';
+
+// Create map
+const map = new terra.Map('#map', {
+    center: [116.397428, 39.90923, 1000],  // [longitude, latitude, camera height]
+    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
+    }
+});
+
+// Add label
+const label = new terra.Label({
+    geometry: { type: 'Point', coordinates: [116.397428, 39.90923, 0] },
+    style: { text: 'Tiananmen Square', fontSize: 16, fontColor: '#ffffff' }
+});
+
+const pointLayer = new terra.PointLayer('points');
+map.addLayer(pointLayer);
+label.addTo(pointLayer);
+```
+
+See the `example/` directory for more examples.
+
+
+
+---
+
+## 🔧 Development
+
+### 🔨 Build
+
+```bash
+# Development mode (watch file changes)
+npm run dev
+
+# Production build
+npm run build
+
+# Generate API documentation
+npm run doc
+```
+
+### 📂 Project Structure
+
+```
+packages/core/
+├── src/                # Source code
+├── dist/               # Compiled output
+├── docs/               # API documentation
+├── assets/             # Asset files
+├── package.json        # Package configuration
+├── tsconfig.json       # TypeScript configuration
+├── vite.config.ts      # Vite build configuration
+└── typedoc.json        # Documentation generation configuration
+```
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+---
+
+## 🔗 Related Links
+
+- [Three.js Official Website](https://threejs.org/)\
+- [GeoJSON Specification](https://geojson.org/)
+- [WMTS Standard](https://www.ogc.org/standards/wmts)
+<!-- - [three-tile Website](https://sxguojf.github.io/three-tile-doc/1.introduce/01.whatIs/) -->
+---
+
+<div align="center">
+
+**If this project helps you, please give it a ⭐️ Star!**
+
+</div>

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>