Support and Documentation

Defining image sizes
Defining image sizes at the theme level

Image sizes are defined in the configuration file (see Configuring a theme) of your theme. To define an image, you will at a minimum need to define the width (or maximumWidth) and height (or maximumHeight).

An example configuration file with a single image size definition would look like the following:

{
  "imageSizes": {
    "MyImageSize": {
      "width": 100,
      "height": 100
    }
  }
}
Defining image sizes at the module level

You can define image sizes at the module level, overriding image sizes at the theme level. You can use all of the keys listed in the table Keys for image size in module-level data files except the following:

Table 67. previewWidth and previewHeight at the module level

Key

Description

Type

previewWidth

This key is available at the module level only if the following are true:

  • previewWidth is present in the theme's _config.json for the same template.

  • width is not present in the theme's _config.json for the same template.

Number

previewHeight

This key is available at the module level only if the following are true:

  • previewHeight is present in the theme's _config.json for the same template.

  • height is not present in the theme's _config.json for the same template.

Number



The following snippet describes the height, width, and source set descriptors for a template Image.hbs. These attributes override any of the contextual rendering settings in the theme's _config.json.

{
  "_template": "Image.hbs",
  "height": "900",
  "width": "1600",
  "srcsetDescriptors": [
    "2x",
    "3x"
  ]
}
Available properties

The following table lists the available properties when defining an image size.

Table 68. Keys for image size

Key

Description

Type

width

Width of rendered image in web page and generated image representation in Styleguide.

Number

height

Height of rendered image in web page and generated image representation in Styleguide.

Number

previewWidth

If width not set, width of image representation in Styleguide. Do not set previewWidth if width is set.

Number

previewHeight

If height not set, height of image representation in Styleguide. Do not set previewHeight if height is set.

Number

maximumWidth

Maximum width of image size. Aspect ratio will be preserved by the resize. If you define maximumWidth, you must also define previewWidth; otherwise, you will get an error.

Number

maximumHeight

Maximum height of image size. Aspect ratio will be preserved by the resize. If you define maximumHeight, you must also define previewHeight; otherwise, you will get an error.

Number

srcsetDescriptors

A list of image density or width descriptors to support different device screen resolutions. For more information, see srcSetDescriptors.

Array of String

format

Specifies the format in which an image is delivered to the client. For more information, see Image format.

String

group

Heading under which an image size appears in the image editor. For more information, see Grouping images in the image editor.

String

displayName

Customized label for an image size in the image editor. For more information, see Image size display names.

String

quality

Specifies an image's visual quality and compression level at run time.

Number



Image size display names

Brightspot's image editor lists the image sizes as they appear in the theme's configuration file _config.json.

{
  "imageSizes": {
    "square-small-62x62": {
      "width": 62,
      "height": 62
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84
    },
    "square-large-765x765": {
      "width": 765,
      "height": 765
    }
  }
}

In the previous snippet, Brightspot displays the names square-small-62x6, square-medium-84x84, and square-large-765x765. See the left image in the table Image-size labels.

You can provide a more intuitive name for each image size using the displayName key.

{
  "imageSizes": {
    "square-large-765x765": {
      "width": 765,
      "height": 765,
      "displayName": "Huge Square" 1
    },
    "square-small-62x62": {
      "width": 62,
      "height": 62,
      "displayName": "Small Square" 2
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84,
      "displayName": "Medium Square" 3
    }
  }
}

1

Custom name for the image size square-large-765x765.

2

Custom name for the image size square-small-62x62.

3

Custom name for the image size square-medium-84x84.

The following illustrations provide examples default and customized image-size names.

Table 69. Image-size labels
Default image-size names
Figure 189. Default image-size names


Customized image-size names
Figure 190. Customized image-size names




Grouping images in the image editor

Editors can set a focus point on images. If your theme has many image sizes and orientations, the editors may want to place the focus point in different locations.

Focus point on portrait orientation
Figure 191. Focus point on portrait orientation


Focus point on square orientation
Figure 192. Focus point on square orientation


Referring to the previous illustrations, the focus point is in the bottom-right quadrant of the portrait image; in comparison, the focus point is in the top-left quadrant of the square image.

If you have multiple images with the same aspect ratio, the focus point is always in the same place, scaled for the image size. For example, if an image is 1000 × 500 with a focus point at (100, 250), and another image is 2000 × 1000, the focus point for the second image is scaled to (200, 500). This implies that an editor can set a focus point once for all images with the same aspect ratio, and Brightspot scales the focus point when performing crops.

You can group images into the same or similar aspect ratio using the group key under imageSizes.

{
  "imageSizes": {
    "80x80": {
      "width": 80,
      "height": 80,
      "group": "square" 1
    },
    "100x100": {
      "width": 100,
      "height": 100,
      "group": "square"
    },
    "150x100": {
      "width": 150,
      "height": 100,
      "group": "landscape" 2
    }
}

1

Groups images under a label Square in the image editor.

2

Groups images under a label Landscape in the image editor.

When detecting at least one group key in the theme, Brightspot displays a selection field containing all of the groups.

group-selector-displayed.svg

When an editor selects one of the groups and sets a focus point, Brightspot applies and scales the focus point to all associated image sizes.

Image format

By default, Brightspot delivers images to a client in the format in which they are stored. For example, if you upload an image as a PNG, Brightspot delivers the image in the same format.

You can force Brightspot to deliver images of a given size in a given format—regardless of the format in which the image is stored. This feature is useful if you ingest or upload multiple images in one format, and want to deliver them to the browser in a different format. (If your travel editor took one thousand jaw-dropping photographs during a safari and uploaded them to Brightspot as PNGs, you can force Brightspot to convert the images to JPGs.)

The following table lists the available formats and their suggested uses.

Table 70. Available image formats

Extension

Name

Suggested Use

png

Portable Network Graphic

Transparency.

gif

Graphics Interchange Format

Animation, small images with fewer than 256 colors.

jpg

Joint Photographic Experts Group

All other uses.



This feature is available if you configured DIMS as the image editor; for details, see Image editor configuration.

You can use any of the extensions in the table Available image formats with the format key inside the elements of an imageSizes array.

{
  "imageSizes": {
    "small": {
      "format": "jpg" 1
    }
  }
}

1

Delivers as jpg all usages of the small image size.

Brightspot delivers the file by retrieving the original file and running it through a file converter as indicated in the following URL.

target-online-image-format.svg

Referring to the previous illustration, Brightspot constructs an image's src attribute from the original file's name bowtie.png and an instruction to an online service for conversion to the jpg format. When the browser submits this request to the server, the image editor performs the conversion.

. See also:
Examples
Fixed image size

Setting both width and height dimensions results in a fixed image size. A fixed image size may result in cropping if the image size does not reflect the aspect ratio of the original image.

The following image-size snippet defines a square shape, with equal width and height dimensions.

{
  "imageSizes": {
    "square-medium-200x200": {
      "width": 200,
      "height": 200
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, with a 2:1 aspect ratio, the result is a 200×200 square image that is cropped because the image size does not reflect the aspect ratio of the original image. Brightspot first creates an image rendition that maintains the aspect ratio of the landscape image. In this example, the ratio is 2:1, so Brightspot resizes the image to 400×200. Brightspot then crops the width of the rendition to fit it into a 200×200 image size.

200×200 square
Figure 193. 200×200 square


The next image-size snippet defines a landscape shape, with the width greater than the height.

{
  "imageSizes": {
    "landscape-large-500x250": {
      "width": 500,
      "height": 250
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, the result is a scaled-down landscape image. The image is also uncropped because the image size reflects the aspect ratio of the original image, 2:1.

500×250 landscape
Figure 194. 500×250 landscape


The next image-size snippet defines a portrait image, with the height greater than the width.

{
  "imageSizes": {
    "portrait-medium-200x400": {
      "width": 200,
      "height": 400
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, the result is a 200×400 portrait image. Maintaining the 2:1 aspect ratio, Brightspot resizes the image to 800×400, which is the image rendition. To fit the image into a portrait-oriented size, Brightspot crops the width.

200×400 portrait
Figure 195. 200×400 portrait


Maintaining aspect ratio

As an alternative to a fixed image size, you can have Brightspot calculate the size by specifying only one image dimension, width or height, or by using width or height in conjunction with a maximumHeight or a maximumWidth key. As in a fixed image size, Brightspot creates an image rendition based on the aspect ratio of the image, but Brightspot does not crop the rendition to fit a fixed size. In essence, the image rendition dimensions determine the image size.

The maximumWidth and maximumHeight keys can restrict the width or height of an image while preserving the aspect ratio. For example, say that you have a 1000×500 landscape image, with a 2:1 aspect ratio. The following snippet specifies that the resulting image size not exceed a height of 200.

{
  "imageSizes": {
    "auto-small-400xauto": {
      "width": 400,
      "maximumHeight": 200,
      "previewHeight": 200
    }
  }
}

Maintaining the 2:1 aspect ratio, Brightspot resizes the image to 400×200, which is the image rendition. Because the computed height does not exceed maximum height, the resulting image size is 400×200.

400×200
Figure 196. 400×200


Using the width and previewHeight values, Styleguide generates a 400×200 image representation.

image-sizes.png

If the image size defined in the above snippet is applied to a 500×500 square image, with a 1:1 aspect ratio, the resulting image size is different. Maintaining the 1:1 aspect ratio of the image, Brightspot initially computes a height of 400, which exceeds the maximum height. Brightspot then resizes the image to 200×200 to maintain aspect ratio. (In Styleguide, the image is represented with a 400×200 size.)

200×200
Figure 197. 200×200


srcSetDescriptors

To accommodate image display on devices with different resolutions, the srcsetDescriptors key specifies density descriptors or width descriptors. This key provides support for the HTML srcset attribute. Brightspot generates images of different densities or widths, and the browser determines the applicable image based on the device screen resolution or viewport size.

Note

You cannot combine width descriptors and density descriptors.

Use density descriptors for images that should maintain the same width across devices, but should vary by resolution to support displays with different pixel densities. For example, the following image snippet specifies a density array of 2x and 3x.

{
  "imageSizes": {
    "landscape-small-300x200": {
      "width": 300,
      "height": 200,
      "srcsetDescriptors": [
             "2x",
             "3x"
       ]
    }
  }
}

This results in the following srcset attribute in the HTML image tag:

<img src="src.png" srcset="src-2.png 2x, src-3.png 3x" />

Use width descriptors for images that are likely to change in width, especially in responsive designs. With width descriptors, images vary in width based on the size of the viewport.

For example, the following image snippet specifies a width array of "1000w" and "2000w".

{
  "imageSizes": {
    "auto-large-autox1000": {
      "maximumWidth": 2000,
      "previewWidth": 2000,
      "height": 1000,
      "srcsetDescriptors": [
             "1000w",
             "2000w"
       ]
    }
  }
}

This results in the following srcset attribute in the HTML image tag. If the viewport is 1000 pixels wide or smaller, the image will be 100% of the viewport width, and the browser will use the src-1000.png image. If the viewport is wider than 1000 pixels, the browser will use the src-2000.png image.

<img src="src.png" srcset="src-1000.png 1000w, src-2000.png 2000w" sizes="(max-width: 1000px) 100vw, 2000px" />