教程菜单 本页目录

rotate

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

根据 EXIF 方向标记,以明确的角度或自动定向的方式旋转输出图像。

如果提供了角度,则将其转换为有效的正度旋转。例如,-450 将产生 270 度旋转。

当以 90 的倍数以外的角度旋转时,可以使用背景选项提供背景颜色。

如果未提供角度,则根据 EXIF 数据确定。支持镜像,并可能推断出使用了翻转操作。

使用不带角度的旋转将删除 EXIF 方向标记(如果有)。

每个管道只能发生一次旋转。同一管道中先前的旋转调用将被忽略。

多页图像只能旋转 180 度。

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

Throws:

  • 错误 参数无效
参数类型默认描述
[angle]numberauto旋转角度。
[options]Object如果存在,则为具有可选属性的对象。
[options.background]string | Object""#000000""由颜色模块解析以提取红色、绿色、蓝色和 alpha 的值。

示例

const pipeline = sharp()
  .rotate()
  .resize(null, 200)
  .toBuffer(function (err, outputBuffer, info) {
    // outputBuffer contains 200px high JPEG image data,
    // auto-rotated using EXIF Orientation tag
    // info.width and info.height contain the dimensions of the resized image
  });
readableStream.pipe(pipeline);

示例

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

flip

flip([flip]) ⇒ Sharp

围绕 x 轴垂直(上下)镜像图像。此操作始终在旋转之前发生(如果有)。

此操作无法正确处理多页图像。

参数类型默认
[flip]Booleantrue

示例

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

flop

flop([flop]) ⇒ Sharp

关于 y 轴水平(左右)镜像图像。这总是在旋转之前发生(如果有的话)。

参数类型默认
[flop]Booleantrue

示例

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

affine

affine(matrix, [options]) ⇒ Sharp

对图像执行仿射变换。此操作将始终在调整大小、提取和旋转(如果有)后发生。

您必须提供长度为 4 的数组或 2x2 仿射变换矩阵。默认情况下,新像素将用黑色背景填充。您可以使用 background 选项提供背景颜色。还可以指定特定的插值器。将插值器选项设置为 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) 是左上角。

Throws:

  • 错误 参数无效

: 0.27.0

参数类型默认描述
matrixArray.仿射变换矩阵
[options]Object如果存在,则为具有可选属性的对象。
[options.background]String | Object"#000000"由颜色模块解析以提取红色、绿色、蓝色和 alpha 的值。
[options.idx]Number0输入水平偏移
[options.idy]Number0输入垂直偏移
[options.odx]Number0输出水平偏移
[options.ody]Number0输出垂直偏移
[options.interpolator]Stringsharp.interpolators.bicubic插值器

示例

const pipeline = sharp()
  .affine([[1, 0.3], [0.1, 0.7]], {
     background: 'white',
     interpolator: sharp.interpolators.nohalo
  })
  .toBuffer((err, outputBuffer, info) => {
     // outputBuffer contains the transformed image
     // info.width and info.height contain the new dimensions
  });

inputStream
  .pipe(pipeline);

sharpen

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

锐化图像。

当不带参数使用时,对输出图像进行快速、适度的锐化。

当提供 sigma 时,在 LAB 颜色空间中执行较慢但更准确的 L 通道锐化。可以对“平坦”(m1) 和“锯齿状”(m2) 区域的锐化级别进行细粒度控制。

请参阅 libvips 锐化操作。

Throws:

  • 错误 参数无效
参数类型默认描述
[options]Object | number如果存在,则为具有属性
[options.sigma]number高斯掩模的 sigma,其中 sigma = 1 + radius / 2,介于 0.000001 和 10 之间
[options.m1]number1.0应用于“平坦”区域的锐化级别,介于 0 和 1000000 之间
[options.m2]number2.0应用于“锯齿状”区域的锐化级别,介于 0 和 1000000 之间
[options.x1]number2.0“平坦”和“锯齿状”之间的阈值,介于 0 和1000000
[options.y2]number10.0最大增亮量,介于 0 和 1000000 之间
[options.y3]number20.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。

Throws:

  • 错误 参数无效
参数类型默认描述
[size]number3方形蒙版大小:大小 x大小

示例

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

示例

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

blur

blur([sigma]) ⇒ Sharp

模糊图像。

当不带参数使用时,执行快速 3x3 框模糊(相当于框线性滤波器)。

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

Throws:

  • 错误 参数无效
参数类型说明
[sigma]number0.3 到 1000 之间的值,表示高斯掩模的 sigma,其中 sigma = 1 + radius / 2.

示例

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

示例

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

flatten

flatten([options]) ⇒ Sharp

将 alpha 透明通道(如果有)与背景合并,然后删除 alpha 通道。

另请参阅 removeAlpha。

参数类型默认说明
[options]Object
[options.background]string | Object"{r: 0, g: 0, b: 0}"背景颜色,由颜色模块解析,默认为黑色。

示例

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 }) // converter bright pixels to white
  .unflatten()
  .toBuffer();

gamma

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

通过以 1/gamma 的倍数减少编码(变暗)调整大小,然后以 gamma 的倍数增加编码(变亮)调整大小后,应用伽马校正。这可以提高非线性色彩空间中调整大小后图像的感知亮度。应用伽马校正时,JPEG 和 WebP 输入图像将不会利用加载时缩小的性能优化。

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

Throws:

  • 错误 参数无效
参数类型默认描述
[gamma]number2.2值介于 1.0 和 3.0 之间。
[gammaOut]number值介于 1.0 和 3.0 之间。(可选,默认与伽马相同)

negate

negate([options]) ⇒ Sharp

生成图像的“负片”。

参数类型默认说明
[options]Object
[options.alpha]Booleantrue是否否定任何 alpha通道

示例

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

示例

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

normalise

normalise([options]) ⇒ Sharp

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

使用基于直方图的方法,采用 1% 到 99% 的默认范围来降低对极端噪声的敏感度。

低于下百分位数的亮度值将因剪切为零而曝光不足。高于上百分位数的亮度值将因剪切至最大像素值而过度曝光。

参数类型默认说明
[options]Object
[options.lower]number1亮度值低于该百分位数时将曝光不足。
[options.upper]number99亮度值超过该百分位数时将过度曝光。

示例

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]number1亮度值低于该百分位数时将曝光不足。
[options.upper]number99亮度值超过该百分位数时将过度曝光。

示例

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

clahe

clahe(options) ⇒ Sharp

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

这通常会通过显示较暗的细节来增强图像的清晰度。

Throws:

  • 错误 参数无效

: 0.28.3

参数类型默认说明
optionsObject
options.widthnumber搜索窗口的整数宽度(以像素为单位)。
options.heightnumber搜索窗口的整数高度(以像素为单位)。
[options.maxSlope]number3亮度的整数级别,介于 0 和 100 之间,其中 0 表示禁用对比度限制。

示例

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

convolve

convolve(kernel) ⇒ Sharp

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

Throws:

  • 错误 参数无效
参数类型默认描述
kernelObject
kernel.widthnumber内核的宽度(以像素为单位)。
kernel.heightnumber内核的高度(以像素为单位)。
kernel.kernelArray.包含内核值的长度为 width*height 的数组。
[kernel.scale]numbersum内核的比例(以像素为单位)。
[kernel.offset]number0内核的偏移量(以像素为单位)。

示例

sharp(input)
  .convolve({
    width: 3,
    height: 3,
    kernel: [-1, 0, 1, -2, 0, 2, -1, 0, 1]
  })
  .raw()
  .toBuffer(function(err, data, info) {
    // data contains the raw pixel data representing the convolution
    // of the input image with the horizontal Sobel operator
  });

threshold

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

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

Throws:

  • 错误无效参数
参数类型默认描述
[threshold]number1280-255 范围内的值,表示将应用阈值的级别。
[options]Object
[options.greyscale]Booleantrue转换为单通道灰度。
[options.grayscale]Booleantrue灰度的替代拼写。

boolean

boolean(操作数,操作符,[选项]) ⇒ Sharp

对操作数图像执行按位布尔运算。

此操作创建一个输出图像,其中每个像素都是输入图像相应像素之间所选按位布尔运算的结果。

Throws:

  • 错误 参数无效
参数类型描述
operandBuffer | string包含图像数据的缓冲区或包含图像文件路径的字符串。
operatorstringand、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 应用于图像以调整图像级别。

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

Throws:

  • 错误 参数无效
参数类型默认描述
[a]number | Array.[]乘数
[b]number | Array.[]偏移量

示例

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

将图像与指定的矩阵重新组合。

Throws:

  • 错误 参数无效

: 0.21.1

参数类型描述
inputMatrixArray.3x3 重组矩阵

示例

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 contains the raw pixel data after applying the matrix
    // With this example input, a sepia filter has been applied
  });

modulate

modulate([options]) ⇒ Sharp

使用亮度、饱和度、色调旋转和亮度转换图像。亮度和亮度都对亮度进行操作,不同之处在于亮度是乘法,而亮度是加法。

由于: 0.22.1

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

示例

// increase brightness by a factor of 2
const output = await sharp(input)
  .modulate({
    brightness: 2
  })
  .toBuffer();

示例

// hue-rotate by 180 degrees
const output = await sharp(input)
  .modulate({
    hue: 180
  })
  .toBuffer();

示例

// increase lightness by +50
const output = await sharp(input)
  .modulate({
    lightness: 50
  })
  .toBuffer();

示例

// decrease brightness and saturation while also hue-rotating by 90 degrees
const output = await sharp(input)
  .modulate({
    brightness: 0.5,
    saturation: 0.5,
    hue: 90,
  })
  .toBuffer();
本页目录