Proposal: move resize-related options-as-functions to become options of resize

There have been a couple of cases where people expressed confusion with the current resize API.

The original “fluent” API was partly influenced by that of the gm module, the idea being that having a similar-ish API would make migration between the two modules easier. (The gm module builds an ordered list of flags to pass to the the underlying convert command line utility so it was always a bit of a leaky abstraction anyway.)

That was almost five years ago and I’ve wanted to improve this API for a while, especially as there is now a generation of developers who have never had to work with command line image processing tools.

The resize function currently has three signatures (that will remain):

resize(width)
resize(width, height) // supports null width for auto-scaling
resize(width, height, options)

This proposal is for an additional signature:

resize(options)

where options is an object with one or more of these properties:

• canvas
• crop
• embed
• fastShrinkOnLoad (existing property)
• height
• kernel (existing property)
• width
• withoutEnlargement

The following example usage of the proposed API would become possible.

NOTE: this proposed API has been updated - see https://github.com/lovell/sharp/issues/1135#issuecomment-423770094

resize({ width }) // equivalent to resize(width)
resize({ height }) // equivalent to resize(null, height)
resize({ height, width }) // resize(width, height)
resize({ crop: 'east', height, width }) // resize(width, height).crop('east')
resize({ embed: 'west', height, width }) // resize(width, height).embed('west')
resize({ canvas: 'max', height, width }) // resize(width, height).max()
resize({ canvas: 'min', height, width }) // resize(width, height).min()
resize({ canvas: 'ignoreAspectRatio', height, width }) // resize(width, height).ignoreAspectRatio()
resize({ height, width, withoutEnlargement: true }) // resize(width, height).withoutEnlargement()
resize({ canvas: 'max', height, width, withoutEnlargement: true }) // resize(width, height).max().withoutEnlargement()

REPEATED NOTE: this proposed API has been updated - see https://github.com/lovell/sharp/issues/1135#issuecomment-423770094

The max(), withoutEnlargement() etc. options-as-functions would be deprecated and (eventually) removed. This was the approach previously taken to move the no-longer-present progressive() function to become options of the jpeg() and png() output-selecting functions.

Constructive thoughts and feedback, as always, welcome.

Update: mention existing fastShrinkOnLoad and kernel options that will remain.

Update: consider moving operations that can result in an image of a different size, e.g. extend and trim, to the resize.js file (and therefore the resize docs).

[lovell]

sharp v0.21.0 is now available with this change.

Complete documentation for all the resize options is at http://sharp.pixelplumbing.com/en/stable/api-resize/#resize

[MajorBreakfast]

I like it. This indeed makes it a bit easier to learn. Here are some further ideas:

TL;DR: Align with CSS terminology where possible

resize({ width, height, fit: 'inside' }) // Like resize({ width, height, canvas: 'max' }) above
resize({ width, height, fit: 'outside' }) // Like resize({ width, height, canvas: 'min' }) above
resize({ width, height, fit: 'fill' }) // Like resize({ width, height, canvas: 'ignoreAspectRatio' }) above
resize({ width, height, fit: 'cover', position: 'bottom' }) // Like resize({ width, height, crop: 'south' }) above
resize({ width, height, fit: 'contain' } }) // Like resize({ width, height, embed: 'center' }) above

• Renamed canvas to fit (with 'min' renamed to 'outside' and 'max' to 'inside')
• Renamed crop and embed to cover and contain to align with how it is called in CSS (background-size and object-fit properties)
• Renamed the directions to top, bottom, etc. to align with CSS (object-position property)
• Combined crop and embed with canvas (now fit) because crop is basically canvas: 'min' with what is sticking out cut off. So, combining all of them makes sense because they’re doing similar things and cannot be used at the same time.

Possible explanation for the documentation: The width and height properties describe a box. The fit property specifies how the image is sized and placed relative to this box. Possible values for fit:

• 'inside': Preserving aspect ratio, resize the image to be as large as possible while ensuring that it stays inside the box.
• 'outside': Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than the box.
• 'fill': Ignore the aspect ratio and stretch the image so that it fits the box exactly.
• 'cover': Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than the box and crop the parts outside the box. By default the image is centered, meaning an equal amount is cut off on both sides. For more control you can use the position property.
• 'contain': Preserving aspect ratio, resize the image to be as large as possible while ensuring that it stays inside the box and add extra space around to fit the box. By default the image is centered, meaning extra space is added equally on both sides. For more control you can use the position property.