What is Image Adaptation?

Image Adaptation is a query string-based API that uses Instart's image processing capabilities to apply a variety of operations to images in JPG, PNG, GIF and animated GIF formats. We can

  • resize images to a specific pixel size, a relative percentage of the original image, a maximum or minimum dimension
  • crop images to a specific size from a specified location relative to the image's borders
  • filter images to grayscale or black and white
  • sharpen images to reduce apparent blurriness
  • add a border of a specified color and size
  • chain any of these operations (processed in the order specified)
  • This allows you to store a single high-resolution image on a backend origin web server and then process images as needed when they are delivered through our service. This allows, for example, sending smaller images to mobile and tablet devices with smaller screens and providing thumbnails for larger images.

Note

Images for Image Adaptation must be JPGs, PNGs, GIFs, or animated GIFs only.

Images can be processed using simple resize and cropping commands that are added to the query string of an image's request.

How Image Adaptation works

Images are processed in one of two modes:

  • queued (formerly called non-blocking) mode: When an image operation is first requested, the service returns the original image and schedules the image processing to be performed by our service. Future requests for the image with the same parameters will then return the processed images from our service, as long as the image has not expired. This is the default.
  • Real-time (formerly called blocking) mode: the service will send the processing request to the Image Service immediately and wait for it to complete before serving the image.

Important

If you want to use real-time mode and your site has a very large number of images that will be adapted, or more than 50 image requests per second, please contact Instart Support to ensure we can plan service capacity appropriately.

The following sections describe how to make image adaptation requests of each kind, with examples of each.

Note on best practice

To effectively use Image Adaptation, start with images that are the best size and quality for your customers' highest-resolution devices. You don't want to ship any more pixels than needed to display the image at its intended size in the browser. Relying on the browser to rescale them consumes extra CPU resources and displays them at a lower resolution. It doesn't make sense to use images that are significantly larger than you would ever normally serve to your customers, such as raw images at their best possible resolution from a professional digital camera, which can be many megabytes in size and far larger in height and width than can be displayed on a computer screen without scaling them down.

Also note that the Image Adaptation service has an upper limit for resizing based on a maximum area of 25,000,000 pixels. If the area of the requested image would be larger than this limit, the service provides the image at its original size.

In addition to specifying the query string, image requests to leverage Image Adaptation's capabilities should include the maximum desired dimensions in the IMG tag's width and height attributes in the HTML provided to the end user's browser when the desired image processing will result in a change to the image's size. This ensures that when the first user makes a request for a resized image and gets the original image, the user's browser will initially display at the desired size.

For example, if the size of the original image is 600 x 400 and the desired image size on the page is 300 x 200:

<img width="300" height="200" src="http://img.example.com/ggbridge.jpg?i10c=img.resize(width:300,height:200)" />

would cause the browser to render the larger original image at 300 x 200 for the first request.

For image cropping operations, the first time a request is seen it will likewise be the original, uncropped image. By setting the IMG tag's width and height attributes you can at least enforce that the image will be displayed at the same size that the processed image will have. (Note that it will be distorted unless the aspect ratio of the original image and the cropped image is the same.)

Resizing images

The service allows specifying either a scale percentage of the original image (scale_width and scale_height), a specific number of pixels (width and height), or a maximum/minimum dimension in the query string. You can specify these for just one dimension and the service will scale the image consistently with the original image's aspect ratio. If you specify both such that the aspect ratio is not considered (for example, if you specify a scale_width of 50% and a scale_height of 25%), the service will do what was requested and therefore provide a distorted image.

There is an upper limit for resizing based on a maximum area of 2560 x 1600 pixels. If the area of the requested image would be larger than this limit, the service provides the image at its original size.
If you accidentally encode bad values (for example, any characters other than integers for width and height, any characters other than integers and a single period for scale_width and scale_height), the original image is sent and an error message, "invalid argument range: resize parameters must be positive" is sent in the header x-instart-image-error-message.

Pixel resize

One of the following three variants can be used for specifying pixel values:

  • width
    i10c=img.resize(width:400)
  • height
    i10c=img.resize(height:300)
  • width and height
    i10c=img.resize(width:400,height:300)

When only one of width or height is specified, the other parameter is computed automatically while maintaining the aspect ratio. If both the parameters are specified, both will apply, which means that the aspect ratio might not be maintained, resulting in a distorted (stretched or squashed-looking) image.

Scale resize

One of the following three variants can be used for specifying scale values:

  • scale_width
    i10c=img.resize(scale_width:0.5)
  • scale_height
    i10c=img.resize(scale_height:0.25)
  • scale_width and scale_height
    i10c=img.resize(scale_width:0.5,scale_height:0.25)

As with pixel resize, when only one of scale_width or scale_height is specified, the original aspect ratio is maintained. If both the parameters are specified, the aspect ratio will not be maintained if the percentages are different, resulting in a distorted (stretched or squashed-looking) image.

Maximum and minimum dimension resize

You can specify resizing an image based on either its maximum or minimum dimension:

  • maxdim
    i10c=img.resize.maxdim(value:800)
  • mindim
    i10c=img.resize.mindim(value:800)

maxdim takes the maximum of the image's width or height and resizes that dimension to the given value, maintaining the original aspect ratio. Similarly, mindim takes the minimum of the image's width or height and resizes that dimension to the given value, maintaining the original aspect ratio. This is useful for applications like an array of images where you want to enforce that they all have the same width or height.

For example, consider an image that is 1024 pixels by 768 pixels. If you specify i10c=img.resize.maxdim(value:800) for that image, the service takes the maximum dimension of the image, 1024, and scales the image so that its width is 800 pixels. Likewise, if you specify i10c=img.resize.mindim(value:800) for the same image, the service takes the minimum dimension of the image, 768, and resizes the image so that its height is 800 pixels.

Examples of resize operations

In the following examples we will use the following original asset URL, which has an original size of 800x600 pixels:

http://img.example.com/ggbridge.jpg

The following URLs would trigger an automatic resize and caching of the image in our service.

Pixel resize examples

Scale height and width to a specified number of pixels (half the original image size):

http://img.example.com/ggbridge.jpg?i10c=img.resize(width:400,height:300)

Only height or width specified:

http://img.example.com/ggbridge.jpg?i10c=img.resize(width:400)

http://img.example.com/ggbridge.jpg?i10c=img.resize(height:300)

Note

When only the height or width is specified, the other dimension will automatically be scaled relative to the original image to maintain the original aspect ratio.

Scaling resize examples

Scale both height and width to 50% of the original image:

http://img.example.com/ggbridge.jpg?i10c=img.resize(scale_width:0.50,scale_height:0.50)

Only height or width scaled:

http://img.example.com/ggbridge.jpg?i10c=img.resize(scale_width:0.50)

http://img.example.com/ggbridge.jpg?i10c=img.resize(scale_height:0.50)

When only the height or width is specified, the other dimension will automatically be scaled relative to the original image to maintain the original aspect ratio.

Maximum/minimum dimension resize examples

Resize to the maximum dimension of the original image:

http://img.example.com/ggbridge.jpg?i10c=img.resize.maxdim(value:700)

the maximum dimension of the image, its width of 800 pixels, is scaled so that its width is 700 pixels

Resize to the minimum dimension of the original image:

http://img.example.com/ggbridge.jpg?i10c=img.resize.mindim(value:500)

the minimum dimension of the image, its height of 600 pixels, is scaled so that its height is 500 pixels

Fitting an image in a box with optional border color

You can have the service create a new image with a box of a specified width and height framing it, with the box optionally being filled with a specified color (the default is white). Both width and height are required. The optional bordercolor can be any RGB shade in the form of a hex number.

If the box dimensions are smaller than the image, the image will be scaled to just fit in the box without changing the original image's aspect ratio.

If the box dimensions are larger than the image, the original image will be centered in the box. If the optional parameter enlarge:true is used, the image will be resized such that its width spans the entire box while maintaining its aspect ratio.

Examples:

In the following examples we will use the following original asset URL, which has an original size of 500x330 pixels:

http://img.example.com/stonehenge.jpg

Fit a 500x330 image in a 600x400 box, default box fill color (white):

http://img.example.com/stonehenge.jpg?i10c=img.resize.fit(width:600,height:400)

Fit a 500x330 image in a 600x400 box with default box fill color of white

Fit a 500x330 image in a 600x400 box, box fill color set to 0xd8d8d8 (a shade of gray):

http://img.example.com/stonehenge.jpg?i10c=img.resize.fit(width:600,height:400,bordercolor:"0xd8d8d8")

Fit a 500x330 image in a 600x400 box, box fill color set to 0xd8d8d8, a shade of gray

Fit a 500x330 image in a 600x500 box, box fill color set to 0x3CB371 (a shade of green) and enlarged:

http://img.example.com/stonehenge.jpg?i10c=img.resize.fit(width:600,height:400,bordercolor:"0x3CB371",enlarge:true)

Fit a 500x330 image in a 600x500 box, box fill color set to 0x3CB371, a shade of green, and enlarged

Cropping images

The service allows specifying a specific number of pixels (width and height) and a gravity parameter that defines the placement of the cropping action in the image.

Valid values for width are integers between 1 and the width of the original image; valid values for height are integers between 1 and the height of the original image. If any other value is specified, then this parameter is ignored.

You can specify width and height for just one dimension and the service will scale the cropped image consistently with the original image's aspect ratio.

If you specify both such that the aspect ratio is not considered (for example, if you specify a width of 200 and a height of 300 on an original image that is 1000 x 1000), the resulting image will not have the same aspect ratio as the image but the remaining portion of the image will not be distorted.

The gravity parameter is a string that specifies the location of the cropped region within the original image. By default gravity is center and requests cropping around the center of the original image.

The following lists the valid values for the gravity parameter with an example image demonstrating the effect of each; the resulting image is represented by the area in full color, and the cropped-out portion of the image is shown in grayscale:

ValueDescriptionExample
centerDefault; crop around the center of the original image

leftCrop from the left center of the image

rightCrop from the right center of the image

topCrop from the top center of the image

bottomCrop from the bottom center of the image

topleftCrop from the top left corner of the image

toprightCrop from top right corner of the image

bottomleftCrop from bottom left corner of the image

bottomrightCrop from bottom right corner of the image

Examples of cropping operations

In the following examples we will use the following original asset URL, which has an original size of 1024x768 pixels:

http://img.example.com/tulips.jpg

The following URLs would trigger an automatic cropping and caching of the image in our service.

Crop from the center

Crop height and width to a specified number of pixels:

http://img.example.com/tulips.jpg?i10c=img.crop(width:512,height:300)

Only crop height or width specified:

http://img.example.com/tulips.jpg?i10c=img.resize(width:512)

http://img.example.com/tulips.jpg?i10c=img.resize(height:384)

Note

The cropped image will automatically be scaled relative to the original image to maintain the original aspect ratio.

Crop from the top

http://img.example.com/tulips.jpg?i10c=img.crop(width:512,height:300,gravity:top)

Crop from the bottom right corner

http://img.example.com/tulips.jpg?i10c=img.crop(width:512,height:300,gravity:bottomright)

Sharpening images

Sharpening is a process applied to images to attempt to reduce perceived blurriness. We apply a sharpening process on a scale from 0.0 (no sharpening) to 1.0 (full sharpening).

Example

The following shows the original version of the image on the left, with a sharpened version on the right. The query string is

?i10c=img.sharpen(amount:1.0)

Example image before sharpening operation

Example image after sharpening operation after


Filtering images (grayscale/monochrome)

You can apply a filter to convert an image into either a grayscale or monochrome (black and white) image:

grayscale:
i10c=img.filter(type:grayscale)

monochrome:
i10c=img.filter(type:monochrome)

Example

The following shows the original version of the image on the left, a grayscale version in the center, and a monochrome version on the right.

Example image before filtering operation

Example image after filtering to grayscale

Example image after filtering to monochrome

Chaining image processing

You can combine any of the Image Adaptation operations simply by specifying the commands in the query string, separated by a semicolon. The order these commands appear in the query string controls the order that the operations will be performed in.

Example

Assuming that the size of the original image is 2000x2000 and the area of interest is 1000x1000 around the center, if the cropped image has to fit into a 500x500 box, and be grayscale, the query string would be:

i10c=img.crop(width:1000,height:1000);img.resize(width:500,height:500);img.filter(type:grayscale)