# Image Add Label - 图像文字标注（自适应缩放）

**节点功能**：`Image Add Label` 为图像添加文字标签，标签随图像尺寸与放置方向自适应缩放。支持批量图像与批量文本、动态变量引用、`--` 段落分隔以及按可用宽度自动换行。任一输入批次为 RGBA 时，节点会保留 alpha 并输出 RGBA。

## Inputs | 输入

| 参数名称 | 入端选择 | 数据类型 | 默认值 | 取值范围 | 描述 |
| -------- | -------- | -------- | ------ | -------- | ---- |
| `image` | - | IMAGE | - | - | 输入图像批次 |
| `height_pad` | - | INT | 24 | 1–1024 | 文本周围的最小留白，随尺寸比例缩放 |
| `font_size` | - | INT | 36 | 1–256 | 以 1024 为参考分辨率的基础字号，自动缩放 |
| `invert_color` | - | BOOLEAN | True | - | `True` 输出白色标签+黑字；`False` 输出黑色标签+白字 |
| `font` | - | COMBO | 自动 | fonts 目录 | 从 `fonts/` 目录选择字体（如 `Alibaba-PuHuiTi-Regular.otf`） |
| `text` | - | STRING(多行) | "" | - | 标签文本。存在仅由连字符组成的行时，按 `--` 严格分段；否则按换行分割 |
| `direction` | - | COMBO | `top` | `top`/`bottom`/`left`/`right` | 标签放置方向 |
| `input1` | - | STRING | "" | - | 可在 `text` 中引用的变量 |
| `input2` | - | STRING | "" | - | 可在 `text` 中引用的变量 |

## Outputs | 输出

| 输出名称 | 数据类型 | 描述 |
|---------|----------|------|
| `image` | IMAGE | 带标签的图像批次；RGB 输入输出 RGB，RGBA 输入自动保留 RGBA |

## 功能说明

- 自适应缩放：基于图像宽高与放置方向自动选择缩放模式，保持不同尺寸下的标签占比一致。
- 智能换行：按最大可用宽度进行多行换行；兼容空格分词与中文等无空格文本，度量结果缓存提升性能。
- 固定行高：通过字体度量获取固定行高与顶部偏移，确保行距稳定、布局不跳动。
- 变量模板：支持 `{input1}`、`{input2}`，以及逐帧表达式 `{index}`、`{idx}`、`{range±K}`；`{range}` 可按批量长度自动补零。
- 方向布局：`top/bottom` 生成水平标签条；`left/right` 通过旋转临时标签后进行垂直拼接。
- Alpha 规则：当输入图像带 alpha 时，原图透明区域会保留，新增标签区域默认写入不透明 alpha。
- 异步渲染：逐帧在工作线程渲染，保持界面响应性。

## 典型用法

- 顶部横幅：设置 `direction=top`，使用多行文本；通过 `height_pad` 调整留白。
- 侧边标注：设置 `direction=left/right`，生成垂直标签条；内容按高度自动换行。
- 批量编号：`text` 示例 `Frame {index+1}\nID {range}`，每帧自动编号。
- 自定义字体：将 `.ttf/.otf` 放入 `fonts/` 目录后在 `font` 下拉选择。

## 注意与建议

- 基础字号与留白以 1024 分辨率为参考，并随图像尺寸与方向进行比例缩放。
- 当存在仅由连字符组成的行时，`--` 分隔优先且严格；分段内部的换行原样保留。
- `invert_color=True` 输出白底黑字的标签；`False` 输出黑底白字的标签。