# 3dModeldisplay-gitee

**Repository Path**: zysfnlpc/3d-modeldisplay

## Basic Information

- **Project Name**: 3dModeldisplay-gitee
- **Description**: 3D模型可视化平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-26
- **Last Updated**: 2025-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 高级3D模型可视化与管理平台

这是一个支持多种3D模型格式的高级可视化与管理平台，使用Node.js、Express、HTML、CSS和JavaScript开发。系统支持高斯点云和标准3D模型格式，提供直观的模型展示界面和完整的管理功能，适合各类3D模型展示需求。

## 核心功能特点

### 多格式模型支持
- **标准格式**: GLB/GLTF, OBJ, STL, FBX, SOG（预留）
- **高斯点云**: PLY, SPLAT, KSPLAT, SPZ

### 模型展示页面 (`/public/index.html`)


### 模型管理页面 (`/admin/index.html`)


## 技术实现

### 前端技术
- **Three.js**: 核心3D渲染引擎
- **GaussianSplats3D**: 高斯点云渲染库
- **OrbitControls**: 高级相机控制系统
- **自适应加载系统**: 根据设备性能优化渲染

### 后端技术
- **Node.js + Express**: 服务器与API实现
- **文件系统管理**: 高效处理3D模型文件
- **JSON数据存储**: 轻量级持久化解决方案

### 代码架构
- **模块化设计**: 分离模型加载、控制和渲染逻辑
- **优雅的错误处理**: 多层防御性编程确保稳定性
- **渐进式加载**: 支持大型模型的流式加载

## 目录结构

```
/
├── server.js                 # 服务器主文件
├── package.json              # 项目依赖配置
├── data/                     # 数据存储目录
│   └── models.json           # 模型元数据
├── public/                   # 前端展示相关文件
│   ├── index.html            # 模型展示页面
│   ├── css/                  # 样式文件
│   │   └── style.css         # 主样式文件
│   ├── js/                   # JavaScript文件
│   │   ├── main.js           # 主控制逻辑
│   │   ├── plyViewer.js      # PLY高斯点云处理模块
│   │   ├── standardViewer.js # 标准格式模型处理模块
│   │   ├── plyControlsExtension.js # PLY模型控制扩展
│   │   └── lib/              # 第三方库
│   │       └── gaussian-splats-3d.module.js # 高斯点云渲染库
│   ├── models/               # 模型文件存储
│   └── images/               # 缩略图和贴图
│
├── admin/                    # 管理页面相关文件
│   ├── index.html            # 模型管理界面
│   ├── css/                  # 管理界面样式
│   └── js/                   # 管理逻辑
│
└── README.md                 # 项目文档
```

## 安装与部署

### 本地开发环境
1. 克隆仓库
   ```
   git clone https://github.com/yourusername/3dModeldisplay.git
   cd 3dModeldisplay
   ```

2. 安装依赖
   ```
   npm install
   ```

3. 启动开发服务器
   ```
   npm run dev
   ```

4. 访问应用
   - 模型展示页面: `http://localhost:3000/index.html`
   - 管理页面: `http://localhost:3000/admin/index.html`

### 生产环境部署
1. 服务器准备
   ```
   npm install
   npm run build  # 如果有构建步骤
   ```

2. 使用PM2运行
   ```
   npm install -g pm2
   pm2 start server.js --name "3d-model-display"
   pm2 save
   ```

3. Nginx配置（可选）
   ```nginx
   server {
       listen 80;
       server_name your-domain.com;
       
       location / {
           proxy_pass http://localhost:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_cache_bypass $http_upgrade;
       }
   }
   ```

## 贡献指南
欢迎贡献代码、报告问题或提出新功能建议。请通过以下步骤参与贡献：

1. Fork项目仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建Pull Request

##### 待优化问题
## 模型
1. 不同模型居中展示问题
2. 尺寸不同模型缩放展示问题
3. 模型倒置问题
4. 控制台报错（代码逻辑错误导致）
5. .......
## 页面
1. 页面布局、内容、操作、字体等优化
2. 页面其他功能添加（根据需求适时开发）
3. 页面图片、模型缩略图优化
4. ......

##### 未来展望

## 数据管理优化
1. 将当前的JSON文件存储替换为MongoDB或MySQL数据库
2. 增强模型标签、分类和属性管理，支持更复杂的模型组织和检索
3. 实现基于角色的访问控制，区分管理员、编辑者和查看者权限

## 技术架构升级
1. 使用React或Vue重构前端，实现更高效的组件化开发
2. 建立RESTful API或GraphQL接口，提供更灵活的数据访问
3. 使用Docker封装应用，简化部署和扩展流程
4.  优化大型模型文件的分发，提高全球访问速度

## 用户体验增强
1. **模型中增加文字、标注和交互点**: 支持在模型上添加注释和可交互的热点，增强沉浸式体验（示例群里的演示视频）
2. **AR/VR支持**: 添加增强现实和虚拟现实查看模式，提供更丰富的空间体验
3. **协同查看与标注**: 支持多用户同时查看和标注同一模型，促进团队协作
4. **版本控制**: 实现模型的版本历史管理，追踪修改和变更

## 性能优化
1. **渐进式网格加载**: 实现基于LOD (Level of Detail) 的模型动态加载
2. **WebAssembly加速**: 使用WebAssembly优化计算密集型任务
3. **WebGL优化**: 深度优化渲染管线，提高复杂场景的帧率
4. **移动设备性能优化**: 针对不同移动设备特性自动调整渲染参数
######  注意事项 
#### 请提前安装并熟悉 Node.js、git 基本操作
#### 有任何问题、建议请联系本文作者