Description

This reworks cropping and resizing to support a bigger effort to correctly apply these transformations at the right point within the transformation string.

The current mechanism applies the core width and height to the front of the transformation string, with the idea of providing a "canvas" for someone to work from, but this is unintuitive, where a width and height would be the expected final resize, which may not be the case with other transformations (particularly dynamically generated responsive images).

This removes the widthResize property which applied the transformation the end, where the core width and height resizing now takes place.

To fill in for use cases where it made sense to apply a "base" cropping and resizing effect, a new base* property was added for width, height, crop, gravity, and zoom, to accommodate the situation where one might want to resize, apply transformations, then obtain the true width and height with a final resize as part of a 2-stage crop and resize.

In the example where

Somewhat of a tl;dr This PR primarily reverses the order in which the parameters are applied, opting for the primary width and height to be the final transformation applied to avoid attempting to more accurately describe what the user's intent is when passing in a width and height. As such, the name of the options for the 1st stage is now base*

Examples

Previously when using an effect with a width:

constructCloudinaryUrl({
  options: {
    width: 100,
    grayscale: true
  }
})

The resulting transformation would yield: c_limit,w_960/e_grayscale

However, it would now yield: e_grayscale/c_limit,w_960

This is more relevant when using the 2-stage resizing, where previously:

constructCloudinaryUrl({
  options: {
    width: 100,
    widthResize: 200
  }
})

The resulting transformation would yield: c_limit,w_100/c_limit,w_200

Where now:

constructCloudinaryUrl({
  options: {
    width: 100,
    baseResize: 200
  }
})

The resulting transformation would yield: c_limit,w_200/c_limit,w_100

Use Case

A big use case around why this is important is limiting the size of an image prematurely.

In an example such as:

constructCloudinaryUrl({
  options: {
    width: 100,
    widthResize: 200
  }
})

The resulting transformation would yield: c_limit,w_100/c_limit,w_200

This is problematic if the original image is greater than or equal to 200, as with the first transformation applied, the image will not be able to be sized organically above 100. If using a crop that allows upscaling, it would not result in using the original image, meaning it would scale to 200 with reduced quality.

The effect is largely the same in what it achieves, but the use case and intent should be more accurate with this PR.

Relevant: https://github.com/cloudinary-community/next-cloudinary/issues/327

cloudinary-community / cloudinary-util

Reworking Resizing / Cropping #139

Description