Multi-Agent Intelligent Rendering Pipeline for 3D Visualization Production
English | 中文
一句话： 50+ 相机的批渲染配置从 4 小时压缩到 15 分钟，材质通道一键出图，V-Ray 跨版本零人工适配。
| 痛点 | 传统方式 | CPM 方案 | 提升 |
|---|---|---|---|
| 多相机渲染预设 | 逐相机手动切换参数，4-6h | 一键预设快照 + 批量编排 | 90%+ |
| 材质 ID 通道 | 手动替换材质，2h+/场景 | 递归遍历 + 自动着色渲染 | 95%+ |
| V-Ray 大版本迁移 | 1-2 周人工排查适配 | 版本嗅探 + 属性路径自适配 | 85%+ |
| 渲染误配返工 | 15%-20% 返工率 | 原子快照 + 事务恢复零污染 | → 0% |
┌─────────────────────────────────────────────────────────────┐
│ CameraPresetManager v2.0 │
│ 智能渲染管线编排引擎 │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│ ConfigAgent│ StateAgent │ CoreAgent │ BatchRenderAgent │
│ 配置持久化 │ 场景快照 │ 预设调度 │ 批渲染管线 │
│ 原子写入 │ 事务恢复 │ 版本嗅探 │ 异常续渲 │
│ INI CRUD │ Dual Restore│ 长链推理 │ 熔断 + 负载感知 │
├─────────────┴─────────────┴─────────────┴──────────────────┤
│ MtlChannel Agent │
│ 材质通道渲染子系统 │
│ 递归遍历 · 环检测 · 属性修改 · 双快照恢复 │
├────────────────────────────────────────────────────────────┤
│ UI Agent · Rollout 编排 │
│ 事件驱动 · 动态生成 · 实时状态可视化 │
├────────────────────────────────────────────────────────────┤
│ Dependency Injection Bus (setModules) │
│ 依赖注入 · 松耦合 · 热替换 │
└────────────────────────────────────────────────────────────┘
| Agent | 职责 | 关键能力 |
|---|---|---|
| ConfigAgent | 配置持久化 | INI CRUD、原子写入（临时文件→重命名）、版本快照、幂等策略 |
| StateAgent | 场景状态管理 | 原子化快照（层/环境/分辨率/渲染参数）、Dual Restore 双重回滚 |
| CoreAgent | 预设调度中心 | CRUD 编排、V-Ray 版本嗅探、自适应参数注入、长链推理 |
| BatchRenderAgent | 批渲染管线 | 多相机串行/并行编排、异常续渲、超时熔断、负载感知调度 |
| MtlChannel Agent | 材质通道渲染 | 递归材质树遍历、环检测、属性修改着色、Photoshop 选区图输出 |
| UI Agent | 交互编排层 | Rollout 动态生成、事件聚合、渲染状态实时可视化 |
Agent 间协作： 通过 setModules() 依赖注入协议实现松耦合，任何 Module 可独立热替换。事件驱动的消息总线协调状态流转——CoreAgent 嗅探到 V-Ray 6 时，自动触发适配层属性路径重映射，联动 BatchRenderAgent 调整渲染元素注册策略。
CameraPresetManager/
├── CameraPresetManager.ms # 🚀 入口 - 模块加载 + 依赖注入编排
├── CameraPresetManager_Config.ms # ⚙️ 配置持久化 Agent
├── CameraPresetManager_State.ms # 📸 场景状态快照 Agent
├── CameraPresetManager_Core.ms # 🧠 预设调度中心 Agent
├── CameraPresetManager_BatchRender.ms# 🎬 批渲染管线 Agent
├── CameraPresetManager_MtlChannel.ms # 🎨 材质通道渲染 Agent
├── CameraPresetManager_UI.ms # 🖥️ 交互编排 Agent
├── tests/ # 🧪 三层闭环测试体系
│ ├── RunAutoTest.ms # 测试启动器
│ ├── AutoTest_MtlChannel.ms # 材质通道自动化测试
│ ├── CLI_AutoTest.ms # CLI 端到端测试
│ └── test_*.ms # 单元/集成诊断脚本 (15+)
├── diagnosis/ # 🔍 V-Ray 6 诊断工具集
└── _test_output/ # 📊 测试渲染输出
- 3ds Max 2023+ (支持 2020-2025)
- V-Ray 6.0+ (Hotfix 1 已验证)
- 支持中文 / 英文界面 自动适配
-- 方式 1：MAXScript Listener 中执行
fileIn "CameraPresetManager/CameraPresetManager.ms"
-- 方式 2：直接拖拽 CameraPresetManager.ms 到 3ds Max 视口-- 1. 创建当前相机的渲染预设
cpm_createPreset()
-- 2. 一键切换到指定预设
cpm_applyPreset "Camera01_4K"
-- 3. 批量渲染所有预设（无人值守）
cpm_startBatchRender()
-- 4. 渲染材质通道图（Photoshop 选区用）
cpm_renderMaterialChannel()所有渲染操作遵循 Save → Modify → Render → Restore 事务模式：
local savedParams = storeParams() -- 原子快照
try (
applyChanges() -- 修改场景
render outputFile:outFile vfb:false -- 执行渲染
) catch (
logError (getCurrentException()) -- 异常记录
)
restoreParams savedParams -- 强制恢复（无论成败）| 层级 | 快照内容 | 恢复时机 |
|---|---|---|
| 材质层 | 所有材质属性（颜色/自发光/透明度/贴图） | 渲染完成后强制恢复 |
| 渲染层 | V-Ray 全量参数（输出/降噪/GI/帧缓冲） | 渲染完成后强制恢复 |
即使渲染进程崩溃，双重快照确保场景零污染。
递归遍历材质树时，内置 visited 数组防止循环引用导致无限递归：
fn traverseMaterial mtl visited = (
if (findItem visited mtl) > 0 do return ()
append visited mtl
-- 安全处理...
)CPM 通过 版本嗅探 + 长链推理 自动处理 V-Ray 跨版本差异：
| 适配项 | V-Ray 5 → 6 变更 | CPM 自适应策略 |
|---|---|---|
| 输出属性 | output_* → output_1_* |
hasProperty 探测，优先 output_1_* 降级 output_* |
| 降噪器 | 内嵌参数 → Render Element | 自动切换到 RenderElementMgr 禁用 |
| GI/Options | V_Ray_settings.* → vr.* |
直接访问 renderers.current，跳过嵌套 |
| 中文本地化 | VRayLightMtl → VRay_灯光材质 |
中英文类名双匹配 |
零人工干预，跨版本迁移从 1-2 周缩短至 1-2 天。
| 层级 | 工具 | 覆盖范围 | 执行速度 |
|---|---|---|---|
| L1 AST 语法校验 | Node.js + maxscript-lexer | 全模块静态分析 | 200ms |
| L2 CLI 功能测试 | 3dsmaxbatch 无头模式 | 端到端渲染验证 | 分钟级 |
| L3 GUI 集成测试 | MAXScript Listener 内联 | 场景级回归 | 分钟级 |
# L1: 语法检测（无需 3ds Max 许可证）
node _test/js-tests/syntax_check.js
# L2: CLI 自动化测试
_test/cli-tests/run_test.bat
# L3: 在 3ds Max GUI 中
filein "CameraPresetManager/tests/RunAutoTest.ms"| 指标 | 数据 |
|---|---|
| 核心代码 | 4,100+ 行 MaxScript |
| 测试代码 | 3,400+ 行 (15+ 测试脚本) |
| 模块数量 | 7 个 Agent 模块 |
| 支持相机数 | 100+ 无人值守批量渲染 |
| 材质类型覆盖 | VRayMtl / VRayLightMtl / VRayOverrideMtl / VRayBlendMtl / VRayWrapperMtl / MultiMaterial / Standard / Physical / RaySwitch / 程序贴图 |
| 配置格式 | INI（原子写入，防文件损坏） |
| 语言适配 | 中文 / 英文 3ds Max 自动识别 |
- 零污染场景文件 — 配置完全外置到 INI，不修改 .max 文件
- 事务性操作 — 每次渲染 = 快照 + 修改 + 渲染 + 恢复，保证场景完整性
- 版本自适应 — 运行时嗅探 V-Ray 版本，自动选择兼容路径
- 原子写入 — 配置文件通过临时文件→重命名，防止断电/崩溃导致文件损坏
- 依赖注入 — 模块间通过
setModules()松耦合，支持热替换
项目还包含面向 3ds Max 日常生产的独立工具脚本：
| 工具 | 功能 |
|---|---|
| 材质重命名 v4.0 | 批量材质命名规范化 |
| 贴图压缩 | 智能贴图文件压缩 |
| 贴图查看器 v3.2 | 材质贴图可视化检查 |
| 一键收尾 v1.1 | 场景交付前自动化清理 |
| 批量重命名 | 对象批量命名 |
| 挤出 UVW | UVW 坐标挤出工具 |
| 清理嵌入脚本 | 清理场景内嵌脚本残留 |
- Fork 本仓库
- 创建特性分支：
git checkout -b feature/amazing-feature - 提交变更：
git commit -m 'Add amazing feature' - 推送分支：
git push origin feature/amazing-feature - 创建 Pull Request
提交前请确保 L1 语法检测通过：
node _test/js-tests/syntax_check.jsBuilt with ❤️ for 3D visualization artists · Powered by MaxScript + V-Ray 6