Caire 是一个基于 Seam Carving for Content-Aware Image Resizing 论文的内容感知图像缩放库。

工作原理

• 从提供的图像中生成能量图（边缘检测）。
• 算法会根据最低的能量值，尝试找到图像中最不重要的部分。
• 通过动态规划方法，算法会在图像上从上到下或从左到右（取决于水平或垂直缩放）生成独立的“接缝”，并为每条接缝分配一个自定义值，其中最重要像素的能量成本最高，最不重要像素的能量成本最低。
• 我们从第二行开始遍历图像，计算每一项所有可能连接接缝的累积最小能量。
• 最小能量等级是通过将当前像素值与前一行中相邻像素的最低值相加来计算的。
• 我们从上到下遍历图像，计算最小能量等级。对于每一行中的每个像素，我们计算当前像素的能量加上其上方三个可能像素之一的能量。
• 从能量矩阵中找出成本最低的接缝并将其移除。
• 重复该过程。

过程示意图：

原始图像	能量图	应用的接缝

特性

本库区别于其他现有开源解决方案的关键特性：

• GUI 进度指示器
• 可定制的命令行支持
• 同时支持缩小和放大图像
• 可以同时进行垂直和水平方向的缩放
• 人脸检测功能，避免面部变形
• 支持多种输出图像格式（jpg、jpeg、png、bmp）
• 支持 stdin 和 stdout 管道命令
• 可递归且并发地处理整个目录
• 使用 Sobel 阈值进行精细调整
• 使用模糊滤波器增强边缘检测
• 支持通过单个命令将图像裁剪为正方形
• 支持按比例缩放
• 支持保护性遮罩
• 支持移除性遮罩
• GUI 调试模式支持

安装

首先，安装 Go，设置好 GOPATH，并确保 $GOPATH/bin 在你的 PATH 中。

$ go install github.com/esimov/caire/cmd/caire@latest

macOS (Brew) 安装

该库也可以通过 Homebrew 安装。

$ brew install caire

使用

$ caire -in input.jpg -out output.jpg

支持的命令：

$ caire --help

支持以下标志：

标志	默认值	描述
in	-	输入文件
out	-	输出文件
width	n/a	新宽度
height	n/a	新高度
preview	true	显示 GUI 窗口
perc	false	按百分比缩小图像
square	false	将图像缩放为正方形
blur	4	模糊半径
sobel	2	Sobel 滤波器阈值
debug	false	使用调试器
face	false	使用人脸检测
angle	float	旋转平面中的人脸角度
mask	string	遮罩文件路径
rmask	string	移除遮罩文件路径
color	string	接缝颜色（默认 #ff0000）
shape	string	调试时使用的形状类型：circle、line（默认 circle）

人脸检测

该库能够利用轻量级的 Pigo（https://github.com/esimov/pigo）人脸检测库，在缩放图像之前检测出人脸。

下图展示了在缩放前进行人脸检测的应用效果。可以清楚地看到，启用人脸检测后，算法会避免裁剪检测到的人脸区域内的像素，从而保持人脸区域不变。

原始图像	启用人脸检测	未启用人脸检测

示例图片来源

GUI 进度指示器

该库还内置了 GUI 预览模式，用于实时可视化处理过程。由于其强大性和现代架构，使用了 Gio GUI 库。在运行之前，请确保已安装安装部分中提到的所有依赖项（https://gioui.org/#installation）。

预览窗口默认开启，但您可以通过将 -preview 标志设置为 false 来随时关闭它。当从目录中并发处理图像时，预览模式将被禁用。

人脸检测以避免面部变形

为了在重新缩放之前检测人脸，请使用 -face 标志。无需提供人脸分类文件，因为它已嵌入到生成的二进制文件中。下面的示例代码会将提供的图像按 20% 的比例缩小，但在执行操作前会检查是否存在人脸，以避免面部变形。

有关人脸检测的相关设置，请参阅 Pigo 的 文档。

$ caire -in input.jpg -out output.jpg -face=1 -perc=1 -width=20

支持 stdin 和 stdout 管道命令

您也可以使用 stdin 和 stdout，只需将输入和输出指定为 -：

$ cat input/source.jpg | caire -in - -out - >out.jpg

由于 in 和 out 默认为 -，因此也可以这样使用：

$ cat input/source.jpg | caire >out.jpg
$ caire -out out.jpg < input/source.jpg

您还可以为 -in 标志提供一个图像 URL，甚至可以使用 curl 或 wget 作为管道命令，在这种情况下无需使用 -in 标志。

$ caire -in <image_url> -out <output-folder>
$ curl -s <image_url> | caire > out.jpg

并发处理目录中的多张图片

该库还可以并发处理目录中的多张图片。在这种情况下，您只需提供源文件夹和目标文件夹，以及新的宽度或高度。

$ caire -in <input_folder> -out <output-folder>

支持多种输出图像格式

无需定义输出文件类型，只需使用正确的文件扩展名，库就会将图像编码为该特定格式。

其他选项

如果您希望按特定百分比缩小图像，可以使用 -perc 布尔标志。在这种情况下，width 和 height 提供的值将以百分比表示，而不是像素值。例如，要将图像在水平和垂直方向上都缩小 20%，可以使用以下命令：

$ caire -in input/source.jpg -out ./out.jpg -perc=1 -width=20 -height=20 -debug=false

此外，库还支持 -square 选项。当使用此选项时，图像将根据最短边调整为正方形。

当图像在 X 轴和 Y 轴上同时缩放时，算法会先尝试在进一步缩放之前进行重采样，同时保持图像的宽高比例不变。仅对剩余部分应用接缝雕刻算法。例如：给定一张 2048x1536 的图像，如果我们要将其调整为 1024x500，工具会先将图像缩放到 1024x768，然后再移除剩余的 268 像素。

掩码支持：

• -mask: 保护掩码的路径。掩码应为二进制格式，且与输入图像大小相同。白色区域表示不应雕刻接缝的区域。
• -rmask: 移除掩码的路径。掩码应为二进制格式，且与输入图像大小相同。白色区域表示需要移除的区域。

掩码	掩码移除

Caire 集成

• Caire 可以通过 OpenFaaS 用作无服务器函数：https://github.com/esimov/caire-openfaas
• Caire 也可以作为 snap 功能使用（https://snapcraft.io/caire）：`$ snap run caire --h`

结果

缩小后的图片

原图	缩小后

放大后的图片

原图	扩展后

有用资源

• https://en.wikipedia.org/wiki/Seam_carving
• https://inst.eecs.berkeley.edu/~cs194-26/fa16/hw/proj4-seamcarving/imret.pdf
• http://pages.cs.wisc.edu/~moayad/cs766/download_files/alnammi_cs_766_final_report.pdf
• https://stacks.stanford.edu/file/druid:my512gb2187/Zargham_Nassirpour_Content_aware_image_resizing.pdf

作者

• Endre Simo (@simo_endre)

许可证

版权所有 © 2018 Endre Simo

本项目采用 MIT 许可证。完整的许可文本请参阅 LICENSE 文件。

Caire 快速上手指南

Caire 是一个基于“接缝裁剪（Seam Carving）”算法的内容感知图像大小调整库。它能在缩放图片时智能识别并保留重要内容（如人脸、主体物体），避免传统拉伸导致的变形。

环境准备

• 操作系统：Linux, macOS, Windows (需配置 Go 环境)
• 前置依赖：
  • Go 语言环境：需安装 Go 并配置好 GOPATH，确保 $GOPATH/bin 已加入系统 PATH 环境变量。
  • GUI 依赖（可选）：若需使用图形化进度预览窗口 (-preview)，请确保系统已安装 Gio 所需的图形库依赖。若仅命令行批量处理，可忽略此项。

安装步骤

你可以通过以下任意一种方式安装 Caire：

方式一：通过 Go 安装（推荐）

适用于所有平台，直接获取最新源码编译安装：

go install github.com/esimov/caire/cmd/caire@latest

方式二：macOS (Homebrew)

如果你使用的是 macOS 且安装了 Homebrew：

brew install caire

方式三：Snap (Linux)

适用于支持 Snap 的 Linux 发行版：

sudo snap install caire

基本使用

安装完成后，即可在终端使用 caire 命令。

1. 基础缩放

将图片 input.jpg 调整为指定宽度（高度自动计算以保持比例），输出为 output.jpg：

caire -in input.jpg -out output.jpg -width 800

2. 按百分比缩放

将图片长宽同时缩小 20%：

caire -in input.jpg -out output.jpg -perc=1 -width 20 -height 20

3. 人脸保护模式（核心功能）

开启人脸检测，防止缩放时人物面部变形：

caire -in input.jpg -out output.jpg -face=1 -width 600

4. 批量处理目录

递归并发处理整个文件夹内的图片：

caire -in ./source_folder -out ./dest_folder -width 1024

5. 管道流式处理

支持 stdin/stdout，可结合 curl 或其他工具使用：

curl -s https://example.com/image.jpg | caire -width 500 > resized.jpg

提示：运行时会默认弹出 GUI 进度窗口。若在服务器或无界面环境下运行，请添加 -preview=false 参数禁用它。