图像操作

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();