# three-texture

**Repository Path**: seelingzheng/three-texture

## Basic Information

- **Project Name**: three-texture
- **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-07-18
- **Last Updated**: 2025-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Three.js 材质切换演示

这是一个基于 Vue3 + Three.js + dat.GUI 的3D材质切换演示项目。

## 功能特性

- 🎨 **多种材质类型**: 支持 MeshBasicMaterial、MeshLambertMaterial、MeshPhongMaterial、MeshStandardMaterial、MeshPhysicalMaterial
- 🔍 **智能文件扫描**: 自动扫描本地文件夹，支持多格式纹理和模型，具备高级过滤和搜索功能
- 📁 **文件上传功能**: 支持上传自定义纹理图片和3D模型文件
- 🎯 **实时属性调整**: 通过GUI面板实时调整材质属性，包括颜色、金属度、粗糙度、透明度等
- 🔧 **几何体切换**: 支持多种几何体类型（立方体、球体、圆柱体、圆环、圆锥）
- 🏗️ **自定义模型**: 支持加载GLTF、GLB、OBJ、FBX等格式的3D模型
- 💡 **光照控制**: 可调整环境光和方向光的强度和位置
- 🎮 **交互式界面**: 现代化的GUI控制面板，操作简单直观
- 📱 **响应式设计**: 支持窗口大小调整

## 技术栈

- **Vue 3**: 现代化的前端框架
- **Three.js**: 强大的3D图形库
- **dat.GUI**: 轻量级的调试GUI库
- **Vite**: 快速的构建工具

## 安装和运行

1. 安装依赖：
```bash
npm install
```

2. 启动开发服务器：
```bash
npm run dev
```

3. 构建生产版本：
```bash
npm run build
```

## 📖 使用方法

### 基础操作
1. **材质设置**: 在右侧GUI面板选择材质类型和调整属性
2. **纹理管理**: 
   - 启用/禁用纹理
   - 从自动扫描的文件中选择纹理
   - 调整纹理重复和偏移参数
3. **模型加载**: 
   - 选择使用自定义模型
   - 从扫描到的模型文件中选择
   - 或使用内置几何体

### 文件管理功能
1. **自动扫描**: 应用启动时自动扫描 `public/textures` 和 `public/models` 文件夹
2. **手动刷新**: 点击"刷新文件列表"按钮重新扫描所有文件
3. **文件过滤**: 
   - 使用纹理过滤器按格式筛选 (SVG/光栅图像)
   - 使用模型过滤器按格式筛选 (GLTF/OBJ/FBX)
4. **文件上传**: 
   - 点击"上传纹理"或"上传模型"按钮
   - 选择本地文件进行上传和预览

### 高级功能
- **实时预览**: 所有参数调整都会实时反映在3D场景中
- **性能优化**: 文件缓存和并行加载提高响应速度
- **错误处理**: 文件加载失败时自动回退到默认选项
- **统计信息**: 控制台显示文件扫描统计和详细信息

## 材质类型说明

- **MeshBasicMaterial**: 基础材质，不受光照影响
- **MeshLambertMaterial**: Lambert材质，具有漫反射效果
- **MeshPhongMaterial**: Phong材质，支持镜面反射
- **MeshStandardMaterial**: 标准PBR材质，物理真实感渲染
- **MeshPhysicalMaterial**: 物理材质，最高级的PBR材质

## 项目结构

```
three-texture/
├── src/
│   ├── App.vue          # 主组件
│   └── main.js          # 入口文件
├── index.html           # HTML模板
├── package.json         # 项目配置
├── vite.config.js       # Vite配置
└── README.md           # 项目说明
```

## 🏗️ 项目架构

### 📁 目录结构
```
src/
├── config/           # 配置文件
│   └── constants.js  # 常量和配置
├── utils/            # 工具类
│   ├── fileScanner.js      # 文件扫描器
│   ├── MaterialManager.js  # 材质管理器
│   ├── ModelManager.js     # 模型管理器
│   ├── LightingManager.js  # 光照管理器
│   ├── GUIManager.js       # GUI管理器
│   ├── PerformanceMonitor.js # 性能监控器
│   └── Logger.js           # 日志和错误处理
├── App.vue           # 主应用组件
└── main.js          # 应用入口
```

### 🔧 核心工具类

#### 📄 FileScanner
- 自动扫描文件夹中的纹理和模型文件
- 支持多种文件格式和类型过滤
- 缓存机制提高性能

#### 🎨 MaterialManager
- 统一管理Three.js材质
- 纹理加载和缓存
- 材质属性动态更新

#### 🎮 ModelManager
- 3D模型加载和管理
- 支持GLTF、OBJ、FBX等格式
- 模型预处理和优化

#### 💡 LightingManager
- 场景光照管理
- 动态光照调整
- 阴影配置

#### 🎛️ GUIManager
- 用户界面管理
- 控件动态更新
- 事件处理

#### 📊 PerformanceMonitor
- 实时性能监控
- FPS和内存使用统计
- 函数执行时间测量

#### 📝 Logger
- 统一日志管理
- 错误捕获和处理
- 日志级别控制

## 🚀 代码质量特性

### ✅ 最佳实践
- **模块化设计**: 功能分离，职责单一
- **错误处理**: 完善的错误捕获和恢复机制
- **性能优化**: 缓存、懒加载、资源管理
- **类型安全**: 参数验证和类型检查
- **可维护性**: 清晰的代码结构和文档

### 🔒 安全性
- 文件路径验证
- 输入参数校验
- 资源访问控制
- 错误信息过滤

### 📈 性能优化
- 文件缓存机制
- 并行加载
- 资源复用
- 内存管理

## 🛠️ 开发工具和工作流

### 📋 代码质量工具
- **ESLint**: 代码静态分析和错误检查
- **Prettier**: 代码格式化工具
- **TypeScript**: 类型检查和智能提示
- **EditorConfig**: 统一编辑器配置

### 🚀 可用脚本
```bash
# 开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview

# 代码检查和修复
npm run lint
npm run lint:check

# 代码格式化
npm run format
npm run format:check

# 类型检查
npm run type-check

# 清理缓存
npm run clean

# 构建分析
npm run analyze
```

### 🔧 开发环境配置

#### VS Code 推荐扩展
- ESLint
- Prettier
- Vetur (Vue 支持)
- TypeScript
- Path Intellisense
- Auto Rename Tag

#### 配置文件说明
- `.gitignore`: Git 忽略文件配置
- `.eslintrc.json`: ESLint 规则配置
- `.prettierrc.json`: Prettier 格式化配置
- `tsconfig.json`: TypeScript 配置
- `.editorconfig`: 编辑器统一配置
- `three-texture.code-workspace`: VS Code 工作区配置

### 🔄 CI/CD 流程
- **自动化测试**: 推送代码时自动运行 lint、格式检查、类型检查
- **多版本测试**: 支持 Node.js 16.x, 18.x, 20.x
- **自动部署**: main 分支自动部署到 GitHub Pages

### 📝 提交规范
建议使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
```
feat: 添加新功能
fix: 修复bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建工具或辅助工具的变动
```

该项目展示了如何在Vue3中集成Three.js，实现3D场景的创建、材质的动态切换以及属性的实时调整。代码结构清晰，注释详细，适合学习和二次开发。