@v2x-three/core/README.md

V2X Three.js 核心库 - 开放式的Three.js工具集，支持React和Vue项目

# @v2x-three/core

🚗 V2X Three.js 核心库 - 专为道路可视化和车联网应用设计的开放式 Three.js 工具集

## ✨ 特性

- 🎯 **开箱即用** - 快速设置 Three.js 场景和基础功能
- 🎮 **多种相机控制** - 轨道控制器和第一人称控制器
- 🌍 **环境管理** - HDR 环境贴图加载和管理
- ⚡ **粒子加载效果** - 炫酷的3D粒子加载动画
- 📱 **响应式设计** - 自动适配不同屏幕尺寸
- 🎨 **UI 控件** - 内置性能监控和全屏控制
- 📦 **TypeScript** - 完整的 TypeScript 类型支持
- ⚛️ **框架兼容** - 支持 React、Vue 等现代前端框架

## 📦 安装

```bash
npm install @v2x-three/core three
# 或者
yarn add @v2x-three/core three
```

## 🚀 快速开始

### 🎯 零配置启动（v0.2.0 新功能）

```typescript
import { quickSetup } from '@v2x-three/core';

// 只需要一个容器DOM元素，内置完整的加载界面和错误处理
const container = document.getElementById('my-3d-viewer');

try {
  const result = await quickSetup({
    container: container
    // 所有其他配置都是可选的！内置加载界面会自动显示
  });
  
  // 场景自动启动，加载动画会自动隐藏
  console.log('✅ 3D场景创建成功！');
} catch (error) {
  console.error('❌ 场景创建失败:', error);
  // 错误信息会自动显示在界面上，支持重试按钮
}
```

### 🎨 自定义加载界面

```typescript
const result = await quickSetup({
  container: document.getElementById('my-3d-viewer'),
  
  models: [
    { url: '/path/to/model.glb', name: 'My Model' }
  ],
  
  // 自定义内置加载界面
  loadingUI: {
    theme: 'green',           // 'blue', 'green', 'purple', 'orange', 'dark'
    title: '我的3D应用',
    subtitle: '正在加载精彩内容...',
    logo: '🚗',
    showRoadAnimation: true,
    customTips: [
      '💡 提示：加载完成后可以拖拽旋转视角',
      '🔍 提示：使用滚轮进行缩放'
    ],
    onRetry: () => {
      console.log('用户点击了重试');
      // 实现重试逻辑
    }
  },
  
  // 监听详细加载进度
  onProgress: (progress) => {
    console.log(`${progress.stage}: ${progress.message} - ${progress.overallProgress}%`);
  }
});
```

### 基础使用（传统方式）

```typescript
import { quickSetup, createBasicLighting, createGround } from '@v2x-three/core';

// 快速设置场景
const { scene, camera, renderer, animate } = await quickSetup({
  container: document.getElementById('app'),
  backgroundColor: 0x87ceeb,
  shadowMap: true,
  antialias: true
});

// 添加基础光照
createBasicLighting(scene);

// 添加地面
const ground = createGround(100, 0x666666);
scene.add(ground);

// 开始动画循环
animate();
```

### React 中使用

```tsx
import React, { useEffect, useRef } from 'react';
import { quickSetup, createBasicLighting, ModelLoader } from '@v2x-three/core';

const ThreeScene: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    // 初始化场景
    const { scene, camera, renderer, animate, destroy } = quickSetup({
      container: containerRef.current,
      enableUI: true,
      enableCameraControls: true
    });

    // 添加光照
    createBasicLighting(scene);

    // 加载模型
    const loader = new ModelLoader();
    loader.loadGLTF('/models/road.glb')
      .then(gltf => {
        scene.add(gltf.scene);
      })
      .catch(console.error);

    // 开始渲染
    animate();

    // 清理函数
    return () => {
      destroy();
    };
  }, []);

  return (
    <div 
      ref={containerRef} 
      style={{ width: '100%', height: '100vh' }}
    />
  );
};

export default ThreeScene;
```

### Vue 中使用

```vue
<template>
  <div ref="container" style="width: 100%; height: 100vh;"></div>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { quickSetup, createBasicLighting, ParticleLoader } from '@v2x-three/core';

const container = ref<HTMLDivElement>();
let cleanup: (() => void) | null = null;

onMounted(() => {
  if (!container.value) return;

  // 显示粒子加载效果
  const particleLoader = new ParticleLoader(container.value);
  particleLoader.show();

  // 模拟加载完成
  setTimeout(() => {
    particleLoader.complete(() => {
      // 初始化主场景
      const { scene, camera, renderer, animate, destroy } = quickSetup({
        container: container.value!,
        enableUI: true,
        enableCameraControls: true
      });

      createBasicLighting(scene);
      animate();

      cleanup = destroy;
    });
  }, 3000);
});

onUnmounted(() => {
  if (cleanup) {
    cleanup();
  }
});
</script>
```

## 📚 API 文档

### QuickSetup

快速设置 Three.js 场景的便捷函数。

```typescript
interface QuickSetupConfig {
  container?: HTMLElement;
  enablePerformanceMonitor?: boolean;
  enableUI?: boolean;
  enableCameraControls?: boolean;
  antialias?: boolean;
  alpha?: boolean;
  shadowMap?: boolean;
  tone?: 'none' | 'linear' | 'reinhard' | 'cineon' | 'aces';
}

const result = quickSetup(config?: QuickSetupConfig);
```

### 环境管理器

```typescript
import { EnvironmentManager } from '@v2x-three/core';

const envManager = new EnvironmentManager(scene, renderer);

// 加载HDR环境
await envManager.loadHDREnvironment('/path/to/environment.hdr');

// 设置强度
envManager.setIntensity(1.5);

// 创建渐变天空
envManager.createGradientSky(0x87CEEB, 0xFFE4B5, 2);
```

### 粒子加载器

```typescript
import { ParticleLoader } from '@v2x-three/core';

const loader = new ParticleLoader(containerElement);

// 显示加载动画
loader.show();

// 设置进度
loader.setProgress(0.5);

// 完成加载
loader.complete(() => {
  console.log('加载完成!');
});
```

### 第一人称相机控制

```typescript
import { FPSCameraControls } from '@v2x-three/core';

const fpsControls = new FPSCameraControls(camera, renderer.domElement);

// 启用控制
fpsControls.enable();

// 设置移动速度
fpsControls.setMoveSpeed(10);

// 更新相机（在动画循环中调用）
fpsControls.update(deltaTime);
```

### 模型加载器

```typescript
import { ModelLoader } from '@v2x-three/core';

const loader = new ModelLoader({
  enableDraco: true,
  dracoPath: '/draco/'
});

// 加载GLTF模型
const gltf = await loader.loadGLTF('/models/car.glb', {
  onProgress: (progress) => {
    console.log(`加载进度: ${progress.percentage}%`);
  }
});

scene.add(gltf.scene);
```

## 🛠️ 高级用法

### 自定义渲染循环

```typescript
import { PerformanceMonitor, ResponsiveManager } from '@v2x-three/core';

// 性能监控
const perfMonitor = new PerformanceMonitor({
  targetFPS: 60,
  enableAdaptiveFPS: true
});

// 响应式管理
const responsive = new ResponsiveManager(renderer, camera, {
  enableAutoResize: true,
  maintainAspectRatio: true
});

// 自定义动画循环
function animate() {
  requestAnimationFrame(animate);
  
  const deltaTime = perfMonitor.update();
  
  // 更新控制器
  fpsControls.update(deltaTime);
  
  // 渲染场景
  renderer.render(scene, camera);
  
  // 更新性能信息
  if (uiControls) {
    uiControls.updatePerformanceInfo(
      perfMonitor.getCurrentFPS(),
      renderer.domElement.width,
      renderer.domElement.height,
      renderer.getPixelRatio()
    );
  }
}
```

## 🎯 使用场景

- **车联网可视化** - 道路、车辆、交通流量可视化
- **城市规划** - 3D城市建模和交通仿真
- **游戏开发** - 赛车游戏、驾驶模拟器
- **教育培训** - 交通安全教育、驾驶培训
- **数据可视化** - 交通数据的3D展示

## 📄 许可证

MIT License

## 🤝 贡献

欢迎贡献代码！请先查看贡献指南。

## 🔗 相关链接

- [Three.js 官方文档](https://threejs.org/docs/)
- [WebGL 规范](https://www.khronos.org/webgl/)
- [V2X 标准](https://www.its.dot.gov/v2x/)