@metagl/sdk-render 1.0.13 → 1.0.14

package/README.md

@@ -1,6 +1,45 @@
-# 地图SDK - 三维地球渲染引擎
-
-![渲染引擎预览](https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png)
+<h1 align="center">LACDT Render WebSDK- 三维地球渲染引擎</h1>
+
+<p align="center">一个基于Cesium的三维地球渲染引擎，提供了丰富的地图操作和数据分析功能。它采用模块化架构，包含多个功能系统，支持地图加载、图层管理、建筑模型展示、测量工具、3D Tiles搜索等功能。</p>
+
+<p align="center">
+  <a href="https://github.com/ASunYC/sdk-render/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/ASunYC/sdk-render.svg?style=flat&colorA=080f12&colorB=1fa669" alt="License">
+  </a>
+  <a href="https://github.com/ASunYC/sdk-render">
+    <img src="https://img.shields.io/github/stars/ASunYC/sdk-render?style=flat&colorA=080f12&colorB=1fa669" alt="Stars">
+  </a>
+  <a href="https://github.com/ASunYC/sdk-render/issues">
+    <img src="https://img.shields.io/github/issues/ASunYC/sdk-render?style=flat&colorA=080f12&colorB=1fa669" alt="Issues">
+  </a>
+  <a href="https://www.npmjs.com/package/@metagl/sdk-render">
+    <img src="https://img.shields.io/npm/v/@metagl/sdk-render.svg?style=flat&colorA=080f12&colorB=1fa669" alt="NPM Version">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#核心特性">功能特性</a> •
+  <a href="#快速开始">快速开始</a> •
+  <a href="#系统架构">系统架构</a> •
+  <a href="#更新日志">更新日志</a> •
+  <a href="#联系方式">联系方式</a>
+</p>
+
+<picture>
+  <source
+    width="100%"
+    srcset="https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png"
+    media="(prefers-color-scheme: dark)"
+  />
+  <source
+    width="100%"
+    srcset="https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png"
+    media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)"
+  />
+  <img width="250" src="https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png" />
+</picture>
+
+---
 
 ## 项目简介
 
@@ -61,7 +100,8 @@ const viewer = new Viewer(container);
 // 配置渲染引擎
 const config: RenderConfig = {
     viewer: viewer,
-    token: 'your-access-token'  // 访问 LACDT 资源的 token（必填）
+    token: 'your-access-token',  // 访问 LACDT 资源的 token（必填）
+    assetsBasePath: '/'          // 资源文件基础路径（可选，默认自动检测）
 };
 
 // 初始化渲染引擎（异步方式）
@@ -71,6 +111,102 @@ const render = await Render.create(config);
 **Token 说明**：
 - `token` 是访问 LACDT 资源的必填参数
 
+**资源路径说明**：
+- `assetsBasePath` 用于指定 SDK 资源文件（纹理、数据等）的基础路径
+- 默认会自动检测，但在某些打包工具（如 Vite）中可能需要手动设置
+- 开发模式和生产模式的路径可能不同，需要根据实际情况配置
+
+### 资源路径配置
+
+SDK 需要加载资源文件（纹理、数据等），需要正确配置资源路径：
+
+#### 方式1：初始化时设置（推荐）
+
+```typescript
+const render = await Render.create({
+    viewer: viewer,
+    token: 'your-token',
+    assetsBasePath: '/'  // 资源在网站根目录
+});
+```
+
+#### 方式2：手动设置
+
+```typescript
+import { setSdkBasePath } from '@metagl/sdk-render';
+
+// 在使用任何系统之前设置
+setSdkBasePath('/');
+```
+
+#### 方式3：全局变量设置
+
+```html
+<script>
+  window.__SDK_RENDER_BASE_PATH__ = '/';
+</script>
+<script src="lacdt.render.js"></script>
+```
+
+### 打包工具配置
+
+#### Vite 项目
+
+安装 `vite-plugin-static-copy` 插件：
+
+```bash
+npm install -D vite-plugin-static-copy
+```
+
+配置 `vite.config.js`：
+
+```javascript
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+
+export default defineConfig({
+  plugins: [
+    viteStaticCopy({
+      targets: [
+        // Cesium 资源
+        { src: 'node_modules/cesium/Build/Cesium/*', dest: 'cesium' },
+        // SDK 资源
+        { src: 'node_modules/@metagl/sdk-render/assets', dest: 'assets' },
+        { src: 'node_modules/@metagl/sdk-render/resources', dest: 'resources' }
+      ]
+    })
+  ],
+  define: {
+    CESIUM_BASE_URL: JSON.stringify('/cesium')
+  }
+})
+```
+
+然后在代码中设置：
+
+```typescript
+import { setSdkBasePath } from '@metagl/sdk-render';
+setSdkBasePath('/');
+```
+
+#### Webpack 项目
+
+在 `webpack.config.js` 中添加：
+
+```javascript
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+
+module.exports = {
+  plugins: [
+    new CopyWebpackPlugin({
+      patterns: [
+        { from: 'node_modules/@metagl/sdk-render/assets', to: 'assets' },
+        { from: 'node_modules/@metagl/sdk-render/resources', to: 'resources' }
+      ]
+    })
+  ]
+}
+```
+
 ### 基本使用
 
 ```typescript
@@ -168,6 +304,22 @@ SDK渲染引擎采用模块化架构，包含以下系统：
 
 ## 更新日志
 
+### V1.0.12 (2026-04-09)
+
+#### 新增功能
+- **资源路径管理系统**
+  - 新增 `AssetPathResolver` 资源路径解析器，统一管理 SDK 资源路径
+  - 支持开发模式自动检测和生产模式路径配置
+  - 新增 `setSdkBasePath()`、`getSdkBasePath()`、`resolveAssetPath()` API
+  - `RenderConfig` 新增 `assetsBasePath` 配置项
+
+#### 资源目录调整
+- 统一资源目录结构至 `assets` 和 `resources` 目录
+  - `assets/Textures/` - 体积云纹理
+  - `assets/Images/` - 水体法线贴图等图片资源
+  - `resources/water/` - 海洋数据
+  - `resources/textures/` - 其他纹理资源
+
 ### V1.0.11 (2026-04-02)
 
 #### 新增功能

package/README_EN.md

@@ -1,6 +1,45 @@
-# Map SDK - 3D Earth Rendering Engine
-
-![Rendering Engine Preview](https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png)
+<h1 align="center">LACDT Render WebSDK - 3D Earth Rendering Engine</h1>
+
+<p align="center">A Cesium-based 3D Earth rendering engine providing rich map operations and data analysis capabilities. It adopts a modular architecture with multiple functional systems, supporting map loading, layer management, building model display, measurement tools, 3D Tiles search, and more.</p>
+
+<p align="center">
+  <a href="https://github.com/ASunYC/sdk-render/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/ASunYC/sdk-render.svg?style=flat&colorA=080f12&colorB=1fa669" alt="License">
+  </a>
+  <a href="https://github.com/ASunYC/sdk-render">
+    <img src="https://img.shields.io/github/stars/ASunYC/sdk-render?style=flat&colorA=080f12&colorB=1fa669" alt="Stars">
+  </a>
+  <a href="https://github.com/ASunYC/sdk-render/issues">
+    <img src="https://img.shields.io/github/issues/ASunYC/sdk-render?style=flat&colorA=080f12&colorB=1fa669" alt="Issues">
+  </a>
+  <a href="https://www.npmjs.com/package/@metagl/sdk-render">
+    <img src="https://img.shields.io/npm/v/@metagl/sdk-render.svg?style=flat&colorA=080f12&colorB=1fa669" alt="NPM">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#core-features">Core Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#system-architecture">System Architecture</a> •
+  <a href="#changelog">Changelog</a> •
+  <a href="#contact-information">Contact</a>
+</p>
+
+<picture>
+  <source
+    width="100%"
+    srcset="https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png"
+    media="(prefers-color-scheme: dark)"
+  />
+  <source
+    width="100%"
+    srcset="https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png"
+    media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)"
+  />
+  <img width="250" src="https://gitee.com/ASun001/Resource/raw/master/RenderPreview.png" />
+</picture>
+
+---
 
 ## Project Introduction
 
@@ -61,7 +100,8 @@ const viewer = new Viewer(container);
 // Configure rendering engine
 const config: RenderConfig = {
     viewer: viewer,
-    token: 'your-access-token'  // Token for accessing LACDT resources (required)
+    token: 'your-access-token',  // Token for accessing LACDT resources (required)
+    assetsBasePath: '/'          // Base path for resource files (optional, auto-detected by default)
 };
 
 // Initialize rendering engine (async method)
@@ -71,6 +111,102 @@ const render = await Render.create(config);
 **Token Description**:
 - `token` is a required parameter for accessing LACDT resources
 
+**Resource Path Description**:
+- `assetsBasePath` specifies the base path for SDK resource files (textures, data, etc.)
+- Auto-detection is enabled by default, but manual configuration may be needed in some bundlers (e.g., Vite)
+- Development and production modes may require different paths
+
+### Resource Path Configuration
+
+SDK requires loading resource files (textures, data, etc.). Proper path configuration is essential:
+
+#### Method 1: Set During Initialization (Recommended)
+
+```typescript
+const render = await Render.create({
+    viewer: viewer,
+    token: 'your-token',
+    assetsBasePath: '/'  // Resources at website root
+});
+```
+
+#### Method 2: Manual Setup
+
+```typescript
+import { setSdkBasePath } from '@metagl/sdk-render';
+
+// Set before using any system
+setSdkBasePath('/');
+```
+
+#### Method 3: Global Variable Setup
+
+```html
+<script>
+  window.__SDK_RENDER_BASE_PATH__ = '/';
+</script>
+<script src="lacdt.render.js"></script>
+```
+
+### Build Tool Configuration
+
+#### Vite Project
+
+Install `vite-plugin-static-copy` plugin:
+
+```bash
+npm install -D vite-plugin-static-copy
+```
+
+Configure `vite.config.js`:
+
+```javascript
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+
+export default defineConfig({
+  plugins: [
+    viteStaticCopy({
+      targets: [
+        // Cesium resources
+        { src: 'node_modules/cesium/Build/Cesium/*', dest: 'cesium' },
+        // SDK resources
+        { src: 'node_modules/@metagl/sdk-render/assets', dest: 'assets' },
+        { src: 'node_modules/@metagl/sdk-render/resources', dest: 'resources' }
+      ]
+    })
+  ],
+  define: {
+    CESIUM_BASE_URL: JSON.stringify('/cesium')
+  }
+})
+```
+
+Then set in your code:
+
+```typescript
+import { setSdkBasePath } from '@metagl/sdk-render';
+setSdkBasePath('/');
+```
+
+#### Webpack Project
+
+Add to `webpack.config.js`:
+
+```javascript
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+
+module.exports = {
+  plugins: [
+    new CopyWebpackPlugin({
+      patterns: [
+        { from: 'node_modules/@metagl/sdk-render/assets', to: 'assets' },
+        { from: 'node_modules/@metagl/sdk-render/resources', to: 'resources' }
+      ]
+    })
+  ]
+}
+```
+
 ### Basic Usage
 
 ```typescript
@@ -168,6 +304,22 @@ The SDK rendering engine adopts a modular architecture, including the following
 
 ## Changelog
 
+### V1.0.12 (2026-04-09)
+
+#### New Features
+- **Resource Path Management System**
+  - Added `AssetPathResolver` for unified SDK resource path management
+  - Support for auto-detection in development mode and path configuration in production mode
+  - Added `setSdkBasePath()`, `getSdkBasePath()`, `resolveAssetPath()` APIs
+  - Added `assetsBasePath` configuration option to `RenderConfig`
+
+#### Resource Directory Adjustment
+- Unified resource directory structure to `assets` and `resources` directories
+  - `assets/Textures/` - Volumetric cloud textures
+  - `assets/Images/` - Water normal maps and other image resources
+  - `resources/water/` - Ocean data
+  - `resources/textures/` - Other texture resources
+
 ### V1.0.11 (2026-04-02)
 
 #### New Features