Add tools and tests for AnyImage model management and documentation
- Implement sync_models.py for preparing and uploading ONNX artifacts. - Create build_node.py for building and validating Blender scripts. - Add docs.py for building and previewing documentation with Mike or MkDocs. - Introduce model_exports.py for exporting PyTorch models to ONNX format. - Develop pack.py for packaging the project with dependencies for different platforms. - Add test_sync_models.py to validate sync_models functionality. - Add test_tool_commands.py to ensure repository tools have correct command scripts. - Initialize tools package with __init__.py.
This commit is contained in:
79
README.md
79
README.md
@@ -1,75 +1,12 @@
|
||||
# AnyImage
|
||||
|
||||
AnyImage 是一款 Blender Extension，用于把图片带入可编辑的 2.5D 工作流：粘贴和清理图片、创建普通 Plane 或 Depth Plane、从套索生成 Cutout Shape，并通过独立 AI Environment 去除背景或进行 4× 高清放大。
|
||||
把图片里的空间感带进 Blender。
|
||||
|
||||
完整说明从[文档首页](docs/index.md)开始；首次使用请阅读[安装与首次配置](docs/getting-started/installation.md)和[五分钟上手](docs/getting-started/quick-start.md)。
|
||||
AnyImage 是一款 Blender 扩展，可以粘贴和编辑图片、创建普通 Plane 或 Depth Plane、从局部选区生成 Cutout Shape，并在独立 AI Environment 中完成去背景与高清放大。
|
||||
|
||||
## 主要功能
|
||||
|
||||
- 在 3D View、Node Editor 与绘画模式中用 `Ctrl+V`（macOS 为 `Cmd+V`）粘贴并 Pack 剪贴板图片
|
||||
- 将 Image Empty 转换为带 `O Mesh Plane` Geometry Nodes 的普通 Plane
|
||||
- 使用 MoGe-2 将静态图转换为可调 Depth Plane
|
||||
- 用 Cutout 套索在图片可见 Alpha 内生成 Surface、Balloon、Depth Balloon 或 Depth Surface，并通过统一的 `O Image Cutout` 修改器切换 Shape、按创建分辨率清理碎岛、根据 Region Alpha 校准浮雕基准和调整表面
|
||||
- 用 Image Box、Lasso、Line、Polyline 和 Perspective 清理或矫正静态图片
|
||||
- 用 BEN2 为单图、视频或序列帧去除背景
|
||||
- 用三档 ONNX 模型将单图、视频或序列帧放大 4×，并独立重采样 Alpha
|
||||
|
||||
AI 推理运行在 Blender 之外的独立 Python 3.12 Environment 中。Blender 进程只负责 UI、任务提交和结果导入，不加载 ONNX Runtime 或模型权重。
|
||||
|
||||
**Maximum AI Input Size** 默认设为 2048 px，只限制 Upscale 可执行图片长边 以及 Depth、Normal Map、Fit to Foreground 的 AI 分析输入，不降低颜色贴图分辨率。Cutout 网格密度由默认 `1024` 的独立 **Maximum Cutout Mesh Resolution** 限制，因此本地与 AI Shape 使用同一套明确的网格上限。
|
||||
|
||||
## 安装
|
||||
|
||||
1. 下载与系统匹配的扩展包：
|
||||
- `AnyImage.v<version>.windows-x64.zip`
|
||||
- `AnyImage.v<version>.macos-arm64.zip`
|
||||
- `AnyImage.v<version>.linux-x64.zip`
|
||||
2. 在 Blender 打开 **Edit > Preferences > Extensions**，选择 **Install from Disk** 并直接安装 ZIP。
|
||||
3. 选中 Image Empty，在右键 **AnyImage** 菜单中点击 **Set Up AI Environment…**。
|
||||
4. 安装完成后，在扩展 Preferences 中确认默认 MoGe-2、BEN2 与 Real-ESRGAN WDN 模型显示 Ready。
|
||||
|
||||
普通 Plane、基础 Image 编辑，以及未启用 **Fit to Foreground** / **Generate Normal Map** 的 Cutout Surface 与 Balloon 无需 AI Environment。Cutout 的 Depth 与 Normal Map 统一使用 MoGe-2；两者同时启用时共享同一次 Prediction，不会重复运行模型。Cutout 的 **Generate Normal Map** 是启用开关；开启后，Depth Surface 自动使用 Object Space，其余 Shape 自动使用 Tangent Space。
|
||||
|
||||
Balloon 与 Depth Balloon 会用 `o_balloon` 驱动 `O Image Layer` 已有的 **Normal Scale**，使 Normal Map 强度在轮廓处回落。
|
||||
|
||||
## 快速使用
|
||||
|
||||
选中 Image Empty 后，右键 **AnyImage** 菜单提供：
|
||||
|
||||
- **Convert to Plane**：同步创建普通图片网格；
|
||||
- **Convert to Depth Plane**：使用 Preferences 中选择的深度模型处理静态图；
|
||||
- **Remove Background**：生成透明图片或序列；
|
||||
- **Upscale**：使用默认高清模型把当前图片编辑为 4× 结果。
|
||||
|
||||
3D Viewport 工具栏提供 Image Mask、Perspective 与 Cutout。Remove Background、Upscale、Image Mask 和 Perspective 都只更新当前 Empty；共享 Image 会保留原数据，并为当前 Empty 创建独立结果。工作流对比和当前输入范围见[选择工作流](docs/guides/workflows.md)。
|
||||
|
||||
## 源码结构
|
||||
|
||||
```text
|
||||
src/anyimage/
|
||||
├── operators/ # Blender 交互、任务提交与结果导入
|
||||
├── server/ # 无 Blender 依赖的 Job、媒体、Region、几何与模型能力
|
||||
├── assets/ # Geometry Nodes 与 Shader 资产
|
||||
├── runtime.py # BlendJob Runtime 配置
|
||||
└── __init__.py # Blender 注册入口
|
||||
```
|
||||
|
||||
生产功能使用的可复用节点组统一构建到 `assets/O_AnyImage.blend`，运行时只按名称加载，不动态创建节点组。
|
||||
|
||||
程序边界、功能文件结构和调用流程见[内部实现总览](docs/internals/index.md)；开发新功能前先查看[Common 公共函数](docs/internals/common.md)，复用已经存在的 Image、Depth 产物、Material 和对象替换入口。文档按开始使用、功能指南、参考和内部实现分层，不在 README 重复内部算法细节。
|
||||
|
||||
## 开发
|
||||
|
||||
仓库开发环境使用 CPython 3.11：
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
uv run pytest
|
||||
uv run python pack.py
|
||||
```
|
||||
|
||||
节点资产脚本必须由 Blender 执行，具体命令和验证范围见[节点资产](docs/internals/node-assets.md)。完整开发、打包与 CI 说明见[开发与发布](docs/internals/development.md)。
|
||||
|
||||
## 许可证
|
||||
|
||||
AnyImage Extension 代码采用 GPL-3.0-or-later。模型权重使用各自上游许可证。
|
||||
- 按 **Ctrl+V**（macOS 为 **Cmd+V**）把剪贴板图片粘贴到当前编辑器
|
||||
- 用 **Plane** 创建可调厚度和细分的图片网格
|
||||
- 用 **Depth Plane** 把静态图片转换为可调节的立体面片
|
||||
- 用 **Cutout** 从套索选区生成 Surface、Balloon 与两种 Depth Shape
|
||||
- 用 **Image Tools / Perspective** 直接清理或矫正 Image Empty
|
||||
- 用 **Remove Background / Upscale** 处理单图、视频和序列帧
|
||||
Reference in New Issue
Block a user