image engine getting started

Getting Started with ImageEngine

Images make 60-70% of the total weight of an average web page. ImageEngine is a service to assist designers and web developers resize, crop, and eventually optimize the images on their site automatically.

Using ImageEngine will reduce the image payload significantly and increase website performance.

The easiest way to understand ImageEngine is to see it as an intelligent Content Delivery Network (CDN). The intelligence built in helps you to automatically (or explicitly) optimize images for the requesting device or browser.

The first step is to register an account here in order to receive your unique token.

ImageEngine Lite

If you are setting up an ImageEngine Lite plan you are ready to get started prefixing your urls.

ImageEngine Lite has a limitation of use that will result in an HTTP error code if exceeded:

  • Maximum size of source image is 2MB
  • Maximum bandwidth use is 5GB per month

ImageEngine

ImageEngine Premium does not include any of of the limitations of the ImageEngine Lite plan and offers hotlinking, billing alerts, explicit cropping, HTTP client hints, and more.

If you do not want your resized images to be accessible from outside domains, you will need to enable hotlinking for your account. In order to enable this, you will need to add and verify your whitelist of hostnames. Once verified you will be able to enable hotlinking in your account.

Customer Vault ImageEngine Hotlinking

The Image Engine service will continue to resize images as long as your account is in good standing order. If you would like to set up billing alerts you may configure this. You may also use this to estimate how much you expect to use the service for any given billing period. Once the billing alert has been exceeded, you will receive an email notification to the account on file letting you know you are approaching the estimated costs.

Customer Vault ImageEngine

Note: You will need to remove references to your ImageEngine images in order to halt service.

How does it work?

ImageEngine combines explicit settings, Client Hints and WURFL data to make sure that the image is as optimized as it can be for any device or browser.

This makes ImageEngine the ideal choice for automating your implementation of responsive images.

In order to begin using ImageEngine, you will need to fetch your "subdomain" token received during the registration process and prefix all your images your ImageEngine url (eg: try.imgeng.in or try.lite.imgeng.in for Lite accounts).

If you have an img tag like this:

  <img src="https://example.com/img/car.jpeg">

You will then need to prepend the url with your unique token:

  <img src="https://try.imgeng.in/http://example.com/img/car.jpeg">

The example above demonstrates the fully automatic optimization, meaning that the size and format is determined by either WURFL or Client Hints.

Parameters

Below is a list of parameters that will explicitly instruct ImageEngine on how to treat the image.

ImageEngine takes commands from the URL preceding the original image URL so in the example below, w_320 will set the width of the image to 320px. See the below diagram:

  <img src="https://try.imgeng.in/w_320/h_200/http://jelly.com/bread.png">
Section Values Function
ImageEngine URL URL This is the URL of the ImageEngine service.
Image Manipulation Parameters1 parameter_value pairs2 These settings instruct ImageEngine what transformations are expected.
Image URL URL This is the image that is to be displayed. The image itself does not need to be on the client site.

1 See the respective product sections for a complete parameter list.
2 Some parameters may have multiple values and have the form setting_value_value1_value2

Available Parameters in ImageEngine Lite

Parameter Name Value Description Example
w Width Integer Desired width of resized picture. 1 3 /w_200/
h Height Integer Desired height of resized picture. 1 3 /h_200/
pc Percentage of screen 1-100 (float) This field will use WURFL to calculate the screen width and then scale the image accordingly. /pc_50/
m Fit method stretch, box, letterbox, cropbox 2 This setting determines how the engine will resize the images. This can include stretching, cropping, and/or padding out the canvas. /m_box/
f Format jpg, gif, png, bmp, webp Desired format of picture. If no format is provided, the format of the original picture is used. /f_webp/
cr 4 Crop Integer Crop by coordinates /cr_10,10,100,100/
in 4 Inline Boolean Return the image as a base64 encoded string for use in data urls /in_true/

1 If a fit method is not specified and only width or height is specified it will select "box". If both width and height are specified by fit is not explicitly specified, then it will assume the fit method is "stretch".
2 Fit method has additional optional parameters.
3 If defined, this will take precedence over any automatic setting.
4 Not available in ImageEngine Lite.

Client Hints

For ImageEngine Lite you'll have to explicitly enable Client hints by adding the below <meta> tag to your <head> element:

  <meta http-equiv="Accept-CH" content="DPR, Viewport-Width, Width">

In commercial versions of ImageEngine, the server will advertise support for Client Hints automatically.

Available Client Hints

Client Hint Description ImageEngine Lite ImageEngine
DPR Device Pixel Ratio x x
Width Width x x
Viewport-Width Size of Viewport x x
Save-Data Additional compression x

Using client hints and ImageEngine with responsive images will generate a perfectly sized and optimized image.

Image Formats

The formatting parameter allows images to be converted between formats.

Supported Formats

The following formats are accepted by ImageEngine for both input and output.

  • PNG 1
  • GIF 2
  • JPG 3
  • BMP
  • WEBP

1 Both 8-bit and 24-bit PNG files are supported including both index and alpha transparency.
2 Not all features of ImageEngine are available for animated GIF files.
3 JPEG can also be used as an alias of JPG.

Input ColorSpaces Supported

Image Format Greyscale Indexed Color RGB CMYK
JPG Y N/A Y 3 Y 3
GIF Y 2 Y N/A N/A
8-Bit PNG Y Y 1 N/A N/A
24-Bit PNG Y N/A Y 3 N/A
BMP Y N/A Y N/A

Output ColorSpaces Supported

Image Format Greyscale Indexed Color RGB CMYK
JPG Y N/A Y 3 Y 3
GIF Y 2 Y N/A N/A
8-Bit PNG Y 2 N/A N/A 1 N/A
24-Bit PNG Y N/A Y 3 N/A
BMP Y N/A Y N/A

1 8-bit PNG's are converted to 24-bit by most operations. This will not result in quality loss.
2 8-bit images can be treated like indexed color images for ImageEngine operations. Greyscale images in this case will behave identically to 8-bit indexed color images where the colors available are all greys.
3 Both 8-bit and 16-bit per channel depths are supported

Examples:

Fully Automatic

  https://try.imgeng.in/http://upload.wikimedia.org/wikipedia/commons/8/82/2011_Trampeltier_1528.JPG

All Images are 300px Wide

  https://try.imgeng.in/w_300/http://upload.wikimedia.org/wikipedia/commons/8/82/2011_Trampeltier_1528.JPG

Create 200x200px Thumbnails with Black Letterboxes / Pillarboxes

  https://try.imgeng.in/w_200/h_200/m_letterbox_000000_100/http://upload.wikimedia.org/wikipedia/commons/8/82/2011_Trampeltier_1528.JPG

License

2017 ScientiaMobile Incorporated All Rights Reserved.

NOTICE: All information contained herein is, and remains the property of ScientiaMobile Incorporated and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to ScientiaMobile Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from ScientiaMobile Incorporated.