# model-viewer

**Repository Path**: dragonfly_flyover/model-viewer

## Basic Information

- **Project Name**: model-viewer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2026-01-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D 模型查看器

基于 Three.js + React + Ant Design 的 FBX/GLTF 模型浏览器，支持关联数据展示。

**v1.6 重构版**：代码已模块化，App.tsx 从 2354 行精简到 849 行（-64%）。

## 功能特性

### 核心功能
- ✅ **模型加载**：支持 FBX、GLTF、GLB 格式
- ✅ **目录树**：完整层级结构，支持搜索、展开/折叠
- ✅ **高亮定位**：点击节点自动高亮并定位相机
- ✅ **聚焦模式**：选中部件实体显示，其他半透明
- ✅ **关联数据**：展示端子图、元件接线图等关联图纸
- ✅ **截图导出**：一键保存当前视图为 PNG

### 交互控制
- **左键拖拽**：旋转视角（默认模式）
- **中键/右键拖拽**：平移视图
- **滚轮滚动**：缩放远近
- **点击树节点**：聚焦并显示关联数据
- **点击 3D 部件**：高亮并同步目录选中

## 快速开始

```bash
# 进入项目目录
cd app

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build
```

## 项目结构（v1.6 重构后）

```
model-viewer/
├── app/                    # 主应用目录
│   ├── src/
│   │   ├── App.tsx        # 主组件（849行，-64%）
│   │   ├── App.css        # 样式
│   │   ├── config.ts      # 配置
│   │   ├── types/         # 类型定义
│   │   ├── hooks/         # 自定义Hooks（业务逻辑）
│   │   │   ├── useScene.ts
│   │   │   ├── useModelLoader.ts
│   │   │   ├── useSelection.ts
│   │   │   ├── useTreeData.ts
│   │   │   └── useAssociatedData.ts
│   │   └── utils/         # 工具函数
│   │       ├── threeUtils.ts
│   │       ├── csvUtils.ts
│   │       └── treeUtils.ts
│   └── public/
│       ├── model_data/    # 3D 模型文件
│       └── svg_data/      # 关联图纸数据
├── docs/
│   ├── FEATURES.md        # 详细开发文档
│   ├── ARCHITECTURE.md    # 架构说明
│   └── REFACTOR_SUMMARY.md # 重构总结
└── README.md
```

## 关联数据配置

### 关联信息.csv 格式

```csv
模型目录路径,端子图,元件接线图
门线束及背景/左门/左门线束/左门线束_2/左门锁_C14,C14,左门锁
```

- **模型目录路径**：模型节点的完整路径
- **端子图**：文件名（自动拼接路径 `/svg_data/端子图/{name}.svg`）
- **元件接线图**：文件名（自动拼接路径 `/svg_data/元件接线图/{name}.svg`）

### 导出目录路径

点击左侧目录栏的导出按钮，可导出所有模型目录路径为 CSV 模板，用于填充关联数据。

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| React | 19.x | 前端框架 |
| Three.js | 0.182+ | 3D 渲染引擎 |
| Ant Design | 6.x | UI 组件库 |
| papaparse | 5.x | CSV 解析 |
| Vite | 7.x | 构建工具 |

## 快捷键

| 快捷键 | 功能 |
|--------|------|
| F | 聚焦全局 |
| G | 聚焦选中 |
| Ctrl+S | 截图保存 |

## 详细文档

| 文档 | 说明 |
|------|------|
| [docs/FEATURES.md](docs/FEATURES.md) | 完整功能说明、代码结构、开发指南 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 架构设计、模块依赖、数据流图 |
| [docs/REFACTOR_SUMMARY.md](docs/REFACTOR_SUMMARY.md) | v1.6 重构总结、迁移指南 |

## License

MIT