# Hyper3dViewer

**Repository Path**: zhenwenhe/hyper3d-viewer

## Basic Information

- **Project Name**: Hyper3dViewer
- **Description**: 3D Viewer 
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D Model Viewer

基于 **Three.js + Electron + Vue 3 + Vite** 构建的可扩展三维模型查看器。

## 功能特性

- **多格式支持**: GLTF/GLB, OBJ, FBX, STL
- **高级查看**: 轨道控制、缩放、平移、预设视角（顶/前/右）
- **材质编辑**: 实时调整颜色、粗糙度、金属度、透明度
- **光照控制**: 环境光、平行光参数实时调节
- **动画播放**: 支持 GLTF/FBX 内嵌动画，速度可调
- **测量工具**: 点击模型表面两点，自动计算距离
- **截图导出**: 一键保存当前视口画面
- **显示切换**: 线框模式、网格、坐标轴
- **拖拽加载**: 直接将文件拖入窗口即可加载
- **插件扩展**: 基于 BasePlugin 架构，轻松添加新功能

## 快速开始

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
# 纯 Web 开发（无 Electron）
npm run dev

# Electron + Web 联合开发
npm run electron:dev
```

### 构建打包

```bash
# 仅构建 Web 版
npm run build

# 构建 Electron 应用
npm run electron:build
```

## 项目结构

```
3d-model-viewer/
├── electron/
│   ├── main.ts          # Electron 主进程
│   └── preload.ts       # 预加载脚本（IPC 桥接）
├── src/
│   ├── main.ts          # Vue 入口
│   ├── App.vue          # 根组件（布局 + 工具栏）
│   ├── env.d.ts         # TypeScript 声明
│   ├── core/
│   │   ├── SceneManager.ts   # 三维场景核心管理器
│   │   └── ModelLoader.ts    # 统一模型加载器
│   ├── components/
│   │   ├── Viewer.vue           # 3D 视口组件
│   │   ├── ModelTree.vue        # 模型层级树
│   │   ├── MaterialEditor.vue   # 材质编辑器
│   │   ├── LightingPanel.vue    # 光照控制面板
│   │   ├── AnimationPanel.vue   # 动画播放面板
│   │   └── MeasureTool.vue      # 测量工具面板
│   ├── plugins/
│   │   ├── BasePlugin.ts        # 插件基类
│   │   ├── MeasurementPlugin.ts # 测量插件
│   │   ├── AnimationPlugin.ts   # 动画插件
│   │   ├── AnnotationPlugin.ts  # 标注插件（示例）
│   │   └── index.ts             # 插件注册中心
│   └── store/
│       └── index.ts             # 响应式状态管理
├── index.html
├── package.json
├── vite.config.ts
└── tsconfig.json
```

## 插件开发指南

本项目的核心设计目标之一是**可扩展性**。通过插件系统，你可以在不修改核心代码的前提下添加新功能。

### 创建新插件

1. 在 `src/plugins/` 目录下创建新文件：

```typescript
import { BasePlugin } from './BasePlugin'
import type { SceneManager } from '@/core/SceneManager'

export class MyCustomPlugin extends BasePlugin {
  readonly name = 'my-plugin'
  readonly description = '我的自定义插件'

  protected onInit(): void {
    // this.scene      - 访问 THREE.Scene
    // this.camera     - 访问 THREE.PerspectiveCamera
    // this.renderer   - 访问 THREE.WebGLRenderer
    // this.sceneManager - 访问 SceneManager 完整 API

    // 注册帧回调（每帧调用）
    this.sceneManager!.addAnimationCallback((delta) => {
      // 每帧逻辑...
    })
  }

  dispose(): void {
    // 清理资源
  }
}
```

2. 在 `src/plugins/index.ts` 中导出：

```typescript
export { MyCustomPlugin } from './MyCustomPlugin'
```

3. 在 `Viewer.vue` 的 `onMounted` 中注册：

```typescript
sceneManager.registerPlugin(new MyCustomPlugin())
```

### 插件可用的 API

| 属性/方法 | 说明 |
|-----------|------|
| `this.scene` | THREE.Scene 实例 |
| `this.camera` | 透视相机 |
| `this.renderer` | WebGL 渲染器 |
| `this.sceneManager.getModelGroup()` | 获取当前加载的模型 |
| `this.sceneManager.addAnimationCallback(cb)` | 注册帧回调 |
| `this.sceneManager.removeAnimationCallback(cb)` | 移除帧回调 |
| `this.sceneManager.takeScreenshot()` | 截图 |
| `this.sceneManager.focusOnModel(obj)` | 聚焦到指定对象 |

## 技术栈

- **Three.js** r170 — 三维渲染引擎
- **Vue 3** — UI 框架（Composition API）
- **Electron** — 桌面应用壳
- **Vite** — 构建工具
- **TypeScript** — 类型安全