图片操作

rotate

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

旋转输出图片。

🌐 Rotate the output image.

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

🌐 The provided angle is converted to a valid positive degree rotation. For example, -450 will produce a 270 degree rotation.

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

🌐 When rotating by an angle other than a multiple of 90, the background colour can be provided with the background option.

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

🌐 For backwards compatibility, if no angle is provided, .autoOrient() will be called.

每个管道中只会发生一次旋转（除了最初调用时不带参数的使用 EXIF 数据进行方向调整）。同一管道中之前对 rotate 的调用会被忽略。

🌐 Only one rotation can occur per pipeline (aside from an initial call without arguments to orient via EXIF data). Previous calls to rotate in the same pipeline will be ignored.

多页图片只能旋转 180 度。

🌐 Multi-page images can only be rotated by 180 degrees.

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

🌐 Method order is important when rotating, resizing and/or extracting regions, for example .rotate(x).extract(y) will produce a different result to .extract(y).rotate(x).

投掷:

• 错误 参数无效

参数	类型	默认	描述
[angle]	数字	自动	旋转角度。
[options]	对象		如果存在，是一个具有可选属性的对象。
[options.background]	字符串 |对象	“\”#00000\“”	由[color]（https://www.npmjs.org/package/color）模块解析以提取红、绿、蓝和阿尔法的值。|

示例

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 标签自动调整方向，然后删除该标签。支持镜像，可能会推断出翻转操作的使用。

🌐 Auto-orient based on the EXIF Orientation tag, then remove the tag. Mirroring is supported and may infer the use of a flip operation.

只有 EXIF Orientation 标签会被考虑；其他地方的方向信息，例如 XMP tiff:Orientation 元素，则不受影响，仍由使用者负责处理。

🌐 Only the EXIF Orientation tag is considered; orientation carried in other places, such as an XMP tiff:Orientation element, is left untouched and remains the responsibility of the consumer.

rotate(angle) 和 flip() 或 flop() 的前后使用无论调用顺序如何，逻辑上都会在自动定向之后发生。

🌐 Previous or subsequent use of rotate(angle) and either flip() or flop() will logically occur after auto-orientation, regardless of call order.

示例

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

Example

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

flip

flip([flip]) ⇒ Sharp

沿 x 轴将图片垂直（上下）翻转。
如果有旋转，这总是先发生的。

🌐 Mirror the image vertically (up-down) about the x-axis. This always occurs before rotation, if any.

对于多页图片，此操作无法正常工作。

🌐 This operation does not work correctly with multi-page images.

参数	类型	默认值
[flip]	布尔值	true

示例

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

flop

flop([flop]) ⇒ Sharp

沿 y 轴将图片水平（左右）镜像翻转。如果有旋转，这总是在旋转之前发生。

🌐 Mirror the image horizontally (left-right) about the y-axis. This always occurs before rotation, if any.

参数	类型	默认值
[flop]	布尔值	true

示例

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

affine

affine(matrix, [options]) ⇒ Sharp

对图片执行仿射变换。这个操作总是在调整大小、提取和旋转之后进行（如果有的话）。

🌐 Perform an affine transform on an image. This operation will always occur after resizing, extraction and rotation, if any.

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

🌐 You must provide an array of length 4 or a 2x2 affine transformation matrix. By default, new pixels are filled with a black background. You can provide a background colour with the background option. A particular interpolator may also be specified. Set the interpolator option to an attribute of the sharp.interpolators Object e.g. sharp.interpolators.nohalo.

对于 2x2 矩阵，变换为：

🌐 In the case of a 2x2 matrix, the transform is:

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

where:

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

投掷:

• 错误 参数无效

自: 0.27.0

参数	类型	默认	描述
矩阵	数组.<数组.<数>>|数组.<数>		仿射变换矩阵
[options]	对象		如果存在，是一个具有可选属性的对象。
[options.background]	字符串 |对象	“#000000”	由 [color]（https://www.npmjs.org/package/color） 模块解析以提取红、绿、蓝和 alpha 的值。
[options.idx]	数字	0	输入水平偏移量
[options.idy]	数字	0	输入垂直偏移量
[options.odx]	数字	0	输出水平偏移量
[options.ody]	数字	0	输出垂直偏移量
[options.插值器]	字符串	锐利。插值器.双三次曲线	插值器

示例

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]) ⇒ Sharp

锐化图片。

🌐 Sharpen the image.

当不带参数使用时，对输出图片执行快速、温和的锐化。

🌐 When used without parameters, performs a fast, mild sharpen of the output image.

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

🌐 When a sigma is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space. Fine-grained control over the level of sharpening in “flat” (m1) and “jagged” (m2) areas is available.

查看 libvips 锐化 操作。

🌐 See libvips sharpen operation.

投掷:

• 错误 参数无效

参数	类型	默认值	描述
[options]	对象		如果存在，是一个带有属性的对象
[options.sigma]	数字		高斯掩膜的 sigma 值，范围在 0.000001 到 10 之间
[options.m1]	数字	1.0	对“平坦”区域应用的锐化程度，范围在 0 到 1000000 之间
[options.m2]	数字	2.0	对“锯齿状”区域应用的锐化程度，范围在 0 到 1000000 之间
[options.x1]	数字	2.0	“平坦”和“锯齿状”之间的阈值，范围在 0 到 1000000 之间
[options.y2]	数字	10.0	最大亮化量，范围在 0 到 1000000 之间
[options.y3]	数字	20.0	最大加暗量，范围在 0 到 1000000 之间

示例

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

Example

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

Example

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

median

median([size]) ⇒ Sharp

应用中值滤波。
如果不使用参数，默认的窗口是3x3。

🌐 Apply median filter. When used without parameters the default window is 3x3.

投掷:

• 错误 参数无效

参数	类型	默认值	描述
[size]	数字	3	方形遮罩大小：size x size

示例

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

Example

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

blur

blur([options]) ⇒ Sharp

模糊图片。

🌐 Blur the image.

当不带参数使用时，执行快速 3x3 框模糊（相当于框线性滤镜）。

🌐 When used without parameters, performs a fast 3x3 box blur (equivalent to a box linear filter).

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

🌐 When a sigma is provided, performs a slower, more accurate Gaussian blur.

投掷:

• 错误 参数无效

参数	类型	默认值	描述
[options]	对象 | 数字 | 布尔值
[options.sigma]	数字		高斯掩码的 sigma 值，范围在 0.3 到 1000 之间，其中 sigma = 1 + radius / 2。
[options.precision]	字符串	"'整数'"	操作的精确度，可以是：整数、浮点、近似。
[options.minAmplitude]	数字	0.2	范围在 0.001 到 1 之间。值越小，生成的掩码越大、越精确。

示例

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

Example

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

dilate

dilate([width]) ⇒ Sharp

使用扩张形态运算符扩展前景对象。

🌐 Expand foreground objects using the dilate morphological operator.

投掷:

• 错误 参数无效

参数	类型	默认值	描述
[width]	数字	1	膨胀宽度，单位为像素。

示例

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

erode

erode([width]) ⇒ Sharp

使用侵蚀形态运算符缩小前景对象。

🌐 Shrink foreground objects using the erode morphological operator.

投掷:

• 错误 参数无效

参数	类型	默认值	描述
[width]	数字	1	以像素为单位的腐蚀宽度。

示例

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

flatten

flatten([options]) ⇒ Sharp

将 Alpha 透明度通道（如果有）与背景合并，然后删除 Alpha 通道。

🌐 Merge alpha transparency channel, if any, with a background, then remove the alpha channel.

另请参见 removeAlpha。

🌐 See also removeAlpha.

参数	类型	默认	描述
[options]	对象
[options.background]	字符串 |对象	“{r： 0， g： 0， b： 0}”	背景颜色，由[color]（https://www.npmjs.org/package/color）模块解析，默认为黑色。|

示例

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

unflatten

unflatten()

确保图片有一个 alpha 通道，并且把所有白色像素值设为完全透明。

🌐 Ensure the image has an alpha channel with all white pixel values made fully transparent.

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

🌐 Existing alpha channel values for non-white pixels remain unchanged.

自：0.32.1
示例

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

Example

await sharp(rgbInput)
  .threshold(128, { grayscale: false }) // converter bright pixels to white
  .unflatten()
  .toBuffer();

gamma

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

通过在调整大小前以 1/gamma 的系数降低编码（变暗），然后在调整大小后以 gamma 的系数增加编码（变亮）来应用伽马校正。这样可以提高非线性色彩空间中调整大小图片的感知亮度。在应用伽马校正时，JPEG 和 WebP 输入图片将无法利用加载时缩小的性能优化。

🌐 Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of 1/gamma then increasing the encoding (brighten) post-resize at a factor of gamma. This can improve the perceived brightness of a resized image in non-linear colour spaces. JPEG and WebP input images will not take advantage of the shrink-on-load performance optimisation when applying a gamma correction.

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

🌐 Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.

投掷:

• 错误 参数无效

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

negate

negate([options]) ⇒ Sharp

生成图片的“负片”形式。

🌐 Produce the “negative” of the image.

参数	类型	默认值	描述
[options]	对象
[options.alpha]	布尔值	true	是否否定任何 alpha 通道

示例

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

Example

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

normalise

normalise([options]) ⇒ Sharp

通过扩展输出图片的亮度以覆盖整个动态范围来增强输出图片的对比度。

🌐 Enhance output image contrast by stretching its luminance to cover a full dynamic range.

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

🌐 Uses a histogram-based approach, taking a default range of 1% to 99% to reduce sensitivity to noise at the extremes.

低于 lower 百分位的亮度值会被剪切为零而曝光不足。高于 upper 百分位的亮度值会被剪切到最大像素值而过曝。

🌐 Luminance values below the lower percentile will be underexposed by clipping to zero. Luminance values above the upper percentile will be overexposed by clipping to the max pixel value.

参数	类型	默认值	描述
[options]	对象
[options.lower]	数字	1	低于该百分位的亮度值会曝光不足
[options.upper]	数字	99	高于该百分位的亮度值会曝光过度

示例

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

Example

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

normalize

normalize([options]) ⇒ Sharp

标准化的替代拼写。

🌐 Alternative spelling of normalise.

参数	类型	默认值	描述
[options]	对象
[options.lower]	数字	1	低于该百分位的亮度值会曝光不足
[options.upper]	数字	99	高于该百分位的亮度值会曝光过度

示例

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

clahe

clahe(options) ⇒ Sharp

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

🌐 Perform contrast limiting adaptive histogram equalization CLAHE.

一般来说，这会通过显示较暗的细节来增强图片的清晰度。

🌐 This will, in general, enhance the clarity of the image by bringing out darker details.

投掷:

• 错误 参数无效

自：0.28.3

参数	类型	默认值	描述
options	对象
options.width	数字		搜索窗口的整数宽度，单位像素，范围在1到65536之间。
options.height	数字		搜索窗口的整数高度，单位像素，范围在1到65536之间。
[options.maxSlope]	数字	3	增亮的整数等级，范围0到100，其中0表示禁用对比度限制。

示例

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

convolve

convolve(kernel) ⇒ Sharp

将图片与指定的内核进行卷积。

🌐 Convolve the image with the specified kernel.

投掷:

• 错误 参数无效

参数	类型	默认值	描述
kernel	对象
kernel.width	数字		核心的宽度（像素）。
kernel.height	数字		核心的高度（像素）。
kernel.kernel	数组.<数字>		长度为 width*height 的数组，包含核心值。
[kernel.scale]	数字	sum	核心的缩放值（像素）。
[kernel.offset]	数字	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 contains the raw pixel data representing the convolution
    // of the input image with the horizontal Sobel operator
  });

threshold

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

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

🌐 Any pixel value greater than or equal to the threshold value will be set to 255, otherwise it will be set to 0.

投掷:

• 错误 参数无效

参数	类型	默认值	描述
[threshold]	数字	128	表示应用阈值的级别，取值范围为 0-255。
[options]	对象
[options.greyscale]	布尔值	true	转换为单通道灰度图。
[options.grayscale]	布尔值	true	greyscale 的另一种拼写方式。

boolean

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

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

🌐 Perform a bitwise boolean operation with operand image.

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

🌐 This operation creates an output image where each pixel is the result of the selected bitwise boolean operation between the corresponding pixels of the input images.

投掷:

• 错误 参数无效

参数	类型	描述
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 应用于图片以调整图片亮度。

🌐 Apply the linear formula a * input + b to the image to adjust image levels.

当只提供一个数字时，它将用于所有图片通道。 当提供一个数字数组时，数组长度必须与通道数量匹配。

🌐 When a single number is provided, it will be used for all image channels. When an array of numbers is provided, the array length must match the number of channels.

投掷:

• 错误 参数无效

参数	类型	默认	描述
[a]	数字 |数组。<数>	[]	乘数
[b]	数字|数组。<数>	[]	偏移

示例

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

Example

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

recomb

recomb(inputMatrix) ⇒ Sharp

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

🌐 Recombine the image with the specified matrix.

投掷:

• 错误 参数无效

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

modulate

modulate([options]) ⇒ Sharp

使用亮度、饱和度、色相旋转和明度来转换图片。亮度和明度都作用于亮度值，不同的是亮度是乘法的，而明度是加法的。

🌐 Transforms the image using brightness, saturation, hue rotation, and lightness. Brightness and lightness both operate on luminance, with the difference being that brightness is multiplicative whereas lightness is additive.

自：0.22.1

参数	类型	描述
[options]	对象
[options.brightness]	数字	亮度倍增器
[options.saturation]	数字	饱和度倍增器
[options.hue]	数字	色相旋转的角度
[options.lightness]	数字	亮度增量

示例

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

Example

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

Example

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

Example

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