Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Image

A class representing an Image. This uses operations from Sharp under the hood.

Hierarchy

  • Image

Index

Constructors

constructor

  • Constructs a new Image from raw Buffer data

    Parameters

    • data: ArrayBuffer | CreateOptions

      Raw image data as a buffer, or options to create a new image

    Returns Image

Methods

background

  • background(rgba: string | Color): this
  • Set the background for the embed, flatten and extend operations. The default background is {r: 0, g: 0, b: 0, alpha: 1}, black without transparency.

    Delegates to the color module, which can throw an Error but is liberal in what it accepts, clipping values to sensible min/max. The alpha value is a float between 0 (transparent) and 1 (opaque).

    Parameters

    • rgba: string | Color

      parsed by the color module to extract values for red, green, blue and alpha.

    Returns this

crop

  • Crop the resized image to the exact size specified, the default behaviour.

    Possible attributes of the optional sharp.gravity are north, northeast, east, southeast, south, southwest, west, northwest, center and centre.

    The experimental strategy-based approach resizes so one dimension is at its target length then repeatedly ranks edge regions, discarding the edge with the lowest score based on the selected strategy.

    • entropy: focus on the region with the highest Shannon entropy.
    • attention: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.
    const cropped = await new Image(input)
      .resize(200, 200)
      .crop(Image.strategy.entropy)
      .toBuffer()

    Parameters

    Returns any

    the Image instance

  • Crop to the specified width/height.

    Parameters

    • width: number

      width to crop to

    • Optional height: number

      height to crop to, defaults to proportional height

    • Optional crop: gravity | strategy

      the cropping strategy to use

    Returns any

    the Image instance

embed

  • Preserving aspect ratio, resize the image to the maximum width or height specified then embed on a background of the exact width and height specified.

    If the background contains an alpha value then WebP and PNG format output images will contain an alpha channel, even when the input image does not.

    const data = new Image(input)
      .resize(200, 300)
      .background({r: 0, g: 0, b: 0, alpha: 0})
      .embed()
      .toBuffer();

    Parameters

    • Optional gravity: gravity

      embed to an edge/corner, defaults to center.

    Returns this

extend

  • Pads image by number of pixels. If image is 200px wide, extend(20) makes it 220px wide

    Parameters

    • extend: number | ExtendOptions

      If numeric, pads all sides of an image.

      Otherwise, pad each side by the specified amount.

    Returns this

flatten

  • flatten(flatten: boolean): this
  • Merge alpha transparency channel, if any, with background.

    Parameters

    • flatten: boolean

      Defaults to true

    Returns this

jpeg

  • Output image to JPEG

     * // Convert any input to very high quality JPEG output
    const data = await new Image(input)
      .jpeg({
        quality: 100,
        chromaSubsampling: '4:4:4'
      })
      .toBuffer();

    Parameters

    Returns this

max

  • max(): this
  • Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to the width and height specified.

    Both width and height must be provided via resize otherwise the behavior will default to crop.

    const data = await new ImageinputBuffer)
      .resize(200, 200)
      .max()
      .toBuffer()

    Returns this

metadata

negate

  • negate(): this

overlayWith

  • Overlay (composite) an image over the processed (resized, extracted etc.) image.

    The overlay image must be the same size or smaller than the processed image. If both top and left options are provided, they take precedence over gravity.

    If the overlay image contains an alpha channel then composition with premultiplication will occur.

    Parameters

    • overlay: ArrayBuffer | Image

      image to overlay

    • Optional options: OverlayOptions

      control how the overlay is composited

    Returns this

png

  • Use these PNG options for output image.

    PNG output is always full colour at 8 or 16 bits per pixel. Indexed PNG input at 1, 2 or 4 bits per pixel is converted to 8 bits per pixel.

    // Convert any input to PNG output
    const data = await new Image(input)
      .png()
      .toBuffer();

    Parameters

    • Optional options: PngOptions

      Compression and encoding options

    Returns this

resize

  • resize(width?: number, height?: number, options?: ResizeOptions): this
  • Resize image to width x height. By default, the resized image is center cropped to the exact size specified.

    Parameters

    • Optional width: number

      Width in pixels of the resulting image. Pass undefined or null to auto-scale the width to match the height.

    • Optional height: number

      Height in pixels of the resulting image. Pass undefind or null to auto-scale the height to match the width.

    • Optional options: ResizeOptions

      Resize options

    Returns this

scale

  • scale(width?: number, height?: number, options?: ScaleOptions): this
  • Scale image to width x height. This does not crop the image, it scales it to fit the specified width and height, and keeps the aspect ratio by default.

    Parameters

    • Optional width: number

      Width in pixels of the resulting image. Pass undefined or null to auto-scale the width to match the height.

    • Optional height: number

      Height in pixels of the resulting image. Pass undefind or null to auto-scale the height to match the width.

    • Optional options: ScaleOptions

      Scale options

    Returns this

toBuffer

toImage

  • toImage(): Promise<Image>

webp

  • Output to webp.

    // Convert any input to lossless WebP output
    const data = await new Image(input)
      .webp({ lossless: true })
      .toBuffer();

    Parameters

    • Optional options: WebpOptions

      webp encoding options, quality, etc

    Returns this

withMetadata

  • withMetadata(options?: object): this
  • Include all metadata (EXIF, XMP, IPTC) from the input image in the output image. The default behaviour, when withMetadata is not used, is to strip all metadata and convert to the device-independent sRGB colour space. This will also convert to and add a web-friendly sRGB ICC profile.

    Parameters

    • Optional options: object

      options.orientation: value between 1 and 8, used to update the EXIF Orientation tag.

    Returns this

withoutEnlargement

  • withoutEnlargement(flag?: boolean): this
  • Do not enlarge the output image if the input image width or height are already less than the required dimensions. This is equivalent to GraphicsMagick's > geometry option: "change the dimensions of the image only if its width or height exceeds the geometry specification". Use with max() to preserve the image's aspect ratio The default behaviour before function call is false, meaning the image will be enlarged.

    Parameters

    • Optional flag: boolean

      Toggle option

    Returns this

Generated using TypeDoc