DOCSEARCHbyAlgolia
Submit Docs

smartcrop.js

repository·main·Indexed 12 days ago

https://github.com/jwagner/smartcrop.js

A content-aware image cropping algorithm for browsers, Node.js, and CLI. It identifies the most visually interesting crops using the `smartcrop.crop()` API and supports custom region boosting to prioritize areas like faces. Version 2.0.5.

Tokens
1.1K
Snippets
4
Records
6
Agent score
46%

What's inside smartcrop.js

  1. Boost specific regions (e.g., faces)

    main

    The boost option allows you to manually increase the importance of specific areas in an image. This is commonly used to ensure faces are included in the crop. Each boost object defines a rectangular region and a weight (between 0 and 1). The impact of the boost is proportional to both its weight and its area.

    {
  x: 11,      // pixels from the left side
  y: 20,      // pixels from the top
  width: 32,  // pixels
  height: 32, // pixels
  weight: 1   // in the range [0, 1]
}

  2. Install smartcrop.js

    main

    You can install smartcrop.js via npm or by downloading the source file directly from the repository.

    Note on Promises: smartcrop.js requires Promise support. For older browsers, use a polyfill like promise-polyfill or manually set smartcrop.Promise to a library like bluebird.

    npm install smartcrop

  3. Use smartcrop.js in Node.js

    main

    To use smartcrop.js in a Node.js environment, it is recommended to use one of the following wrappers that handle image processing via specialized libraries:

    • smartcrop-gm: Uses ImageMagick via gm.
    • smartcrop-sharp: Uses libvips via sharp.

    You can also use the smartcrop-cli for command-line operations.

  4. Integrate face detection with smartcrop.js

    main

    The core smartcrop algorithm is generic and does not include face detection. To prioritize faces, you should integrate a third-party face detection library and pass the detected face coordinates into the boost option of smartcrop.crop().

    Recommended Libraries:

    • Client-side: tracking.js is recommended for being small and simple.
    • Server-side: node-opencv can be faster but may have stability issues.
    • Other options: ccv js, jquery.facedetection, or opencv.js.

  5. Use smartcrop.crop() to find the best crop

    main

    The primary API method smartcrop.crop(image, options) finds the optimal crop for a given image based on the provided dimensions and options. It returns a Promise that resolves to a cropResult object containing the topCrop coordinates and dimensions.

    Image Input: The image parameter accepts anything compatible with ctx.drawImage(), such as HTMLImageElement, HTMLCanvasElement, or HTMLVideoElement. Note that CORS rules apply to cross-domain images.

    // you pass in an image as well as the width & height of the crop you
// want to optimize.
smartcrop.crop(image, { width: 100, height: 100 }).then(function(result) {
  console.log(result);
});

// Output example:
// {
//   topCrop: {x: 300, y: 200, height: 200, width: 200}
// }

  6. Configure cropOptions

    main

    The options object passed to smartcrop.crop() allows you to fine-tune the cropping algorithm:

    • width (Number): The desired width of the crop.
    • height (Number): The desired height of the crop.
    • minScale (Number): The minimal scale of the crop rect. Set to 1.0 to prevent crops smaller than necessary.
    • boost (Array<Object>): An optional array of regions to increase in 'interestingness' (e.g., faces). See boost.
    • ruleOfThirds (Boolean): If set to false, disables the rule of thirds composition weight.
    • debug (Boolean): If true, the result will include a debugCanvas and the full array of candidate results.
    // Example of using boost with a region
const options = {
  width: 100,
  height: 100,
  boost: [
    {
      x: 11,      // pixels from the left side
      y: 20,      // pixels from the top
      width: 32,  // pixels
      height: 32, // pixels
      weight: 1   // in the range [0, 1]
    }
  ]
};