nan
2b79a342b0
- Introduced `test_cutout.py` to validate cutout pie menu behavior, image lasso options, and mesh detail calculations. - Added `test_mesh.py` to ensure correct tangent normal rasterization, plane source topology, and depth surface evaluations. - Created `test_mesh_blender.py` to verify material node groups, tangent baking, and local cutout building from Blender images. - Implemented tests for handling alpha regions and ensuring geometry nodes maintain expected behavior.
96 lines
6.8 KiB
Markdown
96 lines
6.8 KiB
Markdown
# AnyImage 开发约定
|
||
|
||
## 总则
|
||
|
||
- 说明性内容（提交说明、文档、注释、Mermaid 等）以中文为主，专有名词和约定俗成的表达可使用英文
|
||
- 动手前先读 `docs/index.md`；程序边界、调用流程和模块职责见 `docs/development.md#程序设计`
|
||
- 修改代码、依赖或执行方式后，同步更新 `README.md` 与对应主题文档，保持文档、测试和实现一致
|
||
- 优先选择依赖少、直接、易验证的实现；保留工作区中与当前任务无关的已有改动
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
.
|
||
├── README.md # 用户入口与快速上手
|
||
├── docs/ # 按功能拆分的设计与开发文档
|
||
├── pack.py # 构建各平台 Blender Extension ZIP
|
||
├── sync_models.py # 准备并同步 ONNX 模型
|
||
├── src/anyimage/
|
||
│ ├── __init__.py # Blender 注册入口
|
||
│ ├── operators.py # Job Operator 与结果导入
|
||
│ ├── panel.py # 3D View 面板
|
||
│ ├── preferences.py # Extension Preferences
|
||
│ ├── properties.py # Scene 设置与动态枚举
|
||
│ ├── job_runtime.py # BlendJob Runtime 配置
|
||
│ ├── blender/ # Depth Plane、Surface 的 Blender 侧实现
|
||
│ ├── server/ # Job、模型、ONNX 推理与输出实现
|
||
│ ├── assets/O_AnyImage.blend # Geometry Nodes 与材质资产
|
||
│ └── wheels/ # 随扩展分发的 BlendJob wheel
|
||
├── tools/ # Blender 资产构建与验证脚本
|
||
└── tests/ # Python 自动化测试
|
||
```
|
||
|
||
文档按主题定位：功能与使用 `docs/features.md`、Depth Plane `docs/depth-plane.md`、Surface `docs/surface.md`、输出格式 `docs/outputs.md`、Job Server `docs/server.md`、程序设计与开发 `docs/development.md`。
|
||
|
||
## 常见命令
|
||
|
||
优先在项目根目录使用 Git Bash；Windows 路径在 Bash 命令中使用正斜杠。
|
||
|
||
```bash
|
||
# 安装或同步开发依赖
|
||
uv sync
|
||
|
||
# 运行全部测试
|
||
uv run pytest
|
||
|
||
# 运行插件注册、Manifest 与打包相关的快速测试
|
||
uv run pytest tests/test_addon.py tests/test_manifest.py tests/test_pack.py -v
|
||
|
||
# 构建 Windows、macOS、Linux 扩展包到 dist/
|
||
uv run python pack.py
|
||
|
||
# 本地 BlendJob wheel 内容变化后刷新锁文件
|
||
uv lock --refresh
|
||
```
|
||
|
||
资产脚本必须由 Blender 执行；具体入口与验证范围见 `docs/development.md#资产构建与验证`，不要用普通 Python 解释器运行。
|
||
|
||
## 命名规范
|
||
|
||
- 变量、函数、Docstring 使用英文；同一概念在代码和文档中使用统一表达
|
||
- Python 类使用大驼峰，不添加项目名前缀。Operator 使用动宾结构，如 `ConvertToDepthPlane`、`RemoveImageBackground`；Menu、Panel、AddonPreferences、PropertyGroup 分别使用实际类型后缀，如 `AnyImageImageMenu`、`ServerPanel`、`AnyImagePreferences`、`AnyImageSettings`
|
||
- `bl_idname` 与挂载到公共 Blender RNA 类型的 Property 使用 `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` 等既有名称
|
||
|
||
## 代码规范
|
||
|
||
- 避免不必要的嵌套，优先使用提前返回和小而明确的函数
|
||
- 只为特殊、非常规或存在兼容性原因的实现写注释，不复述代码本身
|
||
- 删除功能时同时删除无效参数、分支、测试和文档，不保留没有实际消费者的兼容层
|
||
- Blender 侧不载入 AI 依赖：UI、Operator 和结果导入放在 `src/anyimage/` 或 `src/anyimage/blender/`，模型下载、ONNX 推理和输出放在 `src/anyimage/server/`
|
||
- 扩展级设置及其读取入口统一放在 `preferences.py`；使用 `addon_preferences()` 读取，不把 Blender Add-on Preferences 的定位、默认值或路径解析放进专门管理 BlendJob 的 `runtime.py`
|
||
- Job 参数使用可序列化的普通字典；Blender 数据只能在主线程的 Operator 响应阶段读写
|
||
- 新增或修改 Blender 类型时同步检查 `src/anyimage/__init__.py` 的注册与逆序注销，并补充对应测试
|
||
- 依赖版本、wheel 或 Manifest 改变时同步检查 `pyproject.toml`、`uv.lock`、`blender_manifest.toml` 和打包测试
|
||
|
||
## Blender 节点图规范
|
||
|
||
- 不修改节点的 `name`，也不使用 `label` 覆盖节点标题；保留 Blender 为节点类型生成的默认名称和外观，避免读图时无法判断节点原型。用途应通过节点类型、参数、空间布局和必要的少量注释表达
|
||
|
||
- 节点图优先依靠清晰的空间层次表达流程，不用五颜六色的 Frame 做分类；仅在重复区、模拟区等确有包裹语义时少量使用 Frame，并保持配色克制
|
||
- 避免跨越大段节点图的连线；来自 Group Input 的参数可按使用区域放置多个 Group Input，并隐藏未连接的 sockets
|
||
- 主处理链尽量保持为一根从左到右连续可见的几何主线，辅助字段和控制分支放在主线上下两侧，就近汇入消费者
|
||
- 避免交错连线、节点重叠和不必要的回折；新增或重建节点组时检查节点坐标唯一性和主要连线方向
|
||
- Repeat、Simulation、For Each Geometry Element 等具有输入/输出“头尾”的成对结构，应先确定完整包裹范围，再放置内部节点，保证头尾顺序、配对关系和区域边界一眼可辨
|
||
- 作为修改器使用的 Geometry Nodes，除确实需要动态字段或其他结构的接口外，输入 socket 的 structure_type 应设为 SINGLE
|
||
- 为接口 socket 设置符合业务含义的 `subtype`；例如表示 Blender 场景实际长度的浮点输入使用 `DISTANCE`，明确限制为 `0–1` 的比例使用 `FACTOR`，以 `0–100` 表示的百分比使用 `PERCENTAGE`，角度使用对应 subtype。无上限倍率等不符合范围语义的数值保留普通 Float，不为显示形式强套 subtype
|
||
- 调整节点接口或布局后，应补充或更新 Blender 验证，检查 socket 顺序与结构、节点不重叠、Group Input 未使用输出已隐藏，以及几何主线可正常求值
|
||
|
||
## 文档与 Markdown 规范
|
||
|
||
- `README.md` 面向用户；实现原理放入 `docs/` 对应主题，不在 README 堆叠内部细节
|
||
- 不使用 `---` 分隔线；一级标题只在文档开头使用一次
|
||
- Mermaid 节点 ID 使用英文字符，节点显示文本可以使用中文
|
||
- 文档描述当前已实现行为；限制、默认值、命令和文件名必须能从代码或测试中验证
|