图像操作

rotate

rotate([angle], [options]) ⇒ Sharp

旋转输出图像。

提供的角度将转换为有效的正度旋转。例如，-450 将产生 270 度的旋转。

当旋转角度不是 90 的倍数时，可以使用 background 选项提供背景颜色。

为了向后兼容，如果未提供角度，将调用 .autoOrient()。

每个管道中仅能发生一次旋转（除了初始不带参数的调用以通过 EXIF 数据进行方向设置）。同一管道中先前对 rotate 的调用将被忽略。

多页面图像只能旋转 180 度。

旋转、调整大小和/或提取区域时，方法的顺序很重要，例如，.rotate(x).extract(y) 将产生与 .extract(y).rotate(x) 不同的结果。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[angle]	number	auto	旋转角度。
[options]	Object		如果提供，是一个具有可选属性的对象。
[options.background]	string | Object	”"#000000"“	由 color 模块解析以提取红色、绿色、蓝色和 alpha 的值。

示例

const rotateThenResize = await sharp(input)
  .rotate(90)
  .resize({ width: 16, height: 8, fit: 'fill' })
  .toBuffer();
const resizeThenRotate = await sharp(input)
  .resize({ width: 16, height: 8, fit: 'fill' })
  .rotate(90)
  .toBuffer();

autoOrient

autoOrient() ⇒ Sharp

根据 EXIF Orientation 标签进行自动方向调整，然后移除该标签。 支持镜像，并且可能推断使用翻转操作。

之前或之后使用 rotate(angle) 和 flip() 或 flop() 将逻辑发生在自动方向调整后，无论调用顺序如何。

示例

const output = await sharp(input).autoOrient().toBuffer();

示例

const pipeline = sharp()
  .autoOrient()
  .resize(null, 200)
  .toBuffer(function (err, outputBuffer, info) {
    // outputBuffer 包含 200px 高的 JPEG 图像数据，
    // 使用 EXIF Orientation 标签进行自动方向调整
    // info.width 和 info.height 包含调整大小后图像的维度
  });
readableStream.pipe(pipeline);

flip

flip([flip]) ⇒ Sharp

在 x 轴上垂直（上下）翻转图像。 这总是在任何旋转之前发生。

此操作对于多页面图像无法正常工作。

参数	类型	默认
[flip]	Boolean	true

示例

const output = await sharp(input).flip().toBuffer();

flop

flop([flop]) ⇒ Sharp

在 y 轴上水平（左右）翻转图像。 这总是在任何旋转之前发生。

参数	类型	默认
[flop]	Boolean	true

示例

const output = await sharp(input).flop().toBuffer();

affine

affine(matrix, [options]) ⇒ Sharp

对图像执行仿射变换。此操作将总是在调整大小、提取和旋转之后发生（如有）。

您必须提供一个长度为 4 的数组或一个 2x2 的仿射变换矩阵。 默认情况下，新像素将用黑色背景填充。您可以使用 background 选项提供背景颜色。 也可以指定特定的插值器。将 interpolator 选项设置为 sharp.interpolators 对象的属性，例如 sharp.interpolators.nohalo。

在 2x2 矩阵的情况下，变换为：

• X = matrix[0, 0] * (x + idx) + matrix[0, 1] * (y + idy) + odx
• Y = matrix[1, 0] * (x + idx) + matrix[1, 1] * (y + idy) + ody

其中：

• x 和 y 是输入图像中的坐标。
• X 和 Y 是输出图像中的坐标。
• (0,0) 是左上角。

抛出:

• Error 无效的参数

自: 0.27.0

参数	类型	默认	描述
matrix	Array.<Array.<number>> | Array.<number>		仿射变换矩阵
[options]	Object		如果提供，是一个具有可选属性的对象。
[options.background]	String | Object	”#000000”	由 color 模块解析以提取红色、绿色、蓝色和 alpha 的值。
[options.idx]	Number	0	输入水平偏移
[options.idy]	Number	0	输入垂直偏移
[options.odx]	Number	0	输出水平偏移
[options.ody]	Number	0	输出垂直偏移
[options.interpolator]	String	sharp.interpolators.bicubic	插值器

示例

const pipeline = sharp()
  .affine([[1, 0.3], [0.1, 0.7]], {
     background: 'white',
     interpolator: sharp.interpolators.nohalo
  })
  .toBuffer((err, outputBuffer, info) => {
     // outputBuffer 包含变换后的图像
     // info.width 和 info.height 包含新的维度
  });

inputStream
  .pipe(pipeline);

sharpen

sharpen([options], [flat], [jagged]) ⇒ Sharp

锐化图像。

在未使用参数的情况下，执行快速、温和的输出图像锐化。

当提供 sigma 时，执行更慢、更准确的 LAB 色彩空间的 L 通道锐化。 可以对“平坦”（m1）和“锯齿”（m2）区域的锐化级别进行精细控制。

参见 libvips sharpen 操作。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[options]	Object | number		如果提供，是一个具有属性的对象
[options.sigma]	number		高斯掩模的 sigma，其中 sigma = 1 + radius / 2，介于 0.000001 和 10 之间
[options.m1]	number	1.0	应用于“平坦”区域的锐化级别，介于 0 和 1000000 之间
[options.m2]	number	2.0	应用于“锯齿”区域的锐化级别，介于 0 和 1000000 之间
[options.x1]	number	2.0	“平坦”和“锯齿”之间的阈值，介于 0 和 1000000 之间
[options.y2]	number	10.0	最大亮度增加量，介于 0 和 1000000 之间
[options.y3]	number	20.0	最大暗度增加量，介于 0 和 1000000 之间
[flat]	number		（已弃用）见 options.m1。
[jagged]	number		（已弃用）见 options.m2。

示例

const data = await sharp(input).sharpen().toBuffer();

示例

const data = await sharp(input).sharpen({ sigma: 2 }).toBuffer();

示例

const data = await sharp(input)
  .sharpen({
    sigma: 2,
    m1: 0,
    m2: 3,
    x1: 3,
    y2: 15,
    y3: 15,
  })
  .toBuffer();

median

median([size]) ⇒ Sharp

应用中值滤波。 在未使用参数时，默认窗口为 3x3。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[size]	number	3	方形掩模大小：size x size

示例

const output = await sharp(input).median().toBuffer();

示例

const output = await sharp(input).median(5).toBuffer();

blur

blur([options]) ⇒ Sharp

模糊图像。

在没有参数的情况下，执行快速的 3x3 方框模糊（相当于方框线性滤波）。

提供 sigma 时，执行更慢、更准确的高斯模糊。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[options]	Object | number | Boolean
[options.sigma]	number		介于 0.3 和 1000 之间，表示高斯掩模的 sigma，其中 sigma = 1 + radius / 2。
[options.precision]	string	“‘integer‘“	操作的准确性，选项为：integer，float，approximate。
[options.minAmplitude]	number	0.2	介于 0.001 和 1 之间的值。较小的值将生成更大、更准确的掩模。

示例

const boxBlurred = await sharp(input)
  .blur()
  .toBuffer();

示例

const gaussianBlurred = await sharp(input)
  .blur(5)
  .toBuffer();

dilate

dilate([width]) ⇒ Sharp

使用膨胀形态操作扩展前景对象。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[width]	Number	1	膨胀宽度（以像素为单位）。

示例

const output = await sharp(input)
  .dilate()
  .toBuffer();

erode

erode([width]) ⇒ Sharp

使用腐蚀形态操作收缩前景对象。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[width]	Number	1	腐蚀宽度（以像素为单位）。

示例

const output = await sharp(input)
  .erode()
  .toBuffer();

flatten

flatten([options]) ⇒ Sharp

合并 alpha 透明通道（如果有），与背景一起，然后移除 alpha 通道。

另见 removeAlpha。

参数	类型	默认	描述
[options]	Object
[options.background]	string | Object	”{r: 0, g: 0, b: 0}“	背景颜色，由 color 模块解析，默认为黑色。

示例

await sharp(rgbaInput)
  .flatten({ background: '#F0A703' })
  .toBuffer();

unflatten

unflatten()

确保图像具有 alpha 通道，所有白色像素值将变为完全透明。

非白色像素的现有 alpha 通道值保持不变。

此功能是实验性的，API 可能会更改。

自: 0.32.1
示例

await sharp(rgbInput)
  .unflatten()
  .toBuffer();

示例

await sharp(rgbInput)
  .threshold(128, { grayscale: false }) // 将亮像素转换为白色
  .unflatten()
  .toBuffer();

gamma

gamma([gamma], [gammaOut]) ⇒ Sharp

通过在大小调整前按因子 1/gamma 减少编码（变暗），然后在大小调整后按因子 gamma 增加编码（变亮）来应用伽马校正。 这可以改善在非线性色彩空间中调整大小图像的感知亮度。 JPEG 和 WebP 输入图像在应用伽马校正时将无法利用加载时收缩性能优化。

提供第二个参数以使用不同的输出伽马值，否则第一个值将在两个情况下使用。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[gamma]	number	2.2	介于 1.0 和 3.0 之间的值。
[gammaOut]	number		介于 1.0 和 3.0 之间的值。（可选，默认为与 gamma 相同）

negate

negate([options]) ⇒ Sharp

生成图像的“负片”。

参数	类型	默认	描述
[options]	Object
[options.alpha]	Boolean	true	是否对任何 alpha 通道进行反转

示例

const output = await sharp(input)
  .negate()
  .toBuffer();

示例

const output = await sharp(input)
  .negate({ alpha: false })
  .toBuffer();

normalise

normalise([options]) ⇒ Sharp

通过拉伸其亮度以覆盖完整的动态范围来增强输出图像的对比度。

使用基于直方图的方法，默认范围为 1% 到 99%，以减少对噪声的敏感性。

低于 lower 百分位数的亮度值将通过裁剪为零而过度曝光。 高于 upper 百分位数的亮度值将通过裁剪为最大像素值而过度曝光。

参数	类型	默认	描述
[options]	Object
[options.lower]	number	1	亮度值将被过度曝光的百分位数。
[options.upper]	number	99	亮度值将被低曝光的百分位数。

示例

const output = await sharp(input)
  .normalise()
  .toBuffer();

示例

const output = await sharp(input)
  .normalise({ lower: 0, upper: 100 })
  .toBuffer();

normalize

normalize([options]) ⇒ Sharp

normalise 的另一种拼写。

参数	类型	默认	描述
[options]	Object
[options.lower]	number	1	亮度值将被过度曝光的百分位数。
[options.upper]	number	99	亮度值将被低曝光的百分位数。

示例

const output = await sharp(input)
  .normalize()
  .toBuffer();

clahe

clahe(options) ⇒ Sharp

执行对比度限制自适应直方图均衡化 CLAHE。

这通常可以通过突显较暗的细节来增强图像的清晰度。

抛出:

• Error 无效的参数

自: 0.28.3

参数	类型	默认	描述
options	Object
options.width	number		以像素为单位的搜索窗口的整数宽度。
options.height	number		以像素为单位的搜索窗口的整数高度。
[options.maxSlope]	number	3	亮度的整数级别，介于 0 和 100 之间，其中 0 禁用对比度限制。

示例

const output = await sharp(input)
  .clahe({
    width: 3,
    height: 3,
  })
  .toBuffer();

convolve

convolve(kernel) ⇒ Sharp

使用指定的核对图像进行卷积。

抛出:

• Error 无效的参数

参数	类型	默认	描述
kernel	Object
kernel.width	number		核的宽度，单位为像素。
kernel.height	number		核的高度，单位为像素。
kernel.kernel	Array.<number>		长度为 width*height 的数组，包含核值。
[kernel.scale]	number	sum	核的缩放，单位为像素。
[kernel.offset]	number	0	核的偏移，单位为像素。

示例

sharp(input)
  .convolve({
    width: 3,
    height: 3,
    kernel: [-1, 0, 1, -2, 0, 2, -1, 0, 1]
  })
  .raw()
  .toBuffer(function(err, data, info) {
    // data 包含卷积后表示输入图像与水平 Sobel 运算符的原始像素数据
  });

threshold

threshold([threshold], [options]) ⇒ Sharp

任何像素值大于或等于阈值的将设为 255，否则将设为 0。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[threshold]	number	128	在 0-255 范围内的值，表示将应用阈值的级别。
[options]	Object
[options.greyscale]	Boolean	true	转换为单通道灰度。
[options.grayscale]	Boolean	true	灰度的另一种拼写。

boolean

boolean(operand, operator, [options]) ⇒ Sharp

与操作数图像执行按位布尔操作。

此操作创建一个输出图像，其中每个像素是输入图像中对应像素的按位布尔 operation 结果。

抛出:

• Error 无效的参数

参数	类型	描述
operand	Buffer | string	包含图像数据的 Buffer 或包含图像文件路径的字符串。
operator	string	and、or 或 eor 之一，以执行相应的按位操作，如 C 逻辑运算符 &、`
[options]	Object
[options.raw]	Object	描述使用原始像素数据的操作数。
[options.raw.width]	number
[options.raw.height]	number
[options.raw.channels]	number

linear

linear([a], [b]) ⇒ Sharp

对图像应用线性公式 a * 输入 + b 来调整图像级别。

提供单个数字时，将用于所有图像通道。 提供数字数组时，数组长度必须与通道数匹配。

抛出:

• Error 无效的参数

参数	类型	默认	描述
[a]	number | Array.<number>	[]	乘数
[b]	number | Array.<number>	[]	偏移

示例

await sharp(input)
  .linear(0.5, 2)
  .toBuffer();

示例

await sharp(rgbInput)
  .linear(
    [0.25, 0.5, 0.75],
    [150, 100, 50]
  )
  .toBuffer();

recomb

recomb(inputMatrix) ⇒ Sharp

使用指定的矩阵重组图像。

抛出:

• Error 无效的参数

自: 0.21.1

参数	类型	描述
inputMatrix	Array.<Array.<number>>	3x3 或 4x4 重组矩阵

示例

sharp(input)
  .recomb([
   [0.3588, 0.7044, 0.1368],
   [0.2990, 0.5870, 0.1140],
   [0.2392, 0.4696, 0.0912],
  ])
  .raw()
  .toBuffer(function(err, data, info) {
    // data 包含应用矩阵后的原始像素数据
    // 在此示例输入下，已应用复古滤镜
  });

modulate

modulate([options]) ⇒ Sharp

通过亮度、饱和度、色相旋转和亮度转换图像。 亮度和亮度都在亮度上操作，不同之处在于 亮度是乘法的而亮度是加法的。

自: 0.22.1

参数	类型	描述
[options]	Object
[options.brightness]	number	亮度乘数
[options.saturation]	number	饱和度乘数
[options.hue]	number	色相旋转的度数
[options.lightness]	number	亮度加数

示例

// 将亮度增加 2 倍
const output = await sharp(input)
  .modulate({
    brightness: 2
  })
  .toBuffer();

示例

// 色相旋转 180 度
const output = await sharp(input)
  .modulate({
    hue: 180
  })
  .toBuffer();

示例

// 亮度增加 +50
const output = await sharp(input)
  .modulate({
    lightness: 50
  })
  .toBuffer();

示例

// 降低亮度和饱和度，同时色相旋转 90 度
const output = await sharp(input)
  .modulate({
    brightness: 0.5,
    saturation: 0.5,
    hue: 90,
  })
  .toBuffer();