Working with 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)

Locale

OpenTV Platform can be configured to map a requested locale to acceptable locales. This increases the likelihood of finding an appropriate match (that is, an image with text in the correct language if it is an image that includes text) and overcomes the issue where the locale metadata on the ingested image does not exactly match the request (en-GB instead of en_GB, for example).

Optionally, one locale may be configured as the primary locale. ("primary": true is set on the locale, like en_GB in the example below). This is used by downstream services, such as Metadata Server (MDS).
Note that this does not affect how ImageService matches images to a locale specified in a request.

Additionally, a default block can be configured for requests that do not include a locale.

Finally, strict_match can be set to true or false.

If the image request includes a locale, ImageService will attempt to provide an image with a matching locale or the closest acceptable match, as follows:

It first works its way down the list of accepted locales for the specified locale in order.
For example, referring to the example configuration below, if the requested locale is en_GB, it will first look for matching image with the en_GB locale, then ones with the en-GB locale, and so on.
If the service does not find a match within the accepted locales:
- If strict_match is true, it returns a fallback image.
- If strict_match is false, it picks a random image that matches the other criteria (size, aspect ratio) from the ones associated with the content.

If the image request does not include a locale, ImageService will again attempt to provide a match, as follows:

If a default locale is configured (see the "id": "default" block in the example below), ImageService will use it try to find an image using the same logic as described above.
If no default locale is configured, it picks a random image that matches the other criteria (size, aspect ratio) from the ones associated with the content.
If no such images exist, it will return a fallback image.

Note that for the default locale (which is used when the image request does not include a locale), the first accepted locale in the example below is "".
This means that the preferred image in this case is one with no locale defined on it (which may be an image with no text, for example).

You can also use "" for defined locales. For example, you might list the possible matching locale IDs (e.g., en_GB, en-GB, enGB, en, etc.), then "", and then the IDs for your second preferred locale (e.g., "fr_FR", "fr-FR", etc.).

If you need to change the configured acceptable locales, please discuss this with your NAGRAVISION representative.

Example locale configuration

JSON

[
  {
    "id": "default",
    "accepted": [
      "",
      "en_GB",
      "en-GB",
      "enGB",
      "en"
    ]
  },
  {
    "id": "en_GB",
    "primary": true,
    "accepted": [
      "en_GB",
      "en-GB",
      "enGB",
      "en",
      "en_US",
      "en-US",
      "enUS"            
      ""      
    ],
    "strict_match": true
  }
]

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 (as explained above).

See Using 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:

Through OpCon
At ingest
Through an an API call

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.