Working with images
This section explains how to get images using the ImageService, which supersedes the Image Handler Service.
If you are still using IHS, see Using IHS to get images.
Overview
A client application typically needs to retrieve images to represent content in the UI. The ImageService exposes APIs that enable it to do this.
The ImageService attempts to satisfy all the specified requirements of an image request. However:
- The ability to provide a satisfactory image depends on the number and type of images initially ingested.
- Image cropping is NOT supported, so if a portrait image is requested from an landscape source image, the ImageService will return a default image.
- If the request does not specify an aspect ratio (i.e., only width and height are specified), the ImageService will return an image of the nearest supported aspect ratio.
For example, if a request specifies a width of 160 and a height of 90, this equates to a decimal aspect ratio of 1.77:1. The nearest match would be 16x9, which is a decimal aspect ratio of 1.78:1. - Unless a WebP format image is specifically requested, all images will be returned in JPG format.
Prerequisites
Image ingestion
For client applications to be able to retrieve images, image metadata must already have been ingested into the ImageService. Metadata can be ingested in the appropriate NAGRA XML format. See Image ingest.
Retrieving an image
Using the relevant metadata, and other configurations, the ImageService provides an API to fetch images related to the ingested content. A master image that has been retrieved from the image source will be resized in accordance with the client request.
ImageService enables an operator to ingest content from multiple sources, and "maps" (using configured mappings) the many ways in which specific image attributes can be described.
For example:
contentType– where the image is described by the type of content it is related to (for example, it relates to a movie/VOD item, or to a broadcast programme)imageType– where the image is described by how it is used (for example, whether it is a "main banner" image, a channel logo, a picture of a cast member, and so on)
Widening the search
Inconsistent image metadata can can influence the nature of the image returned. In order to maximise the delivery of relevant images (and minimise the use of the "fallback" facility), the ImageService looks to "widen" its search by using the metadata it has available to it. This includes using the locale data – so where there is no exact match for the requested locale, the service will try and match on other locales using a set of defined rules.
See Use ImageService to get images.
Resizing an image
The dimensions of the image returned depend on what you specify in the image request. You can use of a combination of image width, height, and/or aspect ratio parameters.
For example, if you specify width and height as inputs, then the ImageService calculates the aspect ratio (width/height) uses this to select the closest supported aspect ratio. This is then used to generate the required image.
The possible combinations of parameters and how these impact the image output is described in the ImageService API documentation.
All specified dimensions and/or aspect ratios will be converted to the closest pre-defined aspect ratio.
If the matching image does not have the same aspect ratio as the one requested, ImageService letterboxes the image (that is, adds padding at the top or sides of the image to reach the required aspect ratio). If the requested image type is WebP, the padding will be transparent. For JPEG, It will be black.
Preferred images
Multiple images can be assigned to a content item. An operator may set certain images as “preferred” for certain scenarios.
This can be done:
If no preference is set, ImageService returns the first matching image.
Fallback and default images
ImageService enables an operator to assign both a fallback image and a default image. The fallback image can be assigned per contentType – this allows an image to be displayed that relates to the original content type (e.g., a generic movie image, or a default "sports" image).
An image of contentType="default" can also be ingested, either via OpCon or via API. This image will be used when no fallback image is available. These images are usually ingested through OpCon, though they can also be assigned through the use of API calls.
The error image is the “image of last resort”. If an ImageService-related error occurs, then this error image will be returned with a 200 response code. This can only be ingested through the use of an API call.