Image resizing is the single, most important operation one could perform on an image. The Optidash Image API gives you flexibility in choosing a resizing mode for different scenarios you may have. In most cases, the API will perform all calculations for you with respect to the aspect ratio of the image. Below, you'll find a detailed descripion of all resizing modes offered by the Optidash API.

Auto Mode

Auto is the default mode for image resizing even if the mode attribute is not specified. It accepts width and/or height attributes. This mode will always resize an image according to its aspect ratio, so for example, if you only specify width attribute, the height will be automatically adjusted and vice versa. If you specify both width and height attributes, the image will be resized in a way that it does not exceed specified dimensions.

In other words:
I want the image to be at maximum width × height or
I want the width of the image to be at W and height adjusted automatically for me or
I want the height of the image to be at H and width adjusted automatically for me.

{
    "resize": {
        "mode": "auto",
        "width": 300
    }
}

Fit Mode

This mode expects both width and height attributes, and resizes the image to fit the specified dimensions according to the aspect ratio and ensures that the area described by the dimensions is entirely covered with the image. Smaller images will be proportionally upscaled to fit within the desired output frame size. Any outstanding image parts will be cropped out. The default crop gravity value is center and you may alter it by specifying one of the the following: top-left, top, top-right, right, bottom-right, bottom, bottom-left, left.

In addition to direction-based gravity, Optidash also accepts face and faces as gravity values and will leverage face-detection algorithms to position any detected faces in the center of the resized image. If no faces were found, the API will fall back to the default center gravity. face gravity will center the image on the largest (usually most prominent) face detected in the image while faces (plural) will focus the image on all of the faces.

By default, this mode will upscale the input image to fit within larger dimensions specified in your request. If you'd like to prevent that from happening, simply pass "upscale": false within the resize hash.

In other words:
I want the image to fit entirely within width × height dimensions, and I'm okay with some cropping occurring.

{
    "resize": {
        "mode": "fit",
        "width": 200,
        "height": 200,
        "gravity": "right"
    }
}

In order to focus the image on a single, most prominent face, simply use face as gravity value:

{
    "resize": {
        "mode": "fit",
        "width": 250,
        "height": 200,
        "gravity": "face"
    }
}

A similar API call with gravity set to faces (plural) will center the image in a way to show all of the faces:

{
    "resize": {
        "mode": "fit",
        "width": 250,
        "height": 200,
        "gravity": "faces"
    }
}

Fill Mode

This mode expects both width and height attributes, and just like auto strategy, proportionally resizes the image in a way that it does not exceed the specified dimensions. The remaining area is then filled with a background which accepts three values: a hex-encoded color, auto or blur (see examples below). Within the resize hash you may also specify shadow parameter which takes an integer within 1 - 100 and describes the amount of shadow to add to the original image in order to make it stand out.

In other words:
I want the image to be at maximum width × height and excess space filled with a solid background color or Gaussian-blurred version of the original image.

The first possible background value is pretty self-explanatory. You can provide a hex-encoded string in RGB, RRGGBB or AARRGGBB format. The default background color is white #ffffff. Let's have a look at an example JSON request and the resulting image.

{
    "resize": {
        "mode": "fill",
        "width": 400,
        "height": 300,
        "background": "#2b3246"
    }
}

You may also choose to set the most dominant color found in the input image to be used as a background color. To do so, simply specify auto as a background value. Optidash API will than quickly compute color palette of the input image and automatically use the most dominant color ensuring your input image will blend perfectly with the background.

{
    "resize": {
        "mode": "fill",
        "width": 400,
        "height": 300,
        "background": "auto"
    }
}

The last possible background value is blur. When used, Optidash API will use a Gaussian-blurred version of the input image to fill excess space giving you the most visually pleasing composition.

{
    "resize": {
        "mode": "fill",
        "width": 400,
        "height": 300,
        "background": "blur"
    }
}

Exact Mode

This mode expects both width and height attributes, and resizes an image to the exact specified dimensions. It does not take aspect ratio into account, so you will need to do the calculations on your side in order to ensure that the resulting image comes out with perfect proportions.

In other words:
I want the image to be exactly width × height.

{
    "resize": {
        "mode": "exact",
        "width": 300,
        "height": 50
    }
}