@v2x-three/core

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

✨ 特性

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

📦 安装

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

🚀 快速开始

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

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);
  // 错误信息会自动显示在界面上，支持重试按钮
}

🎨 自定义加载界面

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}%`);
  }
});

基础使用（传统方式）

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 中使用

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 中使用

<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 场景的便捷函数。

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);

环境管理器

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);

粒子加载器

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

const loader = new ParticleLoader(containerElement);

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

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

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

第一人称相机控制

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

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

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

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

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

模型加载器

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);

🛠️ 高级用法

自定义渲染循环

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 官方文档
• WebGL 规范
• V2X 标准