输入元数据

metadata

元数据([回调]) ⇒ Promise.<Object> | Sharp

¥metadata([callback]) ⇒ Promise.<Object> | Sharp

快速访问（未缓存的）图片元数据，无需解码任何压缩像素数据。

¥Fast access to (uncached) image metadata without decoding any compressed pixel data.

这是从输入图片的标题中读取的。它不考虑应用于输出图片的任何操作，例如调整大小或旋转。

¥This is read from the header of the input image. It does not take into consideration any operations to be applied to the output image, such as resize or rotate.

响应中的维度将尊重 构造函数参数 的 page 和 pages 属性。

¥Dimensions in the response will respect the page and pages properties of the constructor parameters.

如果未提供 callback，则返回 Promise。

¥A Promise is returned when callback is not provided.

• format：用于解压缩图片数据的解码器的名称，例如 jpeg、png、webp、gif、svg

  ¥format: Name of decoder used to decompress image data e.g. jpeg, png, webp, gif, svg

• size：图片的总大小（以字节为单位），仅适用于流和缓冲区输入

  ¥size: Total size of image in bytes, for Stream and Buffer input only

• width：宽度像素数（不考虑 EXIF 方向，请参见下面的示例）

  ¥width: Number of pixels wide (EXIF orientation is not taken into consideration, see example below)

• height：高像素数（不考虑 EXIF 方向，请参见下面的示例）

  ¥height: Number of pixels high (EXIF orientation is not taken into consideration, see example below)

• space：色彩空间解释的名称，例如 srgb、rgb、cmyk、lab、b-w …

  ¥space: Name of colour space interpretation e.g. srgb, rgb, cmyk, lab, b-w …

• channels：乐队数量例如 3 代表 sRGB，4 代表 CMYK

  ¥channels: Number of bands e.g. 3 for sRGB, 4 for CMYK

• depth：像素深度格式的名称，例如 uchar、char、ushort、float、…

  ¥depth: Name of pixel depth format e.g. uchar, char, ushort, float …

• density：每英寸像素数 (DPI)（如果有）

  ¥density: Number of pixels per inch (DPI), if present

• chromaSubsampling：包含 JPEG 色度子采样的字符串，RGB 为 4:2:0 或 4:4:4，CMYK 为 4:2:0:4 或 4:4:4:4

  ¥chromaSubsampling: String containing JPEG chroma subsampling, 4:2:0 or 4:4:4 for RGB, 4:2:0:4 or 4:4:4:4 for CMYK

• isProgressive：指示图片是否使用逐行扫描隔行扫描的布尔值

  ¥isProgressive: Boolean indicating whether the image is interlaced using a progressive scan

• isPalette：布尔值，表示图片是否基于调色板（GIF、PNG）。

  ¥isPalette: Boolean indicating whether the image is palette-based (GIF, PNG).

• bitsPerSample：每个通道（GIF、PNG、HEIF）每个样本的位数。

  ¥bitsPerSample: Number of bits per sample for each channel (GIF, PNG, HEIF).

• pages：图片中包含的页面/帧数，支持 TIFF、HEIF、PDF、动画 GIF 和动画 WebP

  ¥pages: Number of pages/frames contained within the image, with support for TIFF, HEIF, PDF, animated GIF and animated WebP

• pageHeight：多页图片中每页高的像素数。

  ¥pageHeight: Number of pixels high each page in a multi-page image will be.

• loop：动画图片循环次数，零表示连续循环。

  ¥loop: Number of times to loop an animated image, zero refers to a continuous loop.

• delay：动画图片中每个页面之间的延迟（以毫秒为单位），以整数数组形式提供。

  ¥delay: Delay in ms between each page in an animated image, provided as an array of integers.

• pagePrimary：HEIF 图片中主页的编号

  ¥pagePrimary: Number of the primary page in a HEIF image

• levels：以对象数组形式提供的多级图片中每个级别的详细信息，需要编译为支持 OpenSlide 的 libvips

  ¥levels: Details of each level in a multi-level image provided as an array of objects, requires libvips compiled with support for OpenSlide

• subifds：OME-TIFF 图片中的子图片文件目录的数量

  ¥subifds: Number of Sub Image File Directories in an OME-TIFF image

• background：如果存在，则为 PNG (bKGD) 和 GIF 图片的默认背景颜色

  ¥background: Default background colour, if present, for PNG (bKGD) and GIF images

• compression：用于压缩 HEIF 文件的编码器，av1 (AVIF) 或 hevc (HEIC)

  ¥compression: The encoder used to compress an HEIF file, av1 (AVIF) or hevc (HEIC)

• resolutionUnit：分辨率（密度）单位，inch 或 cm（如果存在）

  ¥resolutionUnit: The unit of resolution (density), either inch or cm, if present

• hasProfile：指示是否存在嵌入式 ICC 配置文件的布尔值

  ¥hasProfile: Boolean indicating the presence of an embedded ICC profile

• hasAlpha：指示 alpha 透明度通道是否存在的布尔值

  ¥hasAlpha: Boolean indicating the presence of an alpha transparency channel

• orientation：EXIF Orientation 标头的数值（如果存在）

  ¥orientation: Number value of the EXIF Orientation header, if present

• exif：包含原始 EXIF 数据的缓冲区（如果存在）

  ¥exif: Buffer containing raw EXIF data, if present

• icc：包含原始 ICC 配置文件数据的缓冲区（如果存在）

  ¥icc: Buffer containing raw ICC profile data, if present

• iptc：包含原始 IPTC 数据的缓冲区（如果存在）

  ¥iptc: Buffer containing raw IPTC data, if present

• xmp：包含原始 XMP 数据的缓冲区（如果存在）

  ¥xmp: Buffer containing raw XMP data, if present

• tifftagPhotoshop：包含原始 TIFFTAG_PHOTOSHOP 数据的缓冲区（如果存在）

  ¥tifftagPhotoshop: Buffer containing raw TIFFTAG_PHOTOSHOP data, if present

• formatMagick：包含通过 *magick 加载的图片格式的字符串

  ¥formatMagick: String containing format for images loaded via *magick

• comments：表示 PNG 文本块的关键字/文本对数组（如果存在）。

  ¥comments: Array of keyword/text pairs representing PNG text blocks, if present.

参数	类型	描述
[callback]	function	使用参数 (err, metadata) 调用

示例

¥Example

const metadata = await sharp(input).metadata();

示例

¥Example

const image = sharp(inputJpg);
image
  .metadata()
  .then(function(metadata) {
    return image
      .resize(Math.round(metadata.width / 2))
      .webp()
      .toBuffer();
  })
  .then(function(data) {
    // data contains a WebP image half the width and height of the original JPEG
  });

示例

¥Example

// Get dimensions taking EXIF Orientation into account.
const { autoOrient } = await sharp(input).metadata();
const { width, height } = autoOrient;

stats

stats([callback]) ⇒ Promise.<Object>

访问图片中每个通道的像素派生图片统计数据。如果未提供 callback，则返回 Promise。

¥Access to pixel-derived image statistics for every channel in the image. A Promise is returned when callback is not provided.

• channels：图片中每个通道的通道统计数据数组。每个通道统计包含

  ¥channels: Array of channel statistics for each channel in the image. Each channel statistic contains

  • min（通道中的最小值）

    ¥min (minimum value in the channel)

  • max（通道中的最大值）

    ¥max (maximum value in the channel)

  • sum（通道中所有值的总和）

    ¥sum (sum of all values in a channel)

  • squaresSum（通道中的平方值之和）

    ¥squaresSum (sum of squared values in a channel)

  • mean（通道中值的平均值）

    ¥mean (mean of the values in a channel)

  • stdev（通道中值的标准差）

    ¥stdev (standard deviation for the values in a channel)

  • minX（最小值所在像素之一的 x 坐标）

    ¥minX (x-coordinate of one of the pixel where the minimum lies)

  • minY（最小值所在像素之一的 y 坐标）

    ¥minY (y-coordinate of one of the pixel where the minimum lies)

  • maxX（最大值所在像素之一的 x 坐标）

    ¥maxX (x-coordinate of one of the pixel where the maximum lies)

  • maxY（最大值所在像素之一的 y 坐标）

    ¥maxY (y-coordinate of one of the pixel where the maximum lies)

• isOpaque：图片是完全不透明的吗？如果图片没有 Alpha 通道或每个像素完全不透明，则为 true。

  ¥isOpaque: Is the image fully opaque? Will be true if the image has no alpha channel or if every pixel is fully opaque.

• entropy：基于直方图的灰度熵估计，丢弃 alpha 通道（如果有）。

  ¥entropy: Histogram-based estimation of greyscale entropy, discarding alpha channel if any.

• sharpness：基于拉普拉斯卷积的标准差估计灰度锐度，丢弃 alpha 通道（如果有）。

  ¥sharpness: Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any.

• dominant：包含基于 4096-bin 3D 直方图的最主要 sRGB 颜色的对象。

  ¥dominant: Object containing most dominant sRGB colour based on a 4096-bin 3D histogram.

注意：统计数据源自原始输入图片。对图片执行的任何操作都必须首先写入缓冲区，以便对结果运行 stats（参见第三个示例）。

¥Note: Statistics are derived from the original input image. Any operations performed on the image must first be written to a buffer in order to run stats on the result (see third example).

参数	类型	描述
[callback]	function	使用参数 (err, stats) 调用

示例

¥Example

const image = sharp(inputJpg);
image
  .stats()
  .then(function(stats) {
     // stats contains the channel-wise statistics array and the isOpaque value
  });

示例

¥Example

const { entropy, sharpness, dominant } = await sharp(input).stats();
const { r, g, b } = dominant;

示例

¥Example

const image = sharp(input);
// store intermediate result
const part = await image.extract(region).toBuffer();
// create new instance to obtain statistics of extracted region
const stats = await sharp(part).stats();