> ## Documentation Index
> Fetch the complete documentation index at: https://bitiful-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 修剪边框
## 概览
`trim` 用于自动去除图像四周的 **纯色边框**（如商品图的白底留白、截图的灰底）或 **透明边框** （如 PNG 导出时多余的透明画布）。它检测内容的最小外接矩形，然后把图裁到这个矩形。
为准确回应 `w/h/rect/dpr` 等 **会更改图片大小、比例 等参数** 的输出图片尺寸预期，该参数发生在所有此类处理之前。
| 模式 | 判定谓词 |
| ------------------ | ------------------------------------------------- |
| `color` | 像素与指定色的差 ≤ `trim-tol` → 背景 |
| `auto` | 行/列离自动检测背景色的均值差 ≤ `trim-md` 且标准差 ≤ `trim-sd` → 背景 |
| `alpha` | `alpha ≤ trim-alpha` → 背景 |
| `colorunlessalpha` | 有 alpha 通道时同 `alpha`，否则同 `auto` |
## 参数总表
| 参数 | 默认值 | 取值范围 | 生效模式 | 一句话含义 |
| ------------ | -------- | -------------------------------------------------- | ------- | --------------- |
| `trim` | 无（不修剪） | `auto` \| `color` \| `alpha` \| `colorunlessalpha` | — | 模式开关，不传则整个功能不激活 |
| `trim-color` | 无（=自动检测） | `RGB` / `RRGGBB` 十六进制 | `color` | 要裁掉的背景色 |
| `trim-tol` | `10` | `0` \~ `255` | `color` | 颜色容差 |
| `trim-md` | `11` | `0` \~ `255` | `auto` | 均值差阈值 |
| `trim-sd` | `10` | `0` \~ `255` | `auto` | 标准差阈值 |
| `trim-alpha` | `0` | `0` \~ `255` | `alpha` | 透明度阈值 |
**参数不通用**：
* `trim-tol` 只在 `color` 模式生效
* `trim-md`/`trim-sd` 只在 `auto` 模式生效
* `trim-alpha` 只在 `alpha` 模式生效。传给不匹配模式的参数会被静默忽略。
## 场景实例
### 修剪视频截帧
原图（上下带黑边）
`trim=auto` 自动修剪后
### 修剪 Logo / Icon
原图（四周带白边）
`trim=auto` 自动修剪后
***
## 参数详解
### `trim` —— 模式开关
不传该参数时不做任何修剪。四个可选值：
#### `auto`（推荐默认）
自动检测背景色（取**四角 8×8 小块的中位数**，对少量噪声与 JPEG 块效应鲁棒）， 再按**行/列统计**判定背景边：某行/列同时满足「离背景的平均差 ≤ `trim-md`」且 「内部差异的标准差 ≤ `trim-sd`」才判为背景。
适用：照片留白、扫描件、带轻微压缩噪声或渐变的背景边。统计判定比逐像素匹配更鲁棒。
#### `color`
裁掉指定色 `trim-color` ±`trim-tol` 容差的边。若未提供 `trim-color`，回退为自动检测背景色。
适用：明确知道背景色是什么（如统一白底商品图），需要精确控制容差的场景。
#### `alpha`
裁掉 `alpha ≤ trim-alpha` 的透明边。**源图无 alpha 通道时为空操作**（原样返回，不报错）。
适用：PNG/WebP 等带透明通道的图，去掉多余的透明画布。
#### `colorunlessalpha`
智能选择：源图**含 alpha 通道**时走 `alpha`，否则走 `auto`。
适用：不确定输入是什么格式的通用场景（如用户上传的混合素材）。
***
### `trim-color` —— 背景色
* **默认**：无（回退自动检测）
* **格式**：十六进制，支持 3 位 `RGB` 缩写或 6 位 `RRGGBB`，可带 `#` 前缀
* **示例**：`fff`、`ffffff`、`e9e9e9`、`%23e9e9e9`（URL 中 `#` 需转义）
* **生效模式**：`color`
指定要裁掉的背景色。格式非法时会记警告并回退为自动检测，不会导致请求失败。
***
### `trim-tol` —— 颜色容差
* **默认**：`10`
* **范围**：`0` \~ `255`
* **生效模式**：`color`
像素与背景色**任一通道**之差 ≤ 该值即视为背景。
* **调小**（如 `0`\~`5`）：只裁掉与背景色几乎完全一致的像素。适合合成图的绝对平整背景。
* **调大**（如 `20`\~`40`）：容忍压缩噪声与轻微色偏。但过大会误裁接近背景色的浅色内容。
> 背景**绝对平整**时（如设计稿导出），容差取值不敏感——实测某图 `trim-tol` 从 5 到 40 结果只差 1px，因为内容与背景对比强烈，阈值落在哪都是同一条分界线。真正吃容差的是 「接近背景色的浅色内容」或「脏边」。
***
### `trim-md` —— 均值差阈值
* **默认**：`11`
* **范围**：`0` \~ `255`
* **生效模式**：`auto`
某行/列离背景色的**平均差** ≤ 该值，才**可能**判为背景边。管的是「整体偏移」—— 背景渐变、镜头暗角、整体色偏。
* **调小**：要求背景边更接近检测出的参考色，判定更严格（裁得更保守）。
* **调大**：容忍更明显的渐变背景（裁得更激进）。
***
### `trim-sd` —— 标准差阈值
* **默认**：`10`
* **范围**：`0` \~ `255`
* **生效模式**：`auto`
某行/列内部差异的**标准差** ≤ 该值，才**可能**判为背景边。管的是「内部起伏」—— 噪点、纹理、细节。
* **调小**：要求背景边内部更均匀（裁得更保守）。
* **调大**：容忍更多噪声（裁得更激进）。
> **`trim-md` 与 `trim-sd` 是「与」关系**：两个条件**同时满足**才判为背景行/列。 两者分工互补——均值差管整体偏移，标准差管内部起伏。一条有明显渐变但很平滑的边 会被 `trim-md` 拦下；一条整体色对但满是噪点的边会被 `trim-sd` 拦下。
***
### `trim-alpha` —— 透明度阈值
* **默认**：`0`
* **范围**：`0` \~ `255`
* **生效模式**：`alpha`
alpha **大于**该值才算内容。缺省 `0` 表示只要**非全透明**（alpha ≥ 1）就是内容。
* **默认 `0`**：**保守且安全**——所有半透明像素（羽化、投影、渐隐等艺术效果） 全部保留，只裁掉完全透明（alpha = 0）的边。
* **调大**（如 `8`）：用于某些导出工具在「本应全透明」的边上留下 alpha=1\~2 噪声残渣 的情况。属于用户显式选择。
> trim 是**纯裁剪操作**，只裁掉矩形边缘，**不修改任何被保留的像素**。 半透明内容不会因 trim 而改变透明度。
***
## 管线次序
**trim 位于所有可能改变尺寸的处理之前**：
```text theme={null}
frame seek → trim → 百分比换算 → rect → resize → sharpen/blur → rotate → 水印 → 编码输出
↑
在这里去边
```
两个直接后果：
1. **后续操作都作用在裁剪后的图上**。`trim=auto&w=300` 是「先去边，再按去边后的宽高比缩到 300」。
2. **百分比参数以裁后尺寸为基准**。`trim=auto&w=50%` 中的 50% 是裁剪后宽度的一半， 不是原图宽度的一半。`rect=10%,10%,80%,80%` 同理。