ImageProcessor

image~ ImageProcessor

A secure wrapper class for the Sharp image processing library. Each method returns 'this' to allow for a fluent, chainable API. This class cannot be directly instantiated. Instead, use the `load` function of the Image module to create an instance with an image loaded from a Buffer or a file path. This class abstracts the complexities of image processing, providing a simple interface for developers to work with images. It allows for flexible image manipulation workflows, enabling developers to chain multiple operations on the image. IMPORTANT: Requires explicit permission to use the module. See docs/permissions-guide for more details.

Constructor

new ImageProcessor(sharpInstance)

Description:
  • Creates a new ImageProcessor instance.
Parameters:
Name Type Description
sharpInstance An instance of the sharp image processing library.

Methods

blur(sigma) → {ImageProcessor}

Description:
  • Applies a blur effect to the image.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.blur(5);
Parameters:
Name Type Description
sigma number The blur amount (higher values = more blur).
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

composite(watermarkBuffer, options) → {ImageProcessor}

Description:
  • Composites another image onto this one.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.composite(watermarkBuffer, { left: 10, top: 10, opacity: 0.5 });
Parameters:
Name Type Description
watermarkBuffer Buffer The image buffer to composite.
options object The options for compositing.
Properties
Name Type Attributes Default Description
left number <optional>
 0 The x-coordinate to place the watermark.
top number <optional>
 0 The y-coordinate to place the watermark.
opacity number <optional>
 1 The opacity of the watermark
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

flip() → {ImageProcessor}

Description:
  • Flips the image horizontally.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.flip();
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

flop() → {ImageProcessor}

Description:
  • Flips the image vertically.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.flop();
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

format(format, optionsopt) → {ImageProcessor}

Description:
  • Converts the image to a specific format.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.format('jpeg', { quality: 80 });
Parameters:
Name Type Attributes Description
format string The format to convert to (e.g., 'jpeg', 'png', 'webp').
options object <optional>
 Options for the format conversion (see sharp documentation).
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

greyscale() → {ImageProcessor}

Description:
  • Converts the image to greyscale.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.greyscale();
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

resize(options) → {ImageProcessor}

Description:
  • Resizes the image to the specified dimensions.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.resize({ width: 200, height: 200, fit: 'contain', background: '#FFFFFF' });
Parameters:
Name Type Description
options object The resize options.
Properties
Name Type Description
width number The new width of the image.
height number The new height of the image.
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

rotate(angle) → {ImageProcessor}

Description:
  • Rotates the image by the specified angle.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.rotate(90);
Parameters:
Name Type Default Description
angle number 0 The angle to rotate the image (in degrees).
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

sharpen() → {ImageProcessor}

Description:
  • Sharpens the image.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.sharpen();
Returns:
The ImageProcessor instance for chaining.
Type
ImageProcessor

(async) toBuffer() → {Promise.<Buffer>}

Description:
  • Processes the image and returns the final data as a Buffer.
Example
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.resize({ width: 200, height: 200 });
const buffer = await processor.toBuffer();
Returns:
Type
Promise.<Buffer>

(async) toFile(scope, filePath) → {Promise.<void>}

Description:
  • Processes the image and saves it to a file using our secure fs module.
Example
// path with leading slash indicates path from scope root, 
// path without leading slash indicates path relative to the executing script
// here image is loaded from <project>/<app_name>/<box>/images/gingee.png
// image is and saved to <project>/<app_name>/output/processed_image.webp
const processor = image.load(fs.BOX, '/images/gingee.png');
processor.resize({ width: 200, height: 200 });
await processor.toFile(fs.WEB, '/output/processed_image.webp');
Parameters:
Name Type Description
scope string The scope to save to (fs.BOX or fs.WEB).
filePath string The destination file path.
Returns:
Type
Promise.<void>