@chocozhang/three-model-render 1.0.1 → 1.0.3

package/README.md

@@ -4,7 +4,9 @@
 
 A high-performance, TypeScript-first toolkit providing 14 optimized utilities for Three.js model visualization and interaction.
 
-[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/HappyColour/three-model-render)
+> 🌟 **[Live Demo: Experience the Power](https://happycolour.github.io/)**
+
+[![Version](https://img.shields.io/badge/version-1.0.2-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/)
 
@@ -21,19 +23,12 @@ A high-performance, TypeScript-first toolkit providing 14 optimized utilities fo
 
 ## 📦 Installation
 
-### Using npm
-```bash
-npm install three-model-render
-```
-
-### Using yarn
-```bash
-yarn add three-model-render
-```
-
-### Using pnpm
 ```bash
-pnpm add three-model-render
+npm install @chocozhang/three-model-render
+# OR
+yarn add @chocozhang/three-model-render
+# OR
+pnpm add @chocozhang/three-model-render
 ```
 
 **Peer Dependencies:**
@@ -43,496 +38,182 @@ npm install three@^0.160.0
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Best Practice Workflow
 
-### Import全量 (Supports Tree-shaking)
-```typescript
-import { followModels, addChildModelLabels, enableHoverBreath } from 'three-model-render'
+Build a professional 3D viewer following our optimized integration pattern. This workflow ensures maximum performance and visual quality.
 
-// Use the utilities
-followModels(camera, model, {
-  easing: 'easeInOut',
-  duration: 1000
-})
-```
+### 1. Core Setup & Model Loading
+Initialize your basic Three.js scene and load your model using our optimized loader.
 
-### Import按需 (Recommended)
 ```typescript
-// Only import what you need
-import { followModels } from 'three-model-render/camera'
-import { addChildModelLabels } from 'three-model-render/core'
-import { enableHoverBreath } from '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
+import { loadModelByUrl } from '@chocozhang/three-model-render';
 
-### Camera Utilities (`/camera`)
-Camera control and animation
+// 1. Basic Three.js Setup
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000);
+const renderer = new THREE.WebGLRenderer();
+const controls = new OrbitControls(camera, renderer.domElement);
 
-- **`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.
-
-**Features:**
-- ✅ Bounding box caching (60% performance boost)
-- ✅ Pause/resume API
-- ✅ Configurable update intervals
-
-**Usage:**
-```typescript
-import { addChildModelLabels } from '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
+// 2. Load Model with Progress
+const model = await loadModelByUrl('path/to/model.glb', {
+    manager: new THREE.LoadingManager(() => console.log('Loaded'))
+});
+scene.add(model);
 ```
 
-**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. Auto-Configuration (Critical Step)
+Automatically position the camera and setup studio-quality lighting based on the model's bounding box.
 
----
-
-### 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 '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.
+import { autoSetupCameraAndLight } from '@chocozhang/three-model-render/setup';
 
-**Features:**
-- ✅ Auto-resize support
-- ✅ Resolution scaling for performance
-- ✅ Complete lifecycle management
-
-**Usage:**
-```typescript
-import { initPostProcessing } from 'three-model-render/core'
-
-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()
+// Automatically calculates optimal camera distance and lighting
+autoSetupCameraAndLight(camera, scene, model);
 ```
 
----
-
-### Camera: followModels
+### 3. Cinematic Entrance
+Create a smooth entry animation to focus on the model.
 
-Smoothly move camera to focus on target objects with easing animations.
-
-**Features:**
-- ✅ Multiple easing functions
-- ✅ Progress callback
-- ✅ Cancelable animations
-
-**Usage:**
 ```typescript
-import { followModels, cancelFollow } from '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 'three-model-render/camera'
+import { followModels, FOLLOW_ANGLES } from '@chocozhang/three-model-render';
 
 followModels(camera, model, {
-  ...FOLLOW_ANGLES.ISOMETRIC  // 45° diagonal view
-})
+    ...FOLLOW_ANGLES.FRONT,
+    duration: 1500,
+    padding: 0.6,
+    controls,
+    easing: 'easeInOut'
+});
 ```
 
----
-
-### Camera: setView
-
-Quick view switching with smooth animations.
+### 4. Post-Processing & Hover Effects
+Enable high-performance post-processing and optimized hover effects (saves 80% CPU when idle).
 
-**Usage:**
 ```typescript
-import { setView, ViewPresets } from 'three-model-render/camera'
-
-// Programmatic view
-await setView(camera, controls, model, 'front', {
-  easing: 'easeInOut',
-  duration: 800
-})
+import { initPostProcessing, enableHoverBreath } from '@chocozhang/three-model-render';
 
-// Using presets
-ViewPresets.isometric(camera, controls, model)
-ViewPresets.top(camera, controls, model)
+// 1. Initialize Post-Processing Manager
+const ppManager = initPostProcessing(renderer, scene, camera, {
+    resolutionScale: 0.8, // Optimize performance
+    edgeStrength: 4,
+    visibleEdgeColor: '#ffee00'
+});
+
+// 2. Enable Smart Hover Effect
+const hoverController = enableHoverBreath({
+    camera,
+    scene,
+    renderer,
+    outlinePass: ppManager.outlinePass,
+    throttleDelay: 16, // 60fps limit
+    minStrength: 2,
+    maxStrength: 8,
+    speed: 3
+});
+
+// IMPORTANT: Add composer to your animation loop
+function animate() {
+    // ...
+    ppManager.composer.render();
+}
 ```
 
-**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.
+### 5. Interaction Handling
+Add intelligent click handling that zooms to parts and triggers actions.
 
-**Features:**
-- ✅ Auto-format detection
-- ✅ DRACO/KTX2 support (GLTF)
-- ✅ Geometry optimization
-- ✅ Texture downscaling
-
-**Usage:**
 ```typescript
-import { loadModelByUrl } from 'three-model-render/loader'
-
-const model = await loadModelByUrl('/path/to/model.fbx', {
-  mergeGeometries: false,
-  maxTextureSize: 2048,      // Downscale large textures
-  useSimpleMaterials: false
-})
-
-scene.add(model)
-```
-
-**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
+import { createModelClickHandler } from '@chocozhang/three-model-render';
+
+const disposeClickHandler = createModelClickHandler(
+    camera, 
+    scene, 
+    renderer, 
+    ppManager.outlinePass, 
+    (object, info) => {
+        console.log('Clicked:', info);
+        
+        // Zoom to clicked part
+        followModels(camera, object, {
+            ...FOLLOW_ANGLES.ISOMETRIC,
+            duration: 1500
+        });
+    }
+);
+```
+
+### 6. Advanced Effects (Explosion)
+Add interactive mesh explosion/disassembly effects.
 
-**Usage:**
 ```typescript
-import { BlueSky } from 'three-model-render/loader'
+import { GroupExploder } from '@chocozhang/three-model-render';
 
 // 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.
-
-**Features:**
-- ✅ Pause/resume API
-- ✅ Bounding box caching
-- ✅ Fade-in animations
-
-**Usage:**
-```typescript
-import { createModelsLabel } from '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()
-```
+const exploder = new GroupExploder(scene, camera, controls);
+exploder.init();
 
----
-
-### Effect: GroupExploder
-
-Model explosion effects with multiple arrangement modes.
-
-**Features:**
-- ✅ 4 explosion modes (ring, spiral, grid, radial)
-- ✅ Smooth animations
-- ✅ Dim other objects
-
-**Usage:**
-```typescript
-import { GroupExploder } from '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)
+// Set Targets
+exploder.setMeshes(targetMeshes);
 
 // Explode
-exploder.explode({
-  mode: 'spiral',        // 'ring' | 'spiral' | 'grid' | 'radial'
-  spacing: 2.5,
-  duration: 1000,
-  lift: 0.6,
-  dimOthers: {
-    enabled: true,
-    opacity: 0.25
-  }
-})
+exploder.explode({ 
+    mode: 'grid', 
+    spacing: 2.8, 
+    dimOthers: { enabled: true, opacity: 0.1 } 
+});
 
 // Restore
-exploder.restore(600)
-
-// Cleanup
-exploder.dispose()
+exploder.restore(600);
 ```
 
----
-
-### Setup: autoSetupCameraAndLight
-
-Automatically setup camera and lighting for a model.
+### 7. View Control
+Easily switch between standard views.
 
-**Features:**
-- ✅ Auto-calculate optimal position
-- ✅ Multi-directional lighting
-- ✅ Shadow support
-- ✅ Light intensity adjustment
-
-**Usage:**
 ```typescript
-import { autoSetupCameraAndLight } from '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
-
-// Cleanup
-handle.dispose()
+// Switch to Top View
+setView(camera, controls, model, 'top');
+// Switch to Isometric
+setView(camera, controls, model, 'iso');
 ```
 
 ---
 
-## 🎨 Framework Integration
+## 📚 Module Overview
 
-### 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'
+### **Core (`/core`)**
+- `initPostProcessing`: Performance-optimized post-processing manager.
+- `enableHoverBreath`: Idle-aware hover effects.
+- `addChildModelLabels`: 3D labeling system.
 
-let labelManager: any
+### **Camera (`/camera`)**
+- `followModels`: Smooth camera transitions.
+- `setView`: Preset view switching (Top, Front, Iso, etc.).
 
-onMounted(() => {
-  labelManager = addChildModelLabels(camera, renderer, model, labelsMap, {
-    enableCache: true
-  })
-  
-  followModels(camera, model, {
-    easing: 'easeInOut'
-  })
-})
+### **Loader (`/loader`)**
+- `loadModelByUrl`: Robust model loader (GLTF, FBX, OBJ).
+- `BlueSky`: Environment map manager.
 
-onUnmounted(() => {
-  labelManager?.dispose()
-})
-</script>
-```
+### **Interaction (`/interaction`)**
+- `createModelClickHandler`: Raycasting click handler.
 
-### React
-```tsx
-import { useEffect } from 'react'
-import { followModels } from 'three-model-render/camera'
-import { addChildModelLabels } from '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} />
-}
-```
+### **Effect (`/effect`)**
+- `GroupExploder`: Mesh disassembly animations.
 
----
+### **Setup (`/setup`)**
+- `autoSetupCameraAndLight`: Instant scene configuration.
 
-## ⚙️ TypeScript Support
+---
 
-Full TypeScript support with complete type definitions:
+## 🎨 HTML/Vue 3 Example
 
-```typescript
-import type {
-  LabelManager,
-  LabelOptions,
-  HoverController,
-  PostProcessingManager,
-  FollowOptions,
-  ExplodeOptions
-} from 'three-model-render'
-```
+For a complete, deployable HTML/Vue 3 example demonstrating all these features, check `examples/html-best-practice/`.
 
 ---
 
-## 🔧 Advanced Configuration
+## ⚙️ TypeScript Support
 
-### tsconfig.json
+Full TypeScript definitions included. Ensure your `tsconfig.json` matches:
 ```json
 {
   "compilerOptions": {
@@ -545,65 +226,6 @@ import type {
 
 ---
 
-## 📊 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% |
-
----
-
-## 📦 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@chocozhang/three-model-render",
-    "version": "1.0.1",
+    "version": "1.0.3",
     "type": "module",
     "description": "Professional Three.js model visualization and interaction toolkit with 14 high-performance utilities",
     "main": "./dist/index.js",
@@ -68,11 +68,11 @@
         "typescript",
         "performance"
     ],
-    "author": "Your Name <your.email@example.com>",
+    "author": "Danny Zhang <happyelement.danny@gmail.com>",
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/your-username/three-model-render.git"
+        "url": "https://github.com/HappyColour/three-model-render.git"
     },
     "publishConfig": {
         "access": "public"