@chocozhang/three-model-render 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [1.0.0] - 2025-12-08
+
+### ✨ Initial Release
+
+#### Core
+- `addChildModelLabels` - 3D model labels with 60% performance boost
+- `enableHoverBreath` - Hover breathing effect with 80% idle CPU reduction
+- `initPostProcessing` - Post-processing with auto-resize
+
+#### Interaction
+- `createModelClickHandler` - Click handling with debouncing
+- `ArrowGuide` - Arrow guide with fade effects
+- `LiquidFillerGroup` - Liquid filling animations
+
+#### Camera
+- `followModels` - Smooth camera following with easing
+- `setView` - Quick view switching
+
+#### Loader
+- `loadModelByUrl` - Universal model loader
+- `loadSkybox` - Skybox loader with caching
+- `BlueSky` - HDR/EXR environment manager
+
+#### UI
+- `createModelsLabel` - Labels with connection lines
+
+#### Effect
+- `GroupExploder` - Model explosion effects
+
+#### Setup
+- `autoSetupCameraAndLight` - Auto camera and lighting
+
+### Performance
+- CPU usage reduced by 55%
+- Memory usage reduced by 33%
+- Full TypeScript support
+- Tree-shaking enabled

package/README.md

@@ -1,231 +1,268 @@
 # three-model-render
 
-> 🚀 Professional Three.js Model Visualization and Interaction Toolkit
+> 🚀 专业级 Three.js 模型可视化与交互工具库
 
-A high-performance, TypeScript-first toolkit providing 14 optimized utilities for Three.js model visualization and interaction.
+[English](./README_EN.md) | 中文
 
-> 🌟 **[Live Demo: Experience the Power](https://happycolour.github.io/)**
+一个高性能、TypeScript 优先的工具库，提供 14 个经过优化的实用工具，专注于解决 Three.js 模型可视化与交互中的常见问题。
 
-[![Version](https://img.shields.io/badge/version-1.0.2-blue.svg)](https://github.com/HappyColour/three-model-render)
+> 🌟 **[在线体验 Demo](https://happycolour.github.io/)**
+
+[![Version](https://img.shields.io/badge/version-1.0.4-blue.svg)](https://github.com/HappyColour/three-model-render)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 
-## ✨ Features
+## ✨ 核心特性
 
-- 🎯 **14 High-Performance Utilities** - Covering all aspects of model visualization
-- 📦 **Tree-Shakable** - Import only what you need
-- 🔷 **TypeScript First** - Full type definitions and IntelliSense support
-- ⚡ **Optimized** - 55% less CPU usage, 33% less memory
-- 🎨 **Easy Integration** - Works with Vue, React, and vanilla JS
-- 📝 **Well Documented** - Comprehensive API docs and examples
+- 🎯 **14 个高性能工具** - 覆盖从加载、展示到交互的全流程
+- 📦 **支持 Tree-Shaking** - 按需引入，体积更小
+- 🔷 **TypeScript 优先** - 完整的类型定义与智能提示
+- ⚡ **性能优化** - 相比原生实现，闲置 CPU 占用降低 55%，内存占用降低 33%
+- 🎨 **无缝集成** - 完美支持 Vue 3, React 及原生 JavaScript
+- 📝 **完善文档** - 提供最佳实践指引与完整示例
 
 ---
 
-## 📦 Installation
+## 📦 安装
 
 ```bash
-npm install @chocozhang/three-model-render
-# OR
-yarn add @chocozhang/three-model-render
-# OR
-pnpm add @chocozhang/three-model-render
+npm install @chocozhang/three-model-render@latest
+# 或
+pnpm add @chocozhang/three-model-render@latest
+# 或
+yarn add @chocozhang/three-model-render@latest
 ```
 
-**Peer Dependencies:**
+**对等依赖 (Peer Dependencies):**
+请确保你的项目中安装了 `three`:
 ```bash
-npm install three@^0.160.0
+npm install three@^0.181.2
 ```
 
 ---
 
-## 🚀 Best Practice Workflow
+## 🚀 最佳实践工作流 (Best Practice Workflow)
 
-Build a professional 3D viewer following our optimized integration pattern. This workflow ensures maximum performance and visual quality.
+为了构建专业、高性能的 3D 查看器，我们建议遵循以下集成模式。此工作流经过生产环境验证，能确保最佳的视觉效果与性能表现。
 
-### 1. Core Setup & Model Loading
-Initialize your basic Three.js scene and load your model using our optimized loader.
+### 1. 基础环境与模型加载
+使用我们优化过的加载器初始化场景。它会自动处理 GLTF/GLB/FBX/OBJ 格式，并内置了 Draco 解码器配置。
 
 ```typescript
 import { loadModelByUrl } from '@chocozhang/three-model-render';
 
-// 1. Basic Three.js Setup
+// 1. 初始化基础场景
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000);
-const renderer = new THREE.WebGLRenderer();
+const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
 const controls = new OrbitControls(camera, renderer.domElement);
 
-// 2. Load Model with Progress
+// 2. 配置全局加载路径 (可选，默认使用本地 /draco/ 和 /basis/)
+import { setLoaderConfig } from '@chocozhang/three-model-render/loader';
+setLoaderConfig({
+    dracoDecoderPath: 'https://www.gstatic.com/draco/versioned/decoders/1.5.6/',
+    ktx2TranscoderPath: '/custom/basis/'
+});
+
+// 3. 加载模型 (自动启用缓存与纹理优化)
 const model = await loadModelByUrl('path/to/model.glb', {
-    manager: new THREE.LoadingManager(() => console.log('Loaded'))
+    maxTextureSize: 1024, // 自动缩小大纹理以节省显存
+    useCache: true        // 启用内部缓存，避免重复加载
 });
 scene.add(model);
 ```
 
-### 2. Auto-Configuration (Critical Step)
-Automatically position the camera and setup studio-quality lighting based on the model's bounding box.
+### 2. 自动场景配置 (关键步骤)
+根据模型的包围盒大小，自动计算最佳相机距离、近裁剪面(Near)和远裁剪面(Far)，并设置影棚级光照。
 
 ```typescript
 import { autoSetupCameraAndLight } from '@chocozhang/three-model-render/setup';
 
-// Automatically calculates optimal camera distance and lighting
-autoSetupCameraAndLight(camera, scene, model);
+// 方式 A: 一键配置相机与灯光
+const lightHandles = autoSetupCameraAndLight(camera, scene, model, {
+    enableShadows: true, 
+    intensity: 1.5      
+});
+
+// 方式 B: 灵活组合 (推荐)
+import { fitCameraToObject, setupDefaultLights } from '@chocozhang/three-model-render/setup';
+fitCameraToObject(camera, model, 1.2); // 仅调整相机
+const lights = setupDefaultLights(scene, model, { enableShadows: true }); // 仅添加灯光
 ```
 
-### 3. Cinematic Entrance
-Create a smooth entry animation to focus on the model.
+### 3. 电影级入场动画
+模型加载后，使用平滑的运镜动画将视角聚焦到模型正面。
 
 ```typescript
 import { followModels, FOLLOW_ANGLES } from '@chocozhang/three-model-render';
 
 followModels(camera, model, {
-    ...FOLLOW_ANGLES.FRONT,
-    duration: 1500,
-    padding: 0.6,
-    controls,
-    easing: 'easeInOut'
+    ...FOLLOW_ANGLES.FRONT, // 使用预设角度
+    duration: 1500,         // 动画时长 1.5s
+    padding: 0.8,           // 留白比例
+    controls,               // 绑定控制器以同步状态
+    easing: 'easeInOut'     // 缓动函数
 });
 ```
 
-### 4. Post-Processing & Hover Effects
-Enable high-performance post-processing and optimized hover effects (saves 80% CPU when idle).
+### 4. 后期处理与呼吸光效
+启用高性能后期处理管线和智能呼吸光效（闲置时自动降低帧率以节省电量）。
 
 ```typescript
 import { initPostProcessing, enableHoverBreath } from '@chocozhang/three-model-render';
 
-// 1. Initialize Post-Processing Manager
+// 1. 初始化后期处理管理器
 const ppManager = initPostProcessing(renderer, scene, camera, {
-    resolutionScale: 0.8, // Optimize performance
-    edgeStrength: 4,
-    visibleEdgeColor: '#ffee00'
+    resolutionScale: 0.8, // 降低分辨率以提升性能
+    edgeStrength: 4,      // 描边强度
+    visibleEdgeColor: '#ffee00' // 描边颜色
 });
 
-// 2. Enable Smart Hover Effect
+// 2. 启用智能悬停效果
 const hoverController = enableHoverBreath({
     camera,
     scene,
     renderer,
     outlinePass: ppManager.outlinePass,
-    throttleDelay: 16, // 60fps limit
-    minStrength: 2,
-    maxStrength: 8,
-    speed: 3
+    throttleDelay: 16,    // 60fps 节流
+    minStrength: 2,       // 呼吸最小强度
+    maxStrength: 8,       // 呼吸最大强度
+    speed: 3              // 呼吸速度
 });
 
-// IMPORTANT: Add composer to your animation loop
+// 重要: 在动画循环中调用 render
 function animate() {
-    // ...
+    requestAnimationFrame(animate);
+    // 使用 composer 替代 renderer.render
     ppManager.composer.render();
 }
 ```
 
-### 5. Interaction Handling
-Add intelligent click handling that zooms to parts and triggers actions.
+### 5. 交互处理系统的集成
+添加智能点击事件，支持自动聚焦到被点击的组件。
 
 ```typescript
 import { createModelClickHandler } from '@chocozhang/three-model-render';
 
+// 创建点击处理器 (返回销毁函数)
 const disposeClickHandler = createModelClickHandler(
     camera, 
     scene, 
     renderer, 
     ppManager.outlinePass, 
     (object, info) => {
-        console.log('Clicked:', info);
+        console.log('点击了:', info);
         
-        // Zoom to clicked part
+        // 聚焦到被点击的部件
         followModels(camera, object, {
             ...FOLLOW_ANGLES.ISOMETRIC,
-            duration: 1500
+            duration: 1000
         });
     }
 );
 ```
 
-### 6. Advanced Effects (Explosion)
-Add interactive mesh explosion/disassembly effects.
+### 6. 高级特效：爆炸分解
+无需复杂计算，一行代码实现模型的爆炸分解视图。
 
 ```typescript
 import { GroupExploder } from '@chocozhang/three-model-render';
 
-// Initialize
+// 初始化爆炸控制器
 const exploder = new GroupExploder(scene, camera, controls);
 exploder.init();
 
-// Set Targets
+// 设置需要爆炸的网格集合
 exploder.setMeshes(targetMeshes);
 
-// Explode
+// 执行爆炸 (Grid 模式)
 exploder.explode({ 
-    mode: 'grid', 
-    spacing: 2.8, 
-    dimOthers: { enabled: true, opacity: 0.1 } 
+    mode: 'grid',    // 排列模式: 'ring' | 'spiral' | 'grid' | 'radial'
+    spacing: 2.8,    // 间距
+    dimOthers: { enabled: true, opacity: 0.1 } // 使其他物体透明
 });
 
-// Restore
+// 还原
 exploder.restore(600);
 ```
 
-### 7. View Control
-Easily switch between standard views.
+### 7. 视角快速切换
+提供标准的工程视角切换功能。
 
 ```typescript
 import { setView } from '@chocozhang/three-model-render';
 
-// Switch to Top View
+// 切换到顶视图
 setView(camera, controls, model, 'top');
-// Switch to Isometric
+
+// 切换到等轴测视图 (ISO)
 setView(camera, controls, model, 'iso');
 ```
 
+### 8. 资源管理与内存释放 (重要)
+使用 `ResourceManager` 统一追踪并销毁 3D 资源，确保应用长期运行不泄露。
+
+```typescript
+import { ResourceManager } from '@chocozhang/three-model-render/core';
+
+const rm = new ResourceManager();
+
+// 追踪加载出的模型
+rm.track(model);
+
+// 当组件卸载时，一键销毁所有关联的几何体、材质与纹理
+rm.dispose();
+```
+
+---
+
+## 🌐 WebXR 兼容性说明
+
+本工具库的所有核心逻辑与 Three.js 的 WebXR 系统保持兼容：
+- `ResourceManager` 支持清理所有 XR 相关的 GPU 资源。
+- `autoSetupCameraAndLight` 计算的包围盒信息可直接用于 XR 传送或布局。
+- `loadModelByUrl` 经过优化的纹理大小非常适合移动端 VR/AR 设备。
+
+> [!NOTE]
+> 交互层 (`createModelClickHandler`) 目前主要针对鼠标与触屏优化。在 XR 环境下，建议结合控制器的射线检测使用。
+
 ---
 
-## 📚 Module Overview
+## 📚 模块总览 (Module Overview)
 
 ### **Core (`/core`)**
-- `initPostProcessing`: Performance-optimized post-processing manager.
-- `enableHoverBreath`: Idle-aware hover effects.
-- `addChildModelLabels`: 3D labeling system.
+- `initPostProcessing`: 高性能后期处理管理器，内置 OutlinePass。
+- `enableHoverBreath`: 智能呼吸光效，支持性能自适应。
+- `addChildModelLabels`: 3D 标签系统，自动跟随模型运动。
 
 ### **Camera (`/camera`)**
-- `followModels`: Smooth camera transitions.
-- `setView`: Preset view switching (Top, Front, Iso, etc.).
+- `followModels`: 智能相机跟随与聚焦。
+- `setView`: 预设视角切换 (Top, Front, Iso, etc.)。
 
 ### **Loader (`/loader`)**
-- `loadModelByUrl`: Robust model loader (GLTF, FBX, OBJ).
-- `BlueSky`: Environment map manager.
+- `loadModelByUrl`: 统一模型加载器，支持多种格式。
+- `BlueSky`: 快速创建天空盒环境。
 
 ### **Interaction (`/interaction`)**
-- `createModelClickHandler`: Raycasting click handler.
+- `createModelClickHandler`: 射线检测点击处理器。
 
 ### **Effect (`/effect`)**
-- `GroupExploder`: Mesh disassembly animations.
+- `GroupExploder`: 模型爆炸/拆解动画控制器。
 
 ### **Setup (`/setup`)**
-- `autoSetupCameraAndLight`: Instant scene configuration.
+- `autoSetupCameraAndLight`: 一键自动化场景配置大师。
 
 ---
 
-## 🎨 HTML/Vue 3 Example
+## 🎨 示例项目
 
-For a complete, deployable HTML/Vue 3 example demonstrating all these features, check `examples/html-best-practice/`.
+我们提供了一个完整的、可部署的示例项目，展示了所有功能的集成方式：
 
----
-
-## ⚙️ TypeScript Support
-
-Full TypeScript definitions included. Ensure your `tsconfig.json` matches:
-```json
-{
-  "compilerOptions": {
-    "lib": ["ES2015", "DOM"],
-    "target": "ES2015",
-    "module": "ESNext"
-  }
-}
-```
+- 👉 **[Vue 3 示例 (推荐)](https://github.com/HappyColour/three-model-render/tree/main/examples/vue-example)** - 完整的 Vue 3 + TypeScript 集成最佳实践
+- 👉 **[HTML 原生示例](https://github.com/HappyColour/three-model-render/tree/main/examples/html-example)** - 适合原生 JavaScript / jQuery 项目
 
 ---
 
-## 📄 License
+## 📄 开源协议
 
 MIT © [Danny Zhang]

package/dist/camera/index.d.ts

@@ -1,6 +1,18 @@
 import * as THREE from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
 
+/**
+ * @file followModels.ts
+ * @description
+ * Camera utility to automatically follow and focus on 3D models.
+ * It smoothly moves the camera to an optimal viewing position relative to the target object(s).
+ *
+ * @best-practice
+ * - Use `followModels` to focus on a newly selected object.
+ * - Call `cancelFollow` before starting a new manual camera interaction if needed.
+ * - Adjust `padding` to control how tight the camera framing is.
+ */
+
 interface FollowOptions {
     duration?: number;
     padding?: number;
@@ -16,72 +28,83 @@ interface FollowOptions {
     onProgress?: (progress: number) => void;
 }
 /**
- * 推荐角度枚举，便于快速选取常见视角
+ * Recommended camera angles for quick selection of common views
  */
 declare const FOLLOW_ANGLES: {
-    /** 等距斜视（默认视角）- 适合建筑、机械设备展示 */
+    /** Isometric view (default) - suitable for architecture, mechanical equipment */
     readonly ISOMETRIC: {
         readonly azimuth: number;
         readonly elevation: number;
     };
-    /** 正前视角 - 适合正面展示、UI 对齐 */
+    /** Front view - suitable for frontal display, UI alignment */
     readonly FRONT: {
         readonly azimuth: 0;
         readonly elevation: 0;
     };
-    /** 右侧视角 - 适合机械剖面、侧视检查 */
+    /** Right view - suitable for mechanical sections, side inspection */
     readonly RIGHT: {
         readonly azimuth: number;
         readonly elevation: 0;
     };
-    /** 左侧视角 */
+    /** Left view */
     readonly LEFT: {
         readonly azimuth: number;
         readonly elevation: 0;
     };
-    /** 后视角 */
+    /** Back view */
     readonly BACK: {
         readonly azimuth: number;
         readonly elevation: 0;
     };
-    /** 顶视图 - 适合地图、平面布局展示 */
+    /** Top view - suitable for maps, layout display */
     readonly TOP: {
         readonly azimuth: 0;
         readonly elevation: number;
     };
-    /** 低角度俯视 - 适合车辆、人物等近地物体 */
+    /** Low angle view - suitable for vehicles, characters near the ground */
     readonly LOW_ANGLE: {
         readonly azimuth: number;
         readonly elevation: number;
     };
-    /** 高角度俯视 - 适合鸟瞰、全景浏览 */
+    /** High angle view - suitable for bird's eye view, panoramic browsing */
     readonly HIGH_ANGLE: {
         readonly azimuth: number;
         readonly elevation: number;
     };
 };
 /**
- * 自动将相机移到目标的斜上角位置，并保证目标在可视范围内（平滑过渡）- 优化版
+ * Automatically moves the camera to a diagonal position relative to the target,
+ * ensuring the target is within the field of view (smooth transition).
  *
- * ✨ 优化内容：
- * - 支持多种缓动函数
- * - 添加进度回调
- * - 支持取消动画
- * - WeakMap 跟踪防止泄漏
- * - 完善错误处理
+ * Features:
+ * - Supports multiple easing functions
+ * - Adds progress callback
+ * - Supports animation cancellation
+ * - Uses WeakMap to track and prevent memory leaks
+ * - Robust error handling
  */
 declare function followModels(camera: THREE.Camera, targets: THREE.Object3D | THREE.Object3D[] | null | undefined, options?: FollowOptions): Promise<void>;
 /**
- * ✨ 取消相机的跟随动画
+ * Cancel the camera follow animation
  */
 declare function cancelFollow(camera: THREE.Camera): void;
 
 /**
- * 视角类型
+ * @file setView.ts
+ * @description
+ * Utility to smoothly transition the camera to preset views (Front, Back, Top, Isometric, etc.).
+ *
+ * @best-practice
+ * - Use `setView` for UI buttons that switch camera angles.
+ * - Leverage `ViewPresets` for readable code when using standard views.
+ */
+
+/**
+ * View types
  */
 type ViewPosition = 'front' | 'back' | 'left' | 'right' | 'top' | 'bottom' | 'iso';
 /**
- * 视角配置选项
+ * View configuration options
  */
 interface SetViewOptions {
     distanceFactor?: number;
@@ -90,41 +113,41 @@ interface SetViewOptions {
     onProgress?: (progress: number) => void;
 }
 /**
- * 平滑切换相机到模型的最佳视角 - 优化版
+ * Smoothly switches the camera to the optimal angle for the model.
  *
- * ✨ 优化内容：
- * - 复用 followModels 逻辑，避免代码重复
- * - 支持更多视角
- * - 配置选项增强
- * - 返回 Promise 支持链式调用
- * - 支持取消动画
+ * Features:
+ * - Reuses followModels logic to avoid code duplication
+ * - Supports more angles
+ * - Enhanced configuration options
+ * - Returns Promise to support chaining
+ * - Supports animation cancellation
  *
- * @param camera       THREE.PerspectiveCamera 相机实例
- * @param controls     OrbitControls 控制器实例
- * @param targetObj    THREE.Object3D 模型对象
- * @param position     视角位置
- * @param options      配置选项
+ * @param camera       THREE.PerspectiveCamera instance
+ * @param controls     OrbitControls instance
+ * @param targetObj    THREE.Object3D model object
+ * @param position     View position
+ * @param options      Configuration options
  * @returns Promise<void>
  */
 declare function setView(camera: THREE.PerspectiveCamera, controls: OrbitControls, targetObj: THREE.Object3D, position?: ViewPosition, options?: SetViewOptions): Promise<void>;
 /**
- * ✨ 取消视角切换动画
+ * Cancel view switch animation
  */
 declare function cancelSetView(camera: THREE.PerspectiveCamera): void;
 /**
- * ✨ 预设视角快捷方法
+ * Preset view shortcut methods
  */
 declare const ViewPresets: {
     /**
-     * 前视图
+     * Front View
      */
     front: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
     /**
-     * 等距视图
+     * Isometric View
      */
     isometric: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
     /**
-     * 顶视图
+     * Top View
      */
     top: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
 };