Processing三维场景编辑器PDE：从场景编排到JSON导出的设计实践

PDE这个项目其实是从一个很具体的问题里长出来的——Processing在可视化编程、快速原型和交互艺术领域确实很顺手，但真到了“把一堆三维模型摆进一个场景、调好角度、导出给别的系统用”这一步，你会发现它天生缺一套正经的编辑器。你可以用代码逐行声明每个物体的位置和旋转，但想用鼠标拖拽、实时看到层级关系、像在Unity里一样组织场景结构，Processing原生的开发环境基本帮不上忙。

PDE（Processing D Editor）想做的事，就是把这个缺口补上：在Processing生态里，做一版面向三维场景的轻量编辑器。它不是一个建模工具，也无意跟Blender这类重型软件抢饭碗，它解决的核心问题是“场景编排”——把现成的模型、粒子、光效、地形参数组合进一个统一的三维空间，以可视化的方式维护，然后输出成结构化数据，交给运行时引擎或者业务系统加载。这篇记录会把它的设计思路、核心模块的落地方法、以及我在开发过程中踩过的坑完整写出来，尤其适合两类人看：一类是在Processing里做可视化项目的开发者，另一类是想自己写一个“小Unity”但不想从零造引擎的人。

1. 项目缘起：为什么说Processing缺一个编辑器

1.1 Processing生态的短板

Processing最爽的地方也是它最头疼的地方：一切都能用代码画出来，但一切都要靠代码组织。写一个demo的时候这完全没问题，代码本身就是存档，运行即所见。可一旦场景里有两百个物件、几十种材质、一套复杂的相机路径，用代码维护的体验就会迅速劣化。模型的坐标散落在初始化函数里，材质参数在另一个类里以静态常量存在，粒子系统的发射位置又在配置文件中——出了需求变更，你要在代码里来回穿梭。三维场景编辑器存在的意义，就是把“数据编排”和“渲染表现”分开：编辑器负责管理场景里有什么、摆在哪、怎么动，运行端只关心怎么把这些数据高效画出来。

PDE的定位就是这一层的编辑器。它不替代Processing做渲染，恰恰相反，它把Processing当作一个可嵌入的渲染底子，在上面套上场景管理、层级面板、属性面板、相机控制器和文件序列化体系。

1.2 PDE在场景资源流里的位置

你可以把PDE理解成一条可视化装配线：

• 输入侧：导入外部模型文件（OBJ、STL或SVG化的轮廓），或者直接用内置的图元生成器创建球体、立方体、地形等基础体；
• 编辑侧：用户在工作区以所见即所得的方式摆放对象、调整属性、建立父子层级、设置动画参数；
• 输出侧：整个场景序列化成JSON，网络加载器、数据可视化引擎、甚至另一台机器上的Processing程序都可以消费这份配置。

这条链路里PDE的关键产出不是画面，而是“可移植的场景描述”。这也是它和SketchUp、Blender最大的区别：别人围绕网格编辑做文章，PDE围绕场景编排做文章，建模用外部工具，编辑用PDE，运行时各自负责，中间用定义良好的场景文件衔接。

1.3 技术选型的基本盘

技术选型没有太多悬念。编辑器本身跑在JVM上，开发语言Java 17，渲染层直接用Processing 4.x的P3D渲染器，UI层使用Java Swing作为宿主窗口框架。我知道很多人的第一反应是“Swing太老了”，但这里有一个很现实的理由：Processing的PApplet本质上就是一个AWT/Swing组件，使用Swing做壳可以做到最小程度的桥接损耗，不需要中间再套一层JavaFX的WebView或者第三方原生窗口库。PDE当前版本基于Processing 4.3构建，早期原型在3.5.2上也验证过，只要是P3D渲染模式，核心场景类就能兼容。

2. PDE编辑器整体架构与场景数据模型

2.1 模块边界怎么切

整个编辑器我按“数据模型—渲染视图—编辑交互—序列化”四层来拆。

第一层是SceneModel，也就是所有场景元素的抽象表示。Node是所有元素的基类，下面派生MeshNode（模型/图元）、GroupNode（容器）、CameraNode（相机）、LightNode（灯光）。这层不依赖任何Processing类，只是为了“描述场景”而存在，理论上一套数据模型可以服务多个渲染后端。第二层是RenderView，负责把SceneModel里的数据翻译成Processing的绘制指令，这一层才允许直接调用PVector、PShape、PImage等渲染API。第三层是EditorInteraction，处理鼠标拾取、拖动、框选、层级拖拽，其实就是在Processing画布上叠了事件处理器。第四层是SceneIO，负责JSON的导出和导入。

这么做最大的好处是替换成本极低。如果你想给PDE换一个渲染后端，比如换成JOGL裸写OpenGL，只需重写RenderView层，SceneModel和SceneIO不会被影响。反过来，如果你想出另一种场景文件格式，比如二进制或XML，只动SceneIO即可。

2.2 SceneGraph的关键设计

SceneModel内部是一个典型的场景图（SceneGraph）。根节点永远是唯一的SceneRoot，下面挂各种Node，每个Node有一个parent引用和一个有序children列表。节点数据结构我简化成下面这样：

java复制public abstract class Node {
    private String id;                      // 全局唯一
    private String name;                    // 显示名称
    private Node parent;
    private final List<Node> children = new CopyOnWriteArrayList<>();
    private final Transform transform = new Transform();

    public void addChild(Node child) {
        if (child == this || child.parent != null) return;
        child.parent = this;
        children.add(child);
        markDirty();
    }

    public void removeFromParent() {
        if (parent == null) return;
        parent.children.remove(this);
        parent = null;
        markDirty();
    }
}

public class Transform {
    public PVector position = new PVector();
    public PVector rotation = new PVector();  // 欧拉角，单位度
    public PVector scale = new PVector(1, 1, 1);
}

由于Java没有C#的property机制，Transform里直接用了public字段，这在编辑器内部是可控的，但所有修改都必须在属性面板入口统一完成，改完后调用invalidate通知渲染层更新。

场景图还有一个重要约束：WorldTransform是递归累加的。一个子节点的世界坐标不只看自己的Transform，还要看所有祖先的Transform叠加。为了降低每帧重算的CPU开销，我做了一层脏标记机制（markDirty），只有被标记的子树才会在下一帧重新计算变换矩阵，其余节点直接复用缓存的世界矩阵。这组逻辑在场景树达到几百个节点以后性能优势非常明显。

2.3 场景元素的分类与扩展方式

内置的节点类型分四类，每个类型在属性面板中暴露的参数完全不同：

• 基础几何体（MeshNode）：球体、盒子、圆柱、平面、圆环，带segment精度参数；
• 组合体（MeshNode）：线框版本、UV球版本、法线展示版本；
• 容器（GroupNode）：本身不渲染，只作为层级管理的挂载点，可以给整组做统一位移或旋转；
• 辅助节点（CameraNode/LightNode）：相机节点带视场角参数，灯光节点带漫反射颜色、强度。

为了让PDE可以扩展到“渲染Processing本身不支持的模型”，MeshNode内还预留了一个PShape字段的插槽。导入OBJ模型时，我会用Processing的loadShape方法创建一个PShape对象，把它绑定到MeshNode上。如果你有自定义的几何生成逻辑，也可以绕过内置图元，直接new一个带有PShape的MeshNode塞进场景树。

我还设计了一个极简的组件扩展接口，类似Unity组件的雏形：

java复制public interface SceneBehaviour {
    String typeName();
    void update(Node host, float deltaTime);
    JSONObject toJson();
    void fromJson(JSONObject obj);
}

动画旋转、沿路径巡航这一类周期性行为，都注册成Behaviour挂在Node上，而不是硬编码进渲染循环。

3. 核心功能落地：编辑器的几个硬骨头

3.1 场景树面板与属性面板的联动

编辑器左侧是场景树JTree，右侧是属性面板JPanel，中间是Processing画布。这个界面布局看着简单，真正做起来最难的是“双向联动”——你点击场景树节点时，画布里要能高亮；在画布里选中模型时，场景树要自动滚动到对应节点；属性面板改一个数值，画布要立刻刷新。

PDE里所有选中状态都收敛到一个EditorSelection单例上。它持有当前选中Node的引用，并且是一个可监听对象，任何UI注册为SelectionListener后，在选中态变化时收到回调：

java复制public enum EditorSelection {
    INSTANCE;

    private final List<SelectionListener> listeners = new CopyOnWriteArrayList<>();
    private Node current;

    public void select(Node node) {
        if (this.current == node) return;
        this.current = node;
        fireSelectionChanged();
    }
}

场景树节点和画布拾取到的对象，最终都调用EditorSelection.INSTANCE.select(node)。属性面板监听到回调之后，读取Node的类型并动态反射生成输入框，这样就避免了为每种节点手写一组固定表单。反射会有一些性能开销，但属性面板只在选中变化时重建一次，日常滑动滑块改数值并不会触发反射，可以接受。

在JTree里维护树同步还有一个细节：数据源的children列表来自SceneModel，但JTree有自己的TreeModel接口，两者之间需要桥接。我直接在树的TreeModelListener回调里同步修改SCeneModel，确保每次通过JTree增删节点后，场景世界和UI不会出现双份状态。

3.2 画布拾取与相机控制

三维场景编辑器绕不开一个基础交互：鼠标点哪里，就选中哪个物体。可鼠标点下去返回的是屏幕上的二维坐标，要把它映射到三维世界里去。

PDE的拾取方案没有走“射线与网格求交”的重型路线。P3D是Processing自己的软件/硬件混合渲染器，它不像JOGL那样能直接给renderer一个selection pass。我采用了一个非常实用主义的做法——离屏颜色标识拾取：

1. 为场景里每个可拾取节点分配一个不重复的颜色，颜色直接编码节点id（用24位，最多支持约1600万个节点）；
2. 当鼠标点击时，切换到一个离屏PGraphics，用纯色模式重新绘制一次场景，每个MeshNode都只填充它对应的标识色；
3. 读取鼠标坐标下PGraphics里那个像素的RGB值，反解出节点id，就能拿到节点引用。

这一帧离屏绘制只需要处理“物体自身轮廓”，不需要光照、不需要纹理、不需要阴影，所以实际耗时很小。场景节点数量在五百以内时，绘制拾取帧和普通渲染帧的差异几乎感觉不到。

相机控制这部分，我集成了peasycam库。之所以不用自己写的轨道相机，是因为编辑器开发前期要处理的核心问题太多了，相机的阻尼、惯性、右键平移、左键旋转、滚轮缩放的成熟调参不是一天两天能磨出来的，而peasycam已经把这些手感调得相当自然。PDE里我还在peasycam基础之上加了聚焦功能：选中节点后按F，相机平滑移动到节点附近，视点看向节点的世界坐标包围盒中心。实现方式很简单——拿到节点世界变换和包围盒半径后，把peasycam的lookAt目标设置过去，并把相机距离调到包围盒半径的2.5倍。

3.3 渲染主循环与脏刷新策略

Processing原生提供了draw()循环，每帧都调用一次，原本的用法就是动态画面的逐帧动画。但编辑器场景里绝大部分时间一切静止，每帧全量重新绘制纯属浪费CPU。

PDE的做法是引入“刷新策略标记位”：

• 场景没有任何变化时，停止调用重绘，把帧率压到10以下，画布仅保留上次渲染的buffer；
• 场景结构或节点属性变化时，在事件回调中置dirtyFlag，下一帧进入完整渲染流程；
• 有动画Behaviour运行时，在场景根节点上设置“需要持续刷新”状态，回到逐帧循环。

实际落地是这样的：RenderView线程并不直接调用redraw()，而是通过一个FrameRequestQueue接受外部请求。场景编辑引发的几乎所有操作——鼠标拖动、滑块改动、层级拖拽——都会调用requestRender()。这个模式下PDE在静止场景里的CPU占用可以降到接近零，这对需要长时间开着编辑器调场景参数的使用场景来说非常关键。

P3D模式下 Processing 默认的帧率设置是60，编辑器里我强烈建议不要直接沿用。把renderer的frameRate设为动态值，静止30，动起来60，你的风扇会感激你的。

3.4 导入模型与地形生成

外部模型导入这一块，PDE现在的策略是“能引入就引入，不能引入就留扩展点”。Processing自带loadShape支持OBJ和SVG，但OBJ在材质解析上比较有限，模型文件带mtl或者纹理路径不规范时经常翻车。

为了不被这只拦路虎阻断，我加了一个简单的模型预处理步骤：导入OBJ前，先用代码扫描文件里的mtllib和纹理相对路径，把纹理相对路径全部重写为绝对路径。这是因为Processing在解析OBJ材质时，默认使用的目录是当前sketch目录，一旦工程被打包运行，相对路径就乱了，必须让PShape成功resolve纹理才能正常显示。

地形生成也是内置工具里的一个重要功能。用户可以在属性面板里给特定MeshNode添加一个“地形高度图生成器”Behaviour，然后导入一张灰度图作为heightmap。PDE会读取图片每个像素的灰度值，把灰度值映射为高度偏移：

java复制int w = img.width, h = img.height;
float[][] heightData = new float[w][h];
img.loadPixels();
for (int y = 0; y < h; y++) {
    for (int x = 0; x < w; x++) {
        int c = img.pixels[y * w + x];
        float gray = brightness(c);
        heightData[x][y] = heightScale * gray / 255.0;
    }
}

高度图生成器生成的是TriangleStrip结构的三维网格。在同一个面板上还能调“网格精度”和“高度缩放系数”，每次调完立即重新生成网格并重新绑定到MeshNode，整体延迟必须控制在百毫秒内才算及格。

3.5 把场景保存成一套清晰的文件格式

编辑器最终要对外交付的核心资产是场景文件。PDE的默认存档格式分三个层级：

• 项目级PDEP文件：记录所有关联资源路径、全局设置、存档版本；
• 场景级JSON文件：场景树的完整序列化结果；
• 模型纹理等二进制资源：不内嵌，只保存磁盘相对路径。

JSON里的典型节点序列化结果长这样：

json复制{
  "type": "MeshNode",
  "id": "node_0012",
  "name": "地面",
  "transform": {
    "pos": [0, 0, 0],
    "rot": [0, 0, 0],
    "scale": [20, 1, 20]
  },
  "geometry": {
    "kind": "heightmap",
    "heightmapPath": "textures/terrain_h.png",
    "segments": [64, 64],
    "heightScale": 3.2
  },
  "behaviours": [
    {
      "type": "autoOrbit",
      "speed": 0.6
    }
  ]
}

保存时走递归遍历，从SceneRoot开始DFS，逐节点调用toJson。这个方法的实现里有一个很重要的“防御点”：父节点序列化时，必须把children也包进同一个JSONObject，同时子节点序列化时必须携带它在父节点children里的index。加载时，先按DFS顺序重建所有Node对象并注册进内存HashMap，然后再进行第二遍父子关系建立。

我踩过一次不排序的坑：如果直接按JSON里出现的顺序挨个把addChild，一旦子节点在父节点之前出现，父节点引用就会为null，场景树直接塌掉。所以PDE的JSON格式里我特意要求DFS顺序输出，并校准了父节点必须率先输出、子节点随后输出的顺序约定，加载器遇到违反约定的数据时会报出“场景文件结构错误”而不是神秘崩溃。

4. Processing底座的关键控制点

4.1 PApplet的构造顺序是绕不过去的坎

Processing库写多了会注意到一个问题：在自己的主类里new一个PApplet子类并调用init()，如果在构造函数里访问size、smooth、或者任何与渲染surface相关的属性，都会得到null或者抛出异常。PApplet的生命周期有严格顺序：构造PApplet —> init() —> 触发setup() —> draw()循环。

PDE的宿主容器JPanel在设计上必须顺从这套时序。启动方式是先创建PApplet实例，塞进一个PFrame，然后PFrame启动后台线程调用init()。渲染相关的初始化全部放在setup()里执行，场景模型可以提前在构造函数里建立，但任何需要用到renderer的操作都必须推迟。

4.2 在Swing的容器里嵌入Processing画布

嵌入实操层面，我用了Processing官方推崇的方式：

java复制PApplet p3d = new PDEViewport();
PFrame viewportFrame = new PFrame();
viewportFrame.setLayout(new BorderLayout());
viewportFrame.add(p3d, BorderLayout.CENTER);
p3d.init();

关键点在于PFrame不能使用JFrame，不能直接添加到其他Swing组件里作为子组件。如果编辑器非要在一个大JFrame里通过tab切换多个场景，最稳妥的做法是每个场景对应一个独立的PFrame，切换时隐藏/显示窗口。把多个PApplet塞进同一个JFrame的contentPane里，在Windows和macOS上的重绘表现都不稳定，我测试时出现过灰色残留、焦点丢失等问题。

4.3 内存与GC问题

Processing在P3D模式下会把大量几何数据上传至显存，如果你动态创建并销毁大量PShape而不调用dispose()，内存会像滚雪球一样涨。编辑器操作里最常见的动作是“拖动属性面板的segment精度滑块”，每次调节都会重建PShape。如果不精确释放旧的PShape，JVM进程的堆内存没有明显变化，但显卡内存会被撑爆，表现就是应用自动黑屏或者驱动崩溃。

PDE里我封装了一个ShapeCache，每次重建模块前都会把旧PShape标记为dispose，然后在下一帧渲染前统一清理：

java复制public class ShapeCache {
    private final List<PShape> disposable = new ArrayList<>();

    public PShape createShape() {
        PShape s = new PShape();
        return s;
    }

    public void markForDispose(PShape s) {
        if (s != null) disposable.add(s);
    }

    public void flush() {
        for (PShape s : disposable) s.dispose();
        disposable.clear();
    }
}

flush的调用时机放在渲染帧的最开始，而不是在删除节点的回调里。这个细节能大幅降低卡顿概率，因为删除动作很可能发生在Property面板的UI线程，而你并不想在UI线程上做显卡相关的释放操作。

5. 服务端集成时遇到的那次启动故障

5.1 真实的错误现场

PDE本身是纯桌面工具，但编辑器生成的场景JSON会被集成到一个Spring Boot的服务端项目中，用于在Web端实时发货。某次集成联调时，服务端启动直接报出一个看着很陌生的异常：

bash复制java.lang.IllegalStateException: Error processing condition on com.ngw.common.autoconfigure.xxx.AutoConfiguration

堆栈里提到了“Error processing condition on com.ngw.commo...”这个包名。它的直接意思是Spring Boot在解析某个自动配置类上的条件注解（比如@ConditionalOnClass或@ConditionalOnProperty）时，反射阶段就报错了。这类错误通常不是条件本身写错，而是自动配置类依赖的类不在classpath里、或者类依赖的库版本与Spring Boot版本不兼容。

5.2 定位路径

排查思路分为四条线，每一条都值得记录：

• 第一，用mvn dependency:tree查看com.ngw.common相关模块的依赖树，确认是否引入了两个不同版本的common包，造成字节码层面冲突；
• 第二，开启Spring Boot的debug日志，让框架打印所有自动配置的匹配报告，这里最直观；
• 第三，直接打开报错条件注解指向的AutoConfiguration文件，确认它@ConditionalOnClass里写的类是否真的存在；
• 第四，检查项目里有没有自定义spring.factories或者AutoConfiguration.imports文件，是否把不该自动装配的类纳入管理。

PDE场景JSON集成模块使用的是旧版common包2.x，其中内置了一个基于旧版Spring Boot 2.2编译的自动配置类。而服务端主工程已经升级到Spring Boot 2.7，条件注解解析器版本从5.1迁移到5.3版本后，一些旧的内部API签名发生了变化，导致条件反射解析失败。

5.3 修复与复盘

修复方案本质上是升级依赖，把common包升到与Spring Boot 2.7兼容的3.x版本。但升级后又有另一个问题——common包旧版某个API方法已标记废弃并从新版本移除，PDE场景服务模块里有直接调用的硬编码。所以还要额外做一层适配，把那些废弃调用替换成新版本的API写法。

写完修复后，我又顺手在服务模块里加了一个启动自检过滤器：每次启动时扫描全部自动配置类的@ConditionalOnClass字段，检查依赖的类是否真的在classpath里。如果类缺失，则启动即报出“真实缺失原因”而非继续冒出笼统的IllegalStateException。经过这次教训后，团队里再没人用“Error processing condition”这种报错去网上乱搜了。

这个案例虽然发生在服务端，但根子上仍然是“条件注解处理”与依赖管理的问题。也提醒了PDE的项目约束：任何依赖的引入都必须做版本矩阵验证，不能在开发机“能跑就完事”。

6. 给想做同类编辑器的人几条实话

6.1 别一上来就追求“编辑器通用化”

我见过很多编辑器项目死掉了，不是因为技术实现不了，是上来就要做“通用的三维场景编辑器”，支持MAYA、FBX、GLTF、骨骼动画、粒子系统，结果干了半年还是一堆半成品面板。PDE的项目边界从一开始就非常清楚：服务Processing生态下“中低复杂度的场景编排”，支持的模型格式就OBJ和STL，节点类型就那几个，动画只做参数化行为，不做骨骼绑定。这让整个开发量显著收敛，也让真正有用的功能打磨得更深。没有边界，就没有交付。

6.2 录制操作日志是编辑器的保命绳

三维编辑器的状态依赖太重了——一个误拖动可能让整个场景树错乱，一次误删可能让半小时的调整全盘作废。PDE在中期迭代加入了一个轻量级UndoManager，核心实现就是Command模式：

java复制public interface EditorCommand {
    void execute();
    void undo();
    String description();
}

场景节点增删、属性修改、父子调整都封装为对应的命令类。在模型操作中间件中，每一次鼠标拖拽结束后才push一个完整命令，这么做可以规避按每帧操作压入命令导致撤销栈爆炸。

有一种情况我不建议做历史记录：相机视角操作。如果相机绕了二十分钟回到原位置，中间生成了上千个命令，储存在撤销栈里会无谓消耗内存。PDE的解决办法是给命令类型加tag，相机操作命令根本不进UndoManager，只在特定“视角书签”功能里手动保留快照。

6.3 PDE还能长成什么

到目前版本，PDE已经能稳定完成“从空场景到导出JSON”的全流程。未来的扩展点其实很清晰：一是把导出器做到更通用的glTF格式，这样能直接接入Web端或其他渲染引擎；二是把Behaviour部分独立成一个事件驱动脚本系统，做一个对普通用户更友好的逻辑编辑面板；三是支持局域网协同编辑，让两个PDE实例操作同一个场景文件，实时同步节点变更。

按我个人的开发习惯，下一步最优先做的是glTF导出——它能让PDE从Processing内部的工具变成真正通用的编辑器，适用范围会再大一圈。但无论怎么扩展，PDE的核心哲学不会变：编辑器不是渲染器，它只负责生成结构清晰、可以被任何程序消费的场景数据。能把这一件事做到位，这个项目就已经值得了。