|
1 | | -# Processing 3D Scene Editor |
2 | | - |
3 | | -> **A Native Processing 3D Editor Paradigm.** |
4 | | -
|
5 | | - |
6 | | - |
7 | | - |
8 | | -## 引言 |
9 | | -本项目是一个基于 **Processing (Java P3D)** 创意编程框架搭建的**三维场景编辑器基本范式**。 |
10 | | -受行业标杆 Unreal Engine 5 (UE5) 和 Unity 的启发，本项目抛弃了简单的参数调控，纯手工从零构建了一套底层基于**纯数学与射线检测 (Raycasting)** 的高级交互式 3D 编辑系统。 |
11 | | - |
12 | | -它不仅向开发者展示了如何在 Processing 内打通 2D 骨架代码与 3D 深度渲染的壁垒，更为所有想要在 Processing 中开发复杂 3D 交互、游戏关卡编辑器、或者是三维数据可视化工具的创作者，提供了一套开箱即用的**极简范式源码**。 |
13 | | - |
14 | | -## 核心功能特性 (Features) |
15 | | - |
16 | | -本项目实现并提炼了商业 3D 引擎最核心的几大基础功能模块： |
17 | | - |
18 | | -### 1. 引擎级摄像机漫游系统 (Advanced Camera Controls) |
19 | | -完美复刻了 UE5 / Unity 的视口基础交互手感，包含两种极致分离的操作模式： |
20 | | -- **第一人称自由飞行 (Fly Mode)**：按住 `右键` 激活。此时系统会锁定并隐藏系统光标（无需担心激烈的鼠标滑动移出屏幕界限），您可以使用 `W/A/S/D` 进行三维空间的前后左右平滑穿梭，并配合鼠标进行 FPS 视角的自由旋转。 |
21 | | -- **环绕检视模式 (Orbit Mode)**：按住键盘 `Alt` 键激活。配合 `左键` 环绕旋转物体 (Orbit)、`中键` 上下左右平移 (Pan) 以及 `右键/滚轮` 剧烈缩放推拉 (Zoom)，可完美对某一个中心焦点进行 360° 无死角观察与审核。 |
22 | | - |
23 | | -### 2. 纯底层数学级射线拾取交互 (Precise Raycast Object Picking) |
24 | | -- 彻底抛弃了低效且繁琐的颜色拾取（Color Picking - 1.0时代技术）或臃肿的物理引擎库。 |
25 | | -- 结合底层反投影矩阵 (`Inverse Projection & View Matrix`) 解析屏幕 2D 坐标到 3D 齐次空间的数学变换，在后台隐式构建出精准的屏幕点击反向实体射线 (`Hit Ray`)。 |
26 | | -- 支持 3D 场景内 `实体 (Entity)` 以及 `全向操作轴 (Gizmo)` 的无限空间内 AABB 三维包围盒与解析平面的精准点击碰撞判定。 |
27 | | - |
28 | | -### 3. 多模态 3D 操作轴系统 (Multi-state Transform Gizmos) |
29 | | -完全对标 UE5 极致纤细、优雅现代的视觉工业设计，支持四种专业级变换操作模式（在视口中随时通过键盘主键盘区数字键 `1/2/3/4` 无缝热切换）： |
30 | | -- **[1] 翻译偏移 (Translate)**：使用尖锐的圆锥箭头 (Cones) 提供 X/Y/Z 三轴精准坐标推拉拖拽。 |
31 | | -- **[2] 万向旋转 (Rotate)**：引进了纯动态三维星环结构 (Torus Rings) 提供针对特定数学平面的滚转、俯仰与偏航控制。内置高阶射线-平面交叉检验方程 (`intersectPlane`)。 |
32 | | -- **[3] 等比缩放 (Scale)**：具有方形滑块 (Boxes) 骨架的大比例尺等距缩放机制。 |
33 | | -- **[4] 纯净选择 (Select)**：隐藏物理控制轴，方便进行物体选中及环境沉浸观察。 |
34 | | -> 🌟 *彩蛋特性*：操作轴内部深度融合了专业 3D 软件必备的 **定比距离逆向缩放** (Constant Screen Size Magic) 特性，无论镜头推远到几十公里之外，操作轴永远保持在屏幕上的等高像素大小，百分百避免远距离无法点选的操作硬伤！另包含智能鼠标**悬浮颜色高亮 (Hover Hint)** 与**强力防物理遮盖透视**渲染机制 (`DISABLE_DEPTH_TEST`)。 |
35 | | -
|
36 | | -### 4. 强迫症福音：智能网格吸附机制 (Grid Snapping) |
37 | | -- **一步一吸附 [G]**：像专业机械与关卡建模软件一样，场景全局引入了吸附开关（按键盘 `G` 键任意开启/关闭）： |
38 | | - - **拖拉平移时**：参数死死锁定于整 `10` 倍数的空间单元位置。 |
39 | | - - **盘旋旋转时**：按 `15°` 角度分度进行极为干脆舒适的机械锁步步进（极其便于 90度 直角翻转）。 |
40 | | - - **暴力缩放时**：按 `0.5` 的倍率阶梯增长（消除无限极烂尾小数）。 |
41 | | - |
42 | | -### 5. 沉浸式界面、PBR 模拟与专业光照 (Advanced Lighting & UI) |
43 | | -- **极简主义界面 (UI Dash)**：手绘的双栏布局（左侧层级面板 Hierarchy / 右侧变换详情属性 Inspector 面板）。 |
44 | | -- **专业点光源系统 (Dynamic Point Lights)**： |
45 | | - - **交互式布光**：支持在场景中摆放、缩放、并实时修改**灯光强度 (Intensity)** 与 **影响范围 (Range)**。 |
46 | | - - **物理级衰减**：引入 `lightFalloff` 模拟真实场景中的光随距离而减弱的视觉深度。 |
47 | | -- **精准材质控制 (Hex Color Palette)**： |
48 | | - - 支持 **Hex 颜色代码** 精确录入。 |
49 | | - - 内置 **10 色快捷拾色盘**，告别繁琐的随机上色。 |
50 | | -- **实时场景诊断 (Scene Statistics)**：在视口左上方实时监控 **FPS (帧率)**、**物体总数** 以及 **Polygon (多边形面数)**，助您掌控工程性能。 |
51 | | -- **一键沉浸 (UI Toggle)**：按下键盘 `H` 键或 `TAB` 键隐藏 HUD，展示纯净 3D 效果。 |
52 | | - |
53 | | -### 6. 撤销/重做与坐标系切换 (Undo/Redo & Coordinates) |
54 | | -- **落笔无悔 [Ctrl+Z / Ctrl+Y]**：基于命令模式 (Command Pattern) 的撤销重做系统，涵盖位移、层级改变、属性修改等所有核心操作。 |
55 | | -- **自身坐标系变换 [L]**：按下 `L` 键在 **世界坐标 (World)** 与 **自身坐标 (Local)** 间自由切换，配合矩阵级旋转逻辑，确保在任何倾斜角度下都能精准操作。 |
56 | | - |
57 | | -### 7. 数据与场景持久化架构 (Scene Serialization & Save/Load) |
58 | | -- **双向 JSON 状态转换树**：支持处理海量场景对象的层级迭代器写入规则，原生保存了包括组件种类、实体哈希、色彩索引甚至小到浮点量级的变换属性。 |
59 | | -- 与 Windows、MacOS 等不同主流操作系统原生的 `selectInput` 和 `selectOutput` 桥接，利用底下的 **Save/Load Scene** UI 按钮便可进行直通硬盘的存取操作，为后续大工程预留生命力保留端口。 |
60 | | - |
61 | | -### 8. Unity 级专业菜单系统 (Top Menu Navigation) - v0.1.9 |
62 | | -- **标准化顶部菜单栏**：完美复刻 Unity/UE5/Blender 等专业软件的顶部导航体验： |
63 | | - - **File (文件)**：新建场景、读取、保存。 |
64 | | - - **Edit (编辑)**：上下文敏感的撤销/重做、删除选中物体。 |
65 | | - - **Create (创建)**：快速添加立方体、球体、平面、点光源。 |
66 | | - - **Window (窗口)**：实时开关控制台、开关统计数据、一键重置摄像机位置。 |
67 | | -- **动态交互**：支持“悬停即切换”逻辑，操作行云流水。 |
68 | | - |
69 | | -### 9. 极简指令控制台与脚本基础 (Scripting Console) - v0.1.9 |
70 | | -- **原生命令解释器 (Command Interpreter)**：支持通过指令（如 `move Cube 10 0 0`）精准控制物体。 |
71 | | -- **实时执行反馈**：底部控制台提供蓝/红颜色的成功或错误提示，具有极强的工程纠错能力。 |
72 | | -- **引号语义解析**：完美支持带空格的物体名称（如 `color "My Cube" #FF0000`）。 |
73 | | - |
74 | | -### 10. 现代玻璃态拟物 UI (Glassmorphism Aesthetics) - v0.1.9 |
75 | | -- **全屏毛玻璃面板**：左右侧边栏全面升级为半透明磨砂质感，让 3D 场景与 2D UI 产生深度交融。 |
76 | | -- **高性能裁剪 (Viewport Clipping)**：基于 `clip()` 指令实现的大纲视图，确保成百上千个物体在滚动时始终精准限制在 UI 方框内，无任何溢出。 |
77 | | -- **智能文字截断**：长名称物体自动以 `...` 省略号显示，保持界面整洁。 |
78 | | - |
79 | | -## 运行与编译环境 (How to Run) |
80 | | -1. 确保您的电脑上安装了 [Processing 4](https://processing.org/download) （实测亦兼带低版本容错）。 |
81 | | -2. 使用 Processing IDE 完整打开项目的 `p3deditor.pde` 父入口。 |
82 | | -3. 点击左上角的 **Run (播放)** 按钮。 |
83 | | -- **环境依赖须知**：**无需配置任何额外的第三方 Libraries 库！** 这或许是本项目纯粹的极大亮点：不论代码核心数学库，还是 AWT 底层鼠键锁死劫持系统，亦或复杂的深度检测逻辑，无所不用其极地只通过 Processing 的随身原生 Java SDK 和核心架构进行封装与解耦驱动。 |
| 1 | +# P3DE (Processing 3D Editor) |
| 2 | + |
| 3 | +> **极致原生 · 高度集成 · 零门槛创作** |
| 4 | +> |
| 5 | +> *A light-weight, modular 3D content creation engine & editor built on the Processing P3D environment.* |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## 1. 项目愿景与技术操守 (Core Philosophy) |
| 14 | + |
| 15 | +P3DE 旨在证明在 **Processing** 这一极简的 Java 艺术编程框架下，依然可以构建出具备工业级交互体验、高保真渲染及可视化逻辑编辑能力的闭环工具链。 |
| 16 | + |
| 17 | +### 🛡️ “原生态”构建一切 (Native Everything) |
| 18 | +本项目最核心的技术底线是：**全过程未引用任何第三方插件或外部 Jar 包库**（如 ControlP5, PeasyCam, Rhino 等）。 |
| 19 | +- **自研 Gizmo 系统**：基于纯向量数学与射线检测 (Raycasting) 实现。 |
| 20 | +- **原生 UI 渲染**：利用 Processing 基本绘图指令逐像素绘制所有界面。 |
| 21 | +- **零依赖脚本引擎 (P3DES)**：自建异步执行与变量插值系统。 |
| 22 | +- **原生 PBR 着色器**：直接在 GLSL 层级编写 Cook-Torrance BRDF 数学模型。 |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## 2. 核心功能特性 (Feature Map) |
| 27 | + |
| 28 | +### 🎮 3D 核心与交互驱动 |
| 29 | +- **专业级 Gizmo 操纵器**：支持平移、旋转、缩放。具备世界/局部坐标系实时切换（`L` 键）与 10 单位整格吸附（`G` 键）。 |
| 30 | +- **层级管理树 (Hierarchy)**：支持无限深度的父子连子变换与右键上下文操作。 |
| 31 | +- **撤回重做 (Undo/Redo)**：基于命令模式构建，覆盖所有核心编辑操作。 |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +### ✨ 物理级高保真渲染 (PBR Pipeline) |
| 36 | +- **GGX Cook-Torrance BRDF**：精准模拟金属度与粗糙度。 |
| 37 | +- **IBL (Image Based Lighting)**：支持 360 度环境图加载，提供真实的全球照明氛围。 |
| 38 | +- **材质属性面板**：集成捡色器与实时纹理通道控制。 |
| 39 | + |
| 40 | +### 🧠 视觉逻辑蓝图 (Visual Logic Blueprint - VLB) |
| 41 | +- **双模所有权**：蓝图可挂载于“实体”或“关卡”，实现对象逻辑与全局控制。 |
| 42 | +- **转译引擎**：通过 DFS 算法将非线性节点流转译为可执行的 P3DES 指令，支持热重载 (Hot-Reload)。 |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +### 🐚 脚本引擎与终端 (Terminal) |
| 47 | +- **P3DEC (Direct Execution)**：专业级指令控制台。 |
| 48 | +- **P3DES (The Script Brain)**：轻量级异步脚本语言，支持 `wait` 等非阻塞指令。 |
| 49 | +- **初始化流**：支持 `init.p3dec` 自动化批处理。 |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +## 3. 运行指南 (Getting Started) |
| 56 | + |
| 57 | +1. **环境要求**：确保安装了 [Processing 4](https://processing.org/download) 或更高版本。 |
| 58 | +2. **启动**：克隆本仓库，在 Processing IDE 中打开 `p3deditor/p3deditor.pde`。 |
| 59 | +3. **零依赖运行**：无需安装任何库，点击 **Run** 即可进入编辑器。 |
| 60 | + |
| 61 | +### ⌨️ 部分核心快捷键 |
| 62 | +- `1` / `2` / `3` / `4`：选择 / 位移 / 旋转 / 缩放。 |
| 63 | +- `L`：世界/局部坐标空间切换。 |
| 64 | +- `G`：开启网格吸附。 |
| 65 | +- `Tab`：隐藏/显示所有 UI。 |
| 66 | +- `` ` `` (反引号)：呼出/关闭控制台终端。 |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## 4. 合作与致谢 (Credits) |
| 71 | + |
| 72 | +本项目的诞生得益于 **SharpEye** 与 **Antigravity (Google AI Coding Agent)** 的深度协同： |
| 73 | +- **SharpEye**：产品愿景、UX 交互设计与顶层蓝图。 |
| 74 | +- **Antigravity**：核心架构设计、数学算法固化与工程实现。 |
| 75 | + |
| 76 | +P3DE 证明了在 AI 辅助编程下，开发者可以以最小的代价定制化具备极高复杂度的专业创作工具。 |
| 77 | + |
| 78 | +--- |
| 79 | + |
| 80 | +### 🌐 详情查阅 (Deep Dives) |
| 81 | +- [P3DE (Processing 3D Editor) 三维场景编辑器 · 软件白皮书 · 基于 v0.4.8](https://www.cnblogs.com/sharpeye/p/19766415) |
84 | 82 |
|
85 | 83 | --- |
86 | | -> 🚀 *本“轻量化编辑器底层基石范式”最初目的是为您日后开发更为复杂的创意交互式编程与三维宇宙规则创造实验铺垫地基，非常欢迎将其 Clone 或 Fork 到您的个人名下进行二次暴力拆解大改！* |
| 84 | +**P3DE 的征程才刚刚开始。** 在原生态的土壤里，通过对每一行底层代码的极致雕琢，终能开出艺术之花。 |
0 commit comments