ChaiNNer项目节点开发深度解析：从概念到实现-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01089/article/details/148506464

ChaiNNer项目节点开发深度解析：从概念到实现

chaiNNer A node-based image processing GUI aimed at making chaining image processing tasks easy and customizable. Born as an AI upscaling application, chaiNNer has grown into an extremely flexible and powerful programmatic image processing application. 项目地址: https://gitcode.com/gh_mirrors/cha/chaiNNer

前言

ChaiNNer作为一个可视化编程语言和开发环境，其核心构建单元是"节点"。本文将深入剖析ChaiNNer节点的设计理念、开发规范以及实现细节，帮助开发者理解如何为ChaiNNer创建高效、可靠的节点。

节点基础概念

在ChaiNNer中，节点相当于传统编程语言中的函数，它们接收输入并产生输出。每个节点实际上是一个带有额外元数据的Python函数，这些元数据用于：

在UI中展示节点信息
确定节点间的有效连接关系
提供类型检查等编译时验证

节点通过包(package)和分类(category)进行组织管理：

包：管理节点依赖（如pip包）
分类：在UI中组织节点结构

节点开发三大黄金法则

1. 不可变性原则

节点禁止修改其输入参数，这是因为ChaiNNer会出于性能考虑缓存和重用值。如果节点修改了输入，将破坏缓存机制导致错误结果。

特别提醒：处理图像(numpy数组)时要格外小心，因为numpy数组是可变的。如需修改输入，必须先创建副本。

2. 确定性原则

节点必须是确定性的——相同输入总是产生相同输出。这对缓存机制至关重要。

随机数处理：如需随机数，应使用固定种子或提供种子输入参数。

3. 副作用声明原则

节点应避免副作用（如文件操作、剪贴板写入等）。如必须产生副作用，需在元数据中明确声明side_effects=True。

节点元数据详解

节点元数据定义了节点与前后端的契约，包括：

核心元数据字段

Schema ID：节点的唯一标识符，推荐格式chainner:<category>:<name>
名称：简洁明了的描述性名称
描述：支持多段Markdown格式文本
图标：从指定图标库中选择
输入/输出：定义节点的接口契约
副作用标记：声明节点是否有副作用

输入输出声明规范

节点必须显式声明所有输入输出，主要作用包括：

类型信息用于验证连接有效性
范围限制用于验证用户输入
占位符和默认值提升用户体验

常见输入类：

NumberInput/SliderInput：数值输入
TextInput：文本输入
ImageInput：图像输入

常见输出类：

ImageOutput：图像输出
NumberOutput：数值输出
TextOutput：文本输出

ID分配与重排序

输入输出默认按声明顺序分配ID。重排序时需注意：

首先为现有元素分配显式ID
然后进行重新排序
中间插入新元素需要为所有元素分配显式ID

# 正确重排序示例
inputs=[
    NumberInput("B").with_id(1),
    ImageInput("A").with_id(0),
]

高级功能实现

输入分组

条件分组：根据其他输入值显示/隐藏相关输入
种子分组：专门处理随机种子输入的特殊样式

# 条件分组示例
inputs = [
    EnumInput(Format, "Format").with_id(0),
    if_enum_group(0, Format.B)(
        NumberInput("B weight")  # 仅当选择B时显示
    ),
]

类型系统集成

ChaiNNer使用名为Navi的自定义类型系统。输出类型可通过output_type参数进行细化：

ImageOutput(
    image_type="""
        Image {
            width: Input0.width + 2*Input1,
            height: Input0.height + 2*Input1,
            channels: Input0.channels,
        }
    """,
)

文档注释

通过.with_docs()方法为输入输出添加文档，支持Markdown格式：

ImageInput().with_docs(
    "示例图像输入",
    "支持*Markdown*格式",
    hint=True  # 在节点上显示提示图标
)

节点通信机制

广播系统

数据广播：向后端发送数据（如图像预览）
类型广播：补充静态类型系统无法推断的信息

注意：广播是可选功能，前端可能忽略某些广播。

节点实现实例解析

以Opacity节点为例：

@adjustments_group.register(
    schema_id="chainner:image:opacity",
    name="Opacity",
    description="调整图像透明度",
    inputs=[
        ImageInput(),
        SliderInput("Opacity", maximum=100, unit="%"),
    ],
    outputs=[
        ImageOutput(image_type=navi.Image(size_as="Input0"), channels=4)
    ],
)
def opacity_node(img: np.ndarray, opacity: float) -> np.ndarray:
    # 确保不修改原始输入
    imgout = convert_to_BGRA(img, get_h_w_c(img)[2])
    imgout[:, :, 3] *= opacity/100
    return imgout

关键点：