# 业级 3D 可视化编辑器与代码生成器

**Repository Path**: Hchujian/three3D

## Basic Information

- **Project Name**: 业级 3D 可视化编辑器与代码生成器
- **Description**: # 🏭 Industrial 3D Visualization Generator (Pro)

### 工业级 3D 可视化编辑器与代码生成器

> **专注于制造业、物联网 (IoT) 与数字孪生的 3D 模型交付方案**
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-12-07
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏭 Industrial 3D Visualization Generator (Pro v2.5)

### 工业级 3D 可视化编辑器与代码生成器 (全自动优化版)

> **专注于超大规模工业装配体、物联网 (IoT) 与数字孪生的 3D 模型高保真交付方案**

---

## 📖 项目简介

这是一个**高性能、模块化**的 3D 模型编辑器与代码生成器。它不仅解决了传统 3D 开发中“调整难、集成麻烦”的问题，更针对**超大规模工业模型（数万零件）**提供了极致的端侧渲染优化能力。

在最新的 **v2.5（架构重解耦版）** 中，系统通过将核心逻辑抽离为自定义 Hooks 和 Utils，实现了极高的代码稳定性与扩展性。同时，通过“核级过滤器”和“全局自动实例化”技术，能够让 7 万零件级别的超级装配体在网页端流畅运行。

**核心竞争优势：**
- 🛡️ **智能稳定性**：独创“少数派保护”逻辑，确保单个小模型 100% 完整显示，绝不误删。
- ☢️ **核级过滤**：自动识别、隐藏模型中的巨型占位符、辅助框和不可见参考对象。
- 🧩 **模块化架构**：核心逻辑高度解耦，易于定制与二次开发。
- ✅ **一键交付**：导出 HTML 或 Vue 2 组件，效果与编辑器 **100% 像素级一致**。

---

## ✨ 核心特性 (Features)

### 1. ☢️ 核级过滤器 (Nuclear Filter Engine)
智能识别识别工业模型导出过程中产生的垃圾节点：
- **关键词查杀**：识别 `bbox`, `dummy`, `helper` 等。
- **体积/顶点数启发式识别**：自动剔除占满全场景但无实际模型的透明容器。
- **安全模式防护**：零件数 < 10 时自动挂起过滤器，保护单体结构。

### 4. 🎨 材质与视觉系统
- **Clay (白模) 模式**：一键切换高质感工业草图风。
- **材质隔离池 (Material Pool)**：局部化材质管理，防止模型切换时的状态穿插与内存泄漏。
- **精确光照控制**：支持方位角、仰角、强度的可视化配置。

---

## 🏗️ 架构概览 (Modular Architecture)

项目在 v2.5 版本进行了深度手术，实现了核心渲染与业务逻辑的彻底剥离：

```mermaid
graph TD
    App[App.jsx 布局控制] --> useModelLoader[useModelLoader 资源加载]
    App --> useSceneControls[useSceneControls 全局配置]
    App --> usePerformanceDiagnostics[usePerformanceDiagnostics 诊断优化]
    
    App --> Model[Model.jsx 渲染核心]
    Model --> useModelMaterials[useModelMaterials 材质处理]
    Model --> MaterialPool[MaterialPool 材质池管理]
    Model --> LODManager[LODManager 细节管理]
    Model --> sceneFilter[sceneFilter 智能识别]
    Model --> VisualBox[VisualBox 高亮反馈]
```

| 组件/模块 | 功能说明 | 状态 |
| :--- | :--- | :--- |
| **Model.jsx** | 瘦身至 220 行，仅负责声明式组件挂载 | 🚀 极简 |
| **useModelMaterials** | 整合 Clay 模式、配置同步与资源回收逻辑 | 🔄 闭环 |
| **sceneFilter** | 纯函数查杀引擎，支持不同规模场景的启发式决策 | 🧠 智能 |
| **MaterialPool** | 局部引用计数池，单模型彻底隔离，杜绝渲染残留 | 🛡️ 稳定 |

---

## 🚀 快速开始

### 1. 环境准备
```bash
node -v # >= 18.0.0
npm install
```

### 2. 启动开发
```bash
npm run dev
```

### 3. 工业流程示例
1. **拖入模型**：将 FBX/GLB 拖入。
2. **性能体检**：如果是超大模型，系统会主动弹窗建议“执行全局实例化”。
3. **视觉微调**：调整材质、隐藏不必要零件、设置视角。
4. **代码导出**：生成 Vue 2 组件，直接放入若依/Admin 后台。

---

## 📂 项目结构

```bash
src/
├── components/
│   ├── Three/
│   │   ├── Model.jsx           # 极致简化的渲染入口
│   │   ├── Environments.jsx    # 光照预设
│   │   └── VisualBox.jsx       # 选中高亮反馈组件
├── hooks/
│   ├── useModelMaterials.js    # 材质管理黑盒
│   ├── useSceneControls.js     # Leva 状态同步
│   └── usePerformanceDiagnostics.js # 性能诊断与报告
├── utils/
│   ├── meshMerger.js           # 核心合并引擎
│   ├── MaterialPool.js         # 资源池定义
│   ├── LODManager.js           # 细节等级管理
│   └── sceneFilter.js          # 查杀引擎算法
```

---

## 📝 更新日志

### v2.5.0 (2026-01-09)
- **Architecture Refactoring**: 彻底重构，代码量缩减 70%，逻辑高内聚低耦合。
- **Memory Optimization**: 实现跨模型材质与 LOD 的硬隔离。
- **Small Scene Protection**: 增加少数派保护逻辑，解决单模型加载异常。
- **Stability**: 修复了重复加载同名模型不刷新的 Bug。

---

## 📄 许可证

MIT License. Designed with ❤️ for Industrial Excellence. 
Designed by **Antigravity** for **Industrial Performance**.