@chocozhang/three-model-render 1.0.2 → 1.0.4

package/README.md

@@ -1,609 +1,228 @@
 # 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) | 中文
 
-[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/HappyColour/three-model-render)
+一个高性能、TypeScript 优先的工具库，提供 14 个经过优化的实用工具，专注于解决 Three.js 模型可视化与交互中的常见问题。
+
+> 🌟 **[在线体验 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
-
-### Using npm
-```bash
-npm install @chocozhang/three-model-render
-```
+## 📦 安装
 
-### Using yarn
 ```bash
-yarn 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
 ```
 
-### Using pnpm
-```bash
-pnpm add @chocozhang/three-model-render
-```
-
-**Peer Dependencies:**
+**对等依赖 (Peer Dependencies):**
+请确保你的项目中安装了 `three`:
 ```bash
 npm install three@^0.160.0
 ```
 
 ---
 
-## 🚀 Quick Start
+## 🚀 最佳实践工作流 (Best Practice Workflow)
 
-### Import全量 (Supports Tree-shaking)
-```typescript
-import { followModels, addChildModelLabels, enableHoverBreath } from '@chocozhang/three-model-render'
+为了构建专业、高性能的 3D 查看器，我们建议遵循以下集成模式。此工作流经过生产环境验证，能确保最佳的视觉效果与性能表现。
 
-// Use the utilities
-followModels(camera, model, {
-  easing: 'easeInOut',
-  duration: 1000
-})
-```
+### 1. 基础环境与模型加载
+使用我们优化过的加载器初始化场景。它会自动处理 GLTF/GLB/FBX/OBJ 格式，并内置了 Draco 解码器配置。
 
-### Import按需 (Recommended)
 ```typescript
-// Only import what you need
-import { followModels } from '@chocozhang/three-model-render/camera'
-import { addChildModelLabels } from '@chocozhang/three-model-render/core'
-import { enableHoverBreath } from '@chocozhang/three-model-render/core'
-```
-
----
-
-## 📚 Module Overview
-
-### Core Utilities (`/core`)
-High-frequency rendering optimizations
-
-- **`addChildModelLabels`** - 3D model labels with 60% less CPU
-- **`enableHoverBreath`** - Hover breathing effect with 80% less idle CPU
-- **`initPostProcessing`** - Post-processing with resize support
-
-### Interaction Utilities (`/interaction`)
-User interaction enhancements
-
-- **`createModelClickHandler`** - Click handling with debouncing
-- **`ArrowGuide`** - Arrow指引 with fade effects
-- **`LiquidFillerGroup`** - Liquid filling animations
-
-### Camera Utilities (`/camera`)
-Camera control and animation
-
-- **`followModels`** - Smooth camera following with easing
-- **`setView`** - Quick view switching with animations
-
-### Loader Utilities (`/loader`)
-Asset loading and management
-
-- **`loadModelByUrl`** - Universal model loader (FBX, GLTF, OBJ, etc.)
-- **`loadSkybox`** - Skybox loader with caching
-- **`BlueSky`** - HDR/EXR environment manager
-
-### UI Utilities (`/ui`)
-User interface components
-
-- **`createModelsLabel`** - Labels with connection lines and fade-in
-
-### Effect Utilities (`/effect`)
-Visual effects
-
-- **`GroupExploder`** - Model explosion effects with multiple modes
-
-### Setup Utilities (`/setup`)
-Scene initialization
-
-- **`autoSetupCameraAndLight`** - Auto camera and lighting setup
-
----
-
-## 📖 Detailed API Documentation
-
-### Core: addChildModelLabels
-
-Add floating 3D labels to model children with automatic position tracking.
+import { loadModelByUrl } from '@chocozhang/three-model-render';
 
-**Features:**
-- ✅ Bounding box caching (60% performance boost)
-- ✅ Pause/resume API
-- ✅ Configurable update intervals
+// 1. 初始化基础场景
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000);
+const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
+const controls = new OrbitControls(camera, renderer.domElement);
 
-**Usage:**
-```typescript
-import { addChildModelLabels } from '@chocozhang/three-model-render/core'
-
-const labelManager = addChildModelLabels(camera, renderer, model, {
-  'part1': 'Component 1',
-  'part2': 'Component 2'
-}, {
-  enableCache: true,      // Enable bounding box caching
-  updateInterval: 33,     // Update at 30fps
-  fontSize: '14px',
-  color: '#ffffff'
-})
-
-// Control lifecycle
-labelManager.pause()        // Pause updates
-labelManager.resume()       // Resume updates
-labelManager.isRunning()    // Check status
-labelManager.dispose()      // Clean up
-```
-
-**Options:**
-```typescript
-interface LabelOptions {
-  fontSize?: string           // Default: '12px'
-  color?: string             // Default: '#ffffff'
-  background?: string        // Default: '#1890ff'
-  padding?: string           // Default: '6px 10px'
-  borderRadius?: string      // Default: '6px'
-  updateInterval?: number    // Default: 0 (every frame)
-  enableCache?: boolean      // Default: true
-}
+// 2. 加载模型 (支持进度回调)
+const model = await loadModelByUrl('path/to/model.glb', {
+    manager: new THREE.LoadingManager(() => console.log('加载完成'))
+});
+scene.add(model);
 ```
 
----
-
-### Core: enableHoverBreath
-
-Breathing outline effect on hover with intelligent performance optimization.
-
-**Features:**
-- ✅ Auto-pause when no object is hovered (80% idle CPU reduction)
-- ✅ Mousemove throttling
-- ✅ Passive event listeners
-
-**Usage:**
-```typescript
-import { enableHoverBreath } from '@chocozhang/three-model-render/core'
-
-const hoverEffect = enableHoverBreath({
-  camera,
-  scene,
-  renderer,
-  outlinePass,
-  highlightNames: ['model1', 'model2'],
-  throttleDelay: 16,      // 60fps throttling
-  minStrength: 2,
-  maxStrength: 8,
-  speed: 3
-})
-
-// Cleanup
-hoverEffect.dispose()
-```
-
----
-
-### Core: initPostProcessing
-
-Initialize post-processing with resize handling and performance options.
-
-**Features:**
-- ✅ Auto-resize support
-- ✅ Resolution scaling for performance
-- ✅ Complete lifecycle management
+### 2. 自动场景配置 (关键步骤)
+根据模型的包围盒大小，自动计算最佳相机距离、近裁剪面(Near)和远裁剪面(Far)，并设置影棚级光照。
 
-**Usage:**
 ```typescript
-import { initPostProcessing } from '@chocozhang/three-model-render/core'
+import { autoSetupCameraAndLight } from '@chocozhang/three-model-render/setup';
 
-const ppManager = initPostProcessing(renderer, scene, camera, {
-  resolutionScale: 0.8,    // 80% resolution for better performance
-  edgeStrength: 4,
-  visibleEdgeColor: '#ffee00'
-})
-
-// Access components
-ppManager.composer.render()
-ppManager.outlinePass.selectedObjects = [mesh]
-
-// Handle resize
-window.addEventListener('resize', () => ppManager.resize())
-
-// Cleanup
-ppManager.dispose()
+// 一键配置相机与灯光
+const lightHandles = autoSetupCameraAndLight(camera, scene, model, {
+    enableShadows: true, // 开启阴影
+    intensity: 1.5       // 光照强度
+});
 ```
 
----
-
-### Camera: followModels
-
-Smoothly move camera to focus on target objects with easing animations.
-
-**Features:**
-- ✅ Multiple easing functions
-- ✅ Progress callback
-- ✅ Cancelable animations
+### 3. 电影级入场动画
+模型加载后，使用平滑的运镜动画将视角聚焦到模型正面。
 
-**Usage:**
 ```typescript
-import { followModels, cancelFollow } from '@chocozhang/three-model-render/camera'
-
-await followModels(camera, targetMesh, {
-  easing: 'easeInOut',           // 'linear' | 'easeIn' | 'easeOut' | 'easeInOut'
-  duration: 1000,
-  padding: 1.2,
-  controls: orbitControls,
-  onProgress: (progress) => {
-    console.log(`Animation: ${progress * 100}%`)
-  }
-})
-
-// Cancel animation
-cancelFollow(camera)
-```
-
-**Preset Angles:**
-```typescript
-import { FOLLOW_ANGLES } from '@chocozhang/three-model-render/camera'
+import { followModels, FOLLOW_ANGLES } from '@chocozhang/three-model-render';
 
 followModels(camera, model, {
-  ...FOLLOW_ANGLES.ISOMETRIC  // 45° diagonal view
-})
-```
-
----
-
-### Camera: setView
-
-Quick view switching with smooth animations.
-
-**Usage:**
-```typescript
-import { setView, ViewPresets } from '@chocozhang/three-model-render/camera'
-
-// Programmatic view
-await setView(camera, controls, model, 'front', {
-  easing: 'easeInOut',
-  duration: 800
-})
-
-// Using presets
-ViewPresets.isometric(camera, controls, model)
-ViewPresets.top(camera, controls, model)
+    ...FOLLOW_ANGLES.FRONT, // 使用预设角度
+    duration: 1500,         // 动画时长 1.5s
+    padding: 0.8,           // 留白比例
+    controls,               // 绑定控制器以同步状态
+    easing: 'easeInOut'     // 缓动函数
+});
 ```
 
-**Supported Views:**
-- `'front'` - Front view
-- `'back'` - Back view
-- `'left'` - Left side
-- `'right'` - Right side
-- `'top'` - Top view
-- `'bottom'` - Bottom view
-- `'iso'` - Isometric view
-
----
-
-### Loader: loadModelByUrl
-
-Universal model loader supporting multiple formats.
-
-**Features:**
-- ✅ Auto-format detection
-- ✅ DRACO/KTX2 support (GLTF)
-- ✅ Geometry optimization
-- ✅ Texture downscaling
+### 4. 后期处理与呼吸光效
+启用高性能后期处理管线和智能呼吸光效（闲置时自动降低帧率以节省电量）。
 
-**Usage:**
 ```typescript
-import { loadModelByUrl } from '@chocozhang/three-model-render/loader'
+import { initPostProcessing, enableHoverBreath } from '@chocozhang/three-model-render';
 
-const model = await loadModelByUrl('/path/to/model.fbx', {
-  mergeGeometries: false,
-  maxTextureSize: 2048,      // Downscale large textures
-  useSimpleMaterials: false
-})
-
-scene.add(model)
+// 1. 初始化后期处理管理器
+const ppManager = initPostProcessing(renderer, scene, camera, {
+    resolutionScale: 0.8, // 降低分辨率以提升性能
+    edgeStrength: 4,      // 描边强度
+    visibleEdgeColor: '#ffee00' // 描边颜色
+});
+
+// 2. 启用智能悬停效果
+const hoverController = enableHoverBreath({
+    camera,
+    scene,
+    renderer,
+    outlinePass: ppManager.outlinePass,
+    throttleDelay: 16,    // 60fps 节流
+    minStrength: 2,       // 呼吸最小强度
+    maxStrength: 8,       // 呼吸最大强度
+    speed: 3              // 呼吸速度
+});
+
+// 重要: 在动画循环中调用 render
+function animate() {
+    requestAnimationFrame(animate);
+    // 使用 composer 替代 renderer.render
+    ppManager.composer.render();
+}
 ```
 
-**Supported Formats:**
-- GLTF/GLB (with DRACO & KTX2)
-- FBX
-- OBJ
-- PLY
-- STL
-
----
-
-### Loader: BlueSky (HDR/EXR Manager)
-
-Global singleton for managing HDR/EXR environment maps.
-
-**Features:**
-- ✅ Promise API with progress
-- ✅ Loading state management
-- ✅ Cancel loading support
+### 5. 交互处理系统的集成
+添加智能点击事件，支持自动聚焦到被点击的组件。
 
-**Usage:**
 ```typescript
-import { BlueSky } from '@chocozhang/three-model-render/loader'
-
-// Initialize
-BlueSky.init(renderer, scene, 1.0)
-
-// Load with progress
-await BlueSky.loadAsync('/sky.exr', {
-  background: true,
-  onProgress: (progress) => {
-    console.log(`Loading: ${Math.round(progress * 100)}%`)
-  },
-  onComplete: () => console.log('Loaded!'),
-  onError: (err) => console.error(err)
-})
-
-// Check status
-BlueSky.isLoading()          // boolean
-BlueSky.getLoadingState()    // 'idle' | 'loading' | 'loaded' | 'error'
-
-// Cancel
-BlueSky.cancelLoad()
-
-// Cleanup
-BlueSky.dispose()
-```
-
----
-
-### UI: createModelsLabel
-
-Create labels with connection lines and animations.
+import { createModelClickHandler } from '@chocozhang/three-model-render';
+
+// 创建点击处理器 (返回销毁函数)
+const disposeClickHandler = createModelClickHandler(
+    camera, 
+    scene, 
+    renderer, 
+    ppManager.outlinePass, 
+    (object, info) => {
+        console.log('点击了:', info);
+        
+        // 聚焦到被点击的部件
+        followModels(camera, object, {
+            ...FOLLOW_ANGLES.ISOMETRIC,
+            duration: 1000
+        });
+    }
+);
+```
+
+### 6. 高级特效：爆炸分解
+无需复杂计算，一行代码实现模型的爆炸分解视图。
 
-**Features:**
-- ✅ Pause/resume API
-- ✅ Bounding box caching
-- ✅ Fade-in animations
-
-**Usage:**
 ```typescript
-import { createModelsLabel } from '@chocozhang/three-model-render/ui'
-
-const labelMgr = createModelsLabel(camera, renderer, model, {
-  'mesh1': 'Part A',
-  'mesh2': 'Part B'
-}, {
-  updateInterval: 33,      // 30fps
-  fadeInDuration: 300,     // 300ms fade-in
-  lift: 100,               // Lift labels 100px
-  lineColor: 'rgba(200,200,200,0.7)'
-})
-
-// Control
-labelMgr.pause()
-labelMgr.resume()
-labelMgr.dispose()
-```
-
----
+import { GroupExploder } from '@chocozhang/three-model-render';
 
-### Effect: GroupExploder
+// 初始化爆炸控制器
+const exploder = new GroupExploder(scene, camera, controls);
+exploder.init();
 
-Model explosion effects with multiple arrangement modes.
+// 设置需要爆炸的网格集合
+exploder.setMeshes(targetMeshes);
 
-**Features:**
-- ✅ 4 explosion modes (ring, spiral, grid, radial)
-- ✅ Smooth animations
-- ✅ Dim other objects
+// 执行爆炸 (Grid 模式)
+exploder.explode({ 
+    mode: 'grid',    // 排列模式: 'ring' | 'spiral' | 'grid' | 'radial'
+    spacing: 2.8,    // 间距
+    dimOthers: { enabled: true, opacity: 0.1 } // 使其他物体透明
+});
 
-**Usage:**
-```typescript
-import { GroupExploder } from '@chocozhang/three-model-render/effect'
-
-const exploder = new GroupExploder(scene, camera, controls)
-exploder.init()
-
-// Set target meshes
-const meshes = new Set([mesh1, mesh2, mesh3])
-exploder.setMeshes(meshes)
-
-// Explode
-exploder.explode({
-  mode: 'spiral',        // 'ring' | 'spiral' | 'grid' | 'radial'
-  spacing: 2.5,
-  duration: 1000,
-  lift: 0.6,
-  dimOthers: {
-    enabled: true,
-    opacity: 0.25
-  }
-})
-
-// Restore
-exploder.restore(600)
-
-// Cleanup
-exploder.dispose()
+// 还原
+exploder.restore(600);
 ```
 
----
-
-### Setup: autoSetupCameraAndLight
-
-Automatically setup camera and lighting for a model.
+### 7. 视角快速切换
+提供标准的工程视角切换功能。
 
-**Features:**
-- ✅ Auto-calculate optimal position
-- ✅ Multi-directional lighting
-- ✅ Shadow support
-- ✅ Light intensity adjustment
-
-**Usage:**
 ```typescript
-import { autoSetupCameraAndLight } from '@chocozhang/three-model-render/setup'
-
-const handle = autoSetupCameraAndLight(camera, scene, model, {
-  enableShadows: true,
-  padding: 1.2,
-  shadowMapSize: 2048,
-  renderer
-})
+import { setView } from '@chocozhang/three-model-render';
 
-// Adjust light intensity
-handle.updateLightIntensity(0.8)  // 80% intensity
+// 切换到顶视图
+setView(camera, controls, model, 'top');
 
-// Cleanup
-handle.dispose()
+// 切换到等轴测视图 (ISO)
+setView(camera, controls, model, 'iso');
 ```
 
 ---
 
-## 🎨 Framework Integration
-
-### Vue 3
-```vue
-<script setup lang="ts">
-import { onMounted, onUnmounted } from 'vue'
-import { followModels } from 'three-model-render/camera'
-import { addChildModelLabels } from 'three-model-render/core'
-
-let labelManager: any
-
-onMounted(() => {
-  labelManager = addChildModelLabels(camera, renderer, model, labelsMap, {
-    enableCache: true
-  })
-  
-  followModels(camera, model, {
-    easing: 'easeInOut'
-  })
-})
-
-onUnmounted(() => {
-  labelManager?.dispose()
-})
-</script>
-```
+## 📚 模块总览 (Module Overview)
 
-### React
-```tsx
-import { useEffect } from 'react'
-import { followModels } from '@chocozhang/three-model-render/camera'
-import { addChildModelLabels } from '@chocozhang/three-model-render/core'
-
-function ModelViewer() {
-  useEffect(() => {
-    const labelManager = addChildModelLabels(camera, renderer, model, labelsMap)
-    
-    followModels(camera, model, {
-      easing: 'easeInOut'
-    })
-    
-    return () => labelManager.dispose()
-  }, [])
-  
-  return <div ref={containerRef} />
-}
-```
+### **Core (`/core`)**
+- `initPostProcessing`: 高性能后期处理管理器，内置 OutlinePass。
+- `enableHoverBreath`: 智能呼吸光效，支持性能自适应。
+- `addChildModelLabels`: 3D 标签系统，自动跟随模型运动。
 
----
+### **Camera (`/camera`)**
+- `followModels`: 智能相机跟随与聚焦。
+- `setView`: 预设视角切换 (Top, Front, Iso, etc.)。
 
-## ⚙️ TypeScript Support
+### **Loader (`/loader`)**
+- `loadModelByUrl`: 统一模型加载器，支持多种格式。
+- `BlueSky`: 快速创建天空盒环境。
 
-Full TypeScript support with complete type definitions:
+### **Interaction (`/interaction`)**
+- `createModelClickHandler`: 射线检测点击处理器。
 
-```typescript
-import type {
-  LabelManager,
-  LabelOptions,
-  HoverController,
-  PostProcessingManager,
-  FollowOptions,
-  ExplodeOptions
-} from '@chocozhang/three-model-render'
-```
+### **Effect (`/effect`)**
+- `GroupExploder`: 模型爆炸/拆解动画控制器。
 
----
-
-## 🔧 Advanced Configuration
-
-### tsconfig.json
-```json
-{
-  "compilerOptions": {
-    "lib": ["ES2015", "DOM"],
-    "target": "ES2015",
-    "module": "ESNext"
-  }
-}
-```
+### **Setup (`/setup`)**
+- `autoSetupCameraAndLight`: 一键自动化场景配置大师。
 
 ---
 
-## 📊 Performance
+## 🎨 示例项目
 
-### Optimization Results
-- **CPU Usage**: ⬇️ 55% reduction
-- **Memory Usage**: ⬇️ 33% reduction
-- **Idle Performance**: ⬇️ 80% CPU when inactive
+我们提供了一个完整的、可部署的示例项目，展示了所有功能的集成方式：
 
-### Benchmarks
-| Utility | Before | After | Improvement |
-|---------|--------|-------|-------------|
-| Label Updates | 15% CPU | 6% CPU | ⬇️ 60% |
-| Hover (Idle) | 5% CPU | 1% CPU | ⬇️ 80% |
-| Hover (Active) | 8% CPU | 5% CPU | ⬇️ 37.5% |
-| Memory | 180MB | 120MB | ⬇️ 33% |
+- 👉 **[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 项目
 
 ---
 
-## 📦 Build and Publish
-
-### Build Package
-```bash
-npm run build
-```
-
-### Type Check
-```bash
-npm run type-check
-```
-
-### Publish to Private Registry
-```bash
-npm publish
-```
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).
-
----
-
-## 📄 License
+## 📄 开源协议
 
 MIT © [Danny Zhang]
-
----
-
-## 🔗 Links
-
-- [GitHub Repository](https://github.com/HappyColour/three-model-render)
-- [Issue Tracker](https://github.com/HappyColour/three-model-render/issues)
-- [Three.js](https://threejs.org/)
-
----
-
-## 🙏 Acknowledgments
-
-Built with ❤️ using:
-- [Three.js](https://threejs.org/) - 3D library
-- [TypeScript](https://www.typescriptlang.org/) - Type safety
-- [Rollup](https://rollupjs.org/) - Module bundler