跳转至

AddTextToExistingImage 图像动态文字叠加与水印打标节点

节点核心功能 (What is it?)

AddTextToExistingImage 节点负责在现有图像的指定物理空间上绘制并叠加文本图层。它原生支持带 Alpha 透明度的文本与矩形背景色渲染、九宫格对齐定位控制，以及通过外部字典输入动态注入并展开替换 {key} 占位符变量。

典型适用场景 (When would I use it?)

在以下情况下使用该节点：

  • 为图像画面添加大标题、图注、分镜标注或角标标签；
  • 自动化打标元数据信息（如文件名、拍摄时间戳、模型版本号或任务 ID）；
  • 为下游审查流程制作带详细注释说明的质检图像；
  • 通过从上游字典提取的动态参数，自动化批量生成带有可变文本的营销海报或设计卡片。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

  1. 在画布中添加 AddTextToExistingImage 节点。
  2. 将底图数据源接入 input_image 输入插槽。
  3. 在 text 字段输入待渲染的文字模板（支持 {key} 占位符）。
  4. （可选）将包含键值映射的字典接入 template_values 插槽以动态展开模板变量。
  5. 配置对齐方式、文字与底色透明度、边距与字号大小。
  6. 运行节点，在 output 即可提取打标后的全新图像。

参数输入插槽 (Parameters)

核心输入 (Required Inputs)

  • input_image：待叠加绘制文字的底图资产（ImageUrlArtifact / ImageArtifact / 字典数据）。

文本模板与变量 (Text Inputs)

  • text（字符串）：待渲染的文本模板内容。
    • 原生支持形如 {key_name} 的占位符；
    • 占位符动态展开仅体现在渲染后的图像画面上，该节点的 text 输出引脚将完整保留原始模板字符串不变。
  • template_values（字典 dict，可选）：用于展开 text 模板中各占位符的键值对映射表。
    • 若模板中的某个键未在字典中提供，该标记将作为纯文本原生保留；
    • 缺失字段信息会详细记录在 result_details 状态中。

排版样式微调 (Styling Parameters)

  • text_color（Hexa 带透明度十六进制，默认 #ffffffff 纯白完全不透明）：文本字体的颜色与 Alpha 透明度。
  • text_background（Hexa，默认 #000000ff 纯黑完全不透明）：文字块背后的矩形衬底背景色与透明度（例如 #00000080 表示 50% 半透明黑）。
  • text_vertical_alignment（top | center | bottom，默认 top）：文字块在画布上的垂直方向对齐规则。
  • text_horizontal_alignment（left | center | right，默认 left）：文字块的水平方向对齐规则。
  • margin（整型像素，默认 10）：文字块与图像边缘之间的安全边距间隔。
  • font_size（整型像素，默认 36）：绘制渲染所用的基准字体物理磅值。

输出引脚 (Outputs)

  • output：叠加了文字图层的全新图像工件（ImageUrlArtifact）。
  • text：原始传入的文本模板字符串（未展开版本）。
  • was_successful（布尔值）：标志文字叠加计算是否成功执行完毕。
  • result_details：执行详情或告警信息（包含缺失模板键名的排查线索）。

典型工作流示例 (Example)

批量打标元数据水印流水线：

  1. 使用 LoadImage 导入一张待导出的成图。
  2. 添加 AddTextToExistingImage 节点并连接底图。
  3. 将 text 模板配置为： "Photo: {name} | #{index}"
  4. 接入 template_values 字典参数： 
    {"name": "Portrait", "index": 7}
  5. 将 text_background 设为半透明黑色遮罩 #00000080。
  6. 将 text_color 设为纯白 #ffffffff。
  7. 运行节点，在 DisplayImage 中即可查看画面边缘优雅叠印着 "Photo: Portrait | #7" 半透明文字标牌的成图。

关键技术特性 (Important Notes)

  • 全通道 Alpha 颜色支持 (Hexa Support)：文本颜色与背景衬底色均原生支持 8 位十六进制格式（#RRGGBBAA），可自由调配柔和的半透明磨砂或发光效果。
  • 防崩溃容错回退：若字典中缺失特定键，节点不会抛出异常中断执行，而是原样保留 {key} 并优雅记录在日志中。
  • 非破坏性图层绘制：原图像素不受底层破坏，文字与背景图层在合并渲染后生成全新的工件资产。