nan
7dec3b7ca4
- Implemented `cutout_depth_surface.py` for face separation and connected thickness calculations for depth surface assets. - Created `cutout_depth_surface_layout.py` to arrange nodes for staggered calculation branches in depth surface processing. - Authored `geometry_layouts.py` to define layouts for various geometry assets, including image cutouts and depth planes. - Introduced `node_layout.py` for shared presentation rules, facilitating node arrangement and validation in geometry-node layouts.
98 lines
6.5 KiB
Markdown
98 lines
6.5 KiB
Markdown
# AnyImage 项目规范
|
||
|
||
## 总则
|
||
|
||
**不管是代码还是文档，遵循「少就是多」的原则，以好理解为首要要求**
|
||
|
||
- 说明性内容以中文为主，专有名词和约定俗成的表达可使用英文
|
||
- 修改代码、依赖或执行方式后，
|
||
- 不保留旧路径、转发函数、兼容层或胶水代码
|
||
- 仅过测试，不改同步改文档，不构建文档、产物
|
||
- 优先选择依赖少、直接、易验证的实现
|
||
- 复用来自 `common` 的函数，避免重复造轮子
|
||
- 确保文件名/文件夹名和内容边界一致
|
||
|
||
## 查询文档
|
||
|
||
下列是重要文档
|
||
|
||
- [总览](docs/internals/index.md)：内部实现的总揽
|
||
- [程序架构](docs/internals/architecture.md)：进程边界、职责与调用主链
|
||
- [Operator 索引](docs/internals/operators/index.md)：Operator 实现功能和对应源码
|
||
- [节点资产](docs/internals/node-assets.md)：节点组的构建与验证（节点组不在运行时新建）
|
||
|
||
## 常见命令
|
||
|
||
```bash
|
||
# 安装或同步开发依赖
|
||
uv sync
|
||
|
||
# 本地 BlendJob wheel 内容变化后刷新锁文件
|
||
uv lock --refresh
|
||
|
||
# 运行全部测试
|
||
uv run pytest
|
||
|
||
# 构建 Windows、macOS、Linux 扩展包到 dist/
|
||
uv run pack
|
||
|
||
# 构建并验证 Blender 节点资产
|
||
uv run build_node
|
||
|
||
# 准备、校验并同步 ONNX 模型到 R2
|
||
uv run sync_models
|
||
```
|
||
|
||
## 命名规范
|
||
|
||
- 变量、函数、Docstring 必须使用英文；同一概念在代码和文档中使用统一表达
|
||
- 函数的动作前缀应表达产物边界：`generate_*` 表示 AI 生成。`build_*` 表示代码层构建。`create_*` 表示 Blender 内创建
|
||
- 名称应说明业务职责，并与用户概念、公开协议和界面术语保持一致；不要使用脱离上下文后无法判断用途的宽泛名称
|
||
- 文件和目录名应表达稳定的业务分类和模块职责，不直接沿用函数名，也不按临时执行步骤命名
|
||
- 集合层使用复数，单项分类使用单数
|
||
|
||
- Operator Class 使用动宾结构，如 `ConvertToDepthPlane`、`RemoveImageBackground`
|
||
- Menu、Panel、AddonPreferences、PropertyGroup 分别使用实际类型后缀，如 `AnyImageImageMenu`、`ServerPanel`、`AnyImagePreferences`、`AnyImageSettings`
|
||
- `bl_idname` 使用 `anyimage` 项目前缀：
|
||
- Operator 如 `anyimage.convert_to_depth_plane`
|
||
- Menu 如 `ANYIMAGE_MT_image_context`
|
||
- Panel 如 `ANYIMAGE_PT_server`
|
||
- 公共 Property 如 `Scene.anyimage_settings`
|
||
- Operator 自身 Property 不加项目前缀，使用业务名称，如 `input_path`、`process_res`、`resolution_level`
|
||
- 扩展包名使用 Manifest 中的真实名称、版本和平台，例如 `AnyImage.v0.11.2.windows-x64.zip`；节点组名称沿用资产中的 `O DA3 Depth Plane`、`O MoGe2 Surface` 等既有名称
|
||
|
||
## 文档规范
|
||
|
||
- `README.md` 面向用户，不在其中堆叠内部细节。实现原理放入 `docs/internals` 对应主题
|
||
- 文档只正面描述当前主题的职责与实现，不记录无关模块、未采用路径、历史差异、边界辩解、“不做什么”的排除性信息。
|
||
- 实现原理用流程图替代文字，Mermaid 默认使用从上到下
|
||
|
||
## Blender 开发规范
|
||
|
||
- 扩展级设置及其读取入口统一放在 `preferences.py`；使用 `addon_preferences()` 读取
|
||
- Job 参数使用可序列化的普通字典；Blender 数据只能在主线程的 Operator 响应阶段读写
|
||
- 新增或修改 Blender 类型时同步检查 `src/anyimage/__init__.py` 的注册与逆序注销，并补充对应测试
|
||
- 依赖版本、wheel 或 Manifest 改变时同步检查 `pyproject.toml`、`uv.lock`、`blender_manifest.toml` 和打包测试
|
||
- `server/` 是 blendjob 后端代码，无法引用来自它上级文件夹的内容。共享函数需单独实现。
|
||
|
||
## Blender 节点组规范
|
||
|
||
- 节点组统一存入 `assets/O_AnyImage.blend`，运行时按名称加载（`load_node_group(group_name)`）
|
||
- 节点组通过[节点资产](docs/internals/node-assets.md)说明构建，禁止运行时调用 `bpy.data.node_groups.new()` 新建
|
||
- 节点组变更须同步构建脚本、验证、测试和节点资产文档
|
||
- 将节点组当作程序函数：先确定传递几何的主轴，主轴从左到右连续排列。主轴可适当宽松，支线内部尽量紧凑；同一目的的节点距离应明显小于不同部分之间的距离，用留白表达用途分组
|
||
- Join Geometry、Menu Switch、Combine XYZ 等节点前，承担同级输入的独立分支末端尽量排成一列、输出端对齐；XYZ 三轴也属于同级输入，菜单分支按输入顺序上下排列。共享上游留在公共位置，不为末端对齐搬动整条计算链
|
||
- 属性计算作为并行支线，就近汇入主轴，不因计算节点多而延长主轴。同一目的的计算聚在主轴同一侧，独立用途可在两侧错落展开；不追求两侧均衡，长短和距离随内容变化，优先利用附近空位
|
||
- 长算式适当横排，不强迫所有支线竖排或等长。支线可以长过对应的主链步骤，几何输入也不必是最左侧节点
|
||
- Group Input 按区域重复放置，Named Attribute 等字段入口就近读取；隐藏所有未使用输出，避免从远处拉线
|
||
- 跨区域暂存值用 Store Named Attribute 写入 `o_*` 命名空间，按用途分配前缀并明确 FACE、CORNER、POINT 域和存取时机；末尾用一个 Wildcard 模式的 Remove Named Attribute 清理该前缀，例如 `o_depth_*`，保留用户属性和 UV
|
||
- Capture Attribute 适合局部字段固定；若属性连线跨越多个步骤，改为命名属性，让计算分支独立展开
|
||
- 支线确需从主轴向左回接时直接连接，不加 Reroute 绕线，允许这些连线交叉；前向旁路只在确实更清楚时使用少量 Reroute。节点本体仍不得重叠或被遮挡
|
||
- 保留节点默认 `name` 和标题，不用 `label` 覆盖，不用 String 节点注解。Frame 仅用于确有包裹语义的区域
|
||
- 全接线的简单数学运算可折叠；需要阅读的常数、运算域和模式保持可见
|
||
- Repeat、Simulation、For Each Geometry Element 等成对节点，确保位置正确，没有遮挡其他节点
|
||
- 修改器 Geometry Nodes 的输入 socket 默认使用 `SINGLE`
|
||
- socket `subtype` 按业务语义设置：长度用 `DISTANCE`，`0–1` 比例用 `FACTOR`，`0–100` 用 `PERCENTAGE`；无对应范围语义时保留默认
|
||
- 接口或布局变更须验证 socket 顺序与结构、未使用输出隐藏及几何求值；纯布局变更比较运算、默认值和实际连接，确认功能不变
|
||
- 在 Blender 节点编辑器按实际绘制尺寸检查总览和局部步骤，确认主轴、支线长度、节点间距及配对区域清楚；坐标检查不能代替视觉检查
|