Image Service

The image service provides an image from an image content.

Configuration

The image service can be configured using the following system properties:

Property Default Value Description
imageService.configContent _config/aceImageFormats Alias for the configuration content that contains image format specifications.

Image format

Image formats are specified in a configuration content of content type aceImageFormatsContent, in an aspect of type aceImageFormats. The aceImageFormats aspect contains a list of image formats, where each format entry have the following properties:

Property Type Presence Description
name string mandatory The name of the format. Used to refer it in a URL (see Cropping).
label string optional The display name of the format.
description string optional The description of the format, perhaps explaining its intended use.
aspectRatio aceAspectRatio optional Defines a fixed width/height aspect ratio if present. Otherwise no aspect ratio is enforced.

The aceAspectRatio type has the following properties:

Property Type Presence Description
width integer mandatory The aspect ratio on the X axis.
height integer mandatory The aspect ratio on the Y axis.
Example
{
  "system": {
    "contentType": "aceImageFormatsContent"
  },

  "aspects": {
    "aceImageFormats": {
      "_type": "aceImageFormats",
      "formats": [
        {
          "name": "widescreen",
          "label": "16 x 9",
          "description": "The default widescreen format",
          "aspectRatio": {
            "width": 16,
            "height": 9
          }
        },
        {
          "name": "square",
          "label": "1 x 1",
          "description": "The default square format",
          "aspectRatio": {
            "width": 1,
            "height": 1
          }
        }
      ]
    }
  }
}

Request path and parameters

By default, the image service is deployed at http://ace-image-service:8084/. In a production installation, it will likely be behind a proxy with a custom host name.

To get the full image, append the image's version id followed by a file name and an extension (determines the file format to serve). The file name is arbitrary, i.e., the file associated with the image content will be served no matter what path is used after the content ID. This allows using different file names in different contexts. Note that doing so will result in different URLs for the same image, which reduces the hit rate in caches and, hence, might result in penalties from search engines.

Example: Serve the full size image as a PNG
http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/testimage.png

Image service options

The image service always applies any manual editing (pixelation, etc) that has been performed on the image content being requested, but it also takes a number of dynamic parameters. These are described here.

Cropping

There are three parameters to control image cropping:

  1. c: an explicit crop rectangle of the form (x,y,width,height)
  2. a: an aspect ratio on the form (width:height)
  3. f: a named format
Examples
http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/image.png?c=0,0,100,100

http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/image.png?a=4:3

http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/image.png?f=formatName

Only one of these parameters will be used for processing a given request. If several parameters are passed, the active parameter is selected according to the order of precedence listed above.

If f is used, the image service crops the image as follows:

  1. If the crop specification is specified in the image's edit info, use that for cropping.
  2. If the crop specification is not specified image's edit info, but aspect ratio format is specified in the configuration content, use that.
  3. Otherwise, apply no cropping.

Resizing

To resize the image, you add w and/or h parameters. Resizing never changes the proportions of the image, so if you specify both w and h, by default, it will generate the largest image that fits inside that box.

Example: Serve the image as a PNG cropped to 4:3 and resized to fit in a 160x120 box
http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/image.png?a=4:3&w=160&h=120
Example: Get an image that fills a 100x100 px box
http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/image.jpg?w=100&h=100&m=FILL

The image can be scaled to fill a specified box by choosing the FIT mode instead of the default FILL mode by using the m request parameter.

Example: Get an image that fits in a 100x100 px box
http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/image.jpg?w=100&h=100&m=FIT

NOTE: Image resizing is always performed after all other operations have been applied.

Automatic crop position

If cropping coordinates are not specified, a simple algorithm is used to determine where to place the crop rectangle. When cropping the sides of an image, the crop rectangle is placed in the middle. When cropping the top and bottom, the rectangle is placed in the upper part of the image. This is because the interesting part of portrait images are normally located in the upper part.

Jpeg Compression Quality

When requesting an image in the jpeg format, the q parameter can be used to specify the desired jpeg compression quality. The value of the parameter ranges between 0.0 to 1.0 (default 0.75), which controls the tradeoff between image quality and file size. A higher value results in a better image quality at the cost of having a larger file size.

Example: Get a high resolution version of the image with high compression
http://ace-image-service:8084/version/c:MTY4M2ZlNDktMjNkYy00:MTBmMTc5/image.jpg?w=2048&h=2048&q=.3

File Formats

The Image Service uses Java ImageIO to read and write images, which means only image formats supported by ImageIO are supported. The standard ImageIO shipped with the JDK has a very limited support for file formats that are not commonly used on the web. For example, images in CMYK or TIFF formats are not supported out of the box.

The file format of an image served by the Image Service is determined in the following order:

  1. Image file extension: The Image Service uses Apache Tika to determine the image mime type, i.e., type image/*, using the requested image file extension.

  2. Image file content: The Image Service uses Apache Tika to determine the image mime type, i.e., type image/*, using on the image data of the requested image.

  3. Accept header: The Image Service matches the image mime type requested through the Acccept HTTP header with the types supported by ImageIO and uses the best match.

Note that the determined image mime type will affect not only the data format of the returned image, but also the Content-Type HTTP header of the image response.