Defining image sizes

This section provides information on how to define image sizes at the theme level, module level, and more.

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
    }
  }
}

See also:

• Defining image sizes at the module level
• Image context

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:

previewWidth and previewHeight at the module level

The following snippet describes the height, width, and source set descriptors for a templateImage.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"
  ]
}

See also:

• Defining image sizes at the theme level
• Contextual rendering
• Image context

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

Keys for image size

See also:

• Srcset Width Descriptors
• Images
• How to Build Responsive Images with srcset
• Image URLs
• Creating image sizes
• Retrieving image information

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.

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" 
    },
    "square-small-62x62": {
      "width": 62,
      "height": 62,
      "displayName": "Small Square" 
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84,
      "displayName": "Medium Square" 
    }
  }
}

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

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

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" 
    },
    "100x100": {
      "width": 100,
      "height": 100,
      "group": "square"
    },
    "150x100": {
      "width": 150,
      "height": 100,
      "group": "landscape" 
    }
}

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

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.

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.

Available image formats

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 above with the format key inside the elements of an imageSizes array.

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

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

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:

• Image URLs

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.

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.

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.

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.

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

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.)

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.

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" />

Images you upload to Brightspot can appear differently in different places on the front end. The image may have the native size in some pages, and appear larger or smaller in other pages. Brightspot selects the image size to send to the front end based on the image’s context—a combination of template and placeholder.

{
  "imageSizeContexts": { 
    "/styleguide/Image.hbs": { 
      "image": "large" 
    }
  }
}

Referring to the previous example, the context is the placeholder {{image}} within the template Image.hbs. In this context, Brightspot uses the image size large.

You can define levels of nested context, a technique that promotes template reuse.

{
  "imageSizeContexts": {
    "/styleguide/ByLine.hbs": {
      "/styleguide/Image.hbs": {
        "image": "small"
      },
      "/styleguide/BioPage.hbs": {
        "/styleguide/Image.hbs": {
          "image": "large"
        }
      }
    }
  }
}

In the previous example, there are two contexts for the template Image.hbs:

• One context for a byline under the template ByLine.hbs. In this context, Brightspot provides the image size small to the front end.
• One text for a bio page under the template BioPage.hbs. In this context, Brightspot provides the image size large to the front end.

You can assign an image size to multiple contexts using file globbing.

{
  "imageSizeContexts": {
    "/styleguide/*.hbs": {
      "image": "large"
    }
  }
}

In the previous example, Brightspot uses the image size large in any template whose file name matches the pattern /styleguide/*.hbs. For details about the supported patterns, see Glob Primer.

See also:

• Defining image sizes
• Configuring a theme

After you define image sizes (see Defining image sizes), you can use the {{resize}} helper to apply a resize to an image object. In a Brightspot theme, rendering an <img>tag should almost always include a usage of the {{resize}} helper.

Basic usage
As a simple example, suppose a component MyComponent.hbs that renders an <img> with an image size named small.

MyComponent.hbs

{{#resize image "small"}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

Container usage
A container will often need to define an image size used by its children.

Container.hbs

{{include "Item.hbs" child imageSize="large"}}

Item.hbs

{{#resize image imageSize}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

Providing a fallback
To decouple Item.hbs from Container.hbs, you may want to provide a fallback for when an imageSize property is not specified by a container, or there is no container at all.

Item.hbs

{{#resize image (fallback imageSize "small"}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

In the above example, Item.hbs will render using the small image size, unless a container specifies an imageSize value.

Images with variable helpers
There may be times when the immediate container does not specify the image size necessary. Consider an example in which Page.hbs renders a Container.hbs of Item.hbs, and Page.hbs determines which image size to use.

This could be implemented by passing down the image size through multiple templates:

Page.hbs

{{include "Container.hbs" container itemImageSize="large"}}

Container.hbs

{{include "Item.hbs" child imageSize=itemImageSize}}

Item.hbs

{{#resize image imageSize}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

However, this quickly becomes unwieldy when you need to pass the image size through multiple contexts. To facilitate these scenarios, you can use the {{get}} and {{set}} helpers.

Page.hbs

{{#set imageSize="large"}}
    {{include "Container.hbs" container}}
{{/set}}

Item.hbs

{{#resize image (get "imageSize")}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

Container.hbs

{{include "Item.hbs" child}}

Variables with fallback images
You may also wish to define a fallback for when the image size is not specified, using the {{fallback}} helper:

Item.hbs

{{#resize image (fallback (get "imageSize") "small")}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

This section describes the steps for diagnosing and resolving the most common causes of blurry or missing images in published content.

The techniques described in this section assume you are using the Frost theme, which adds a srcset attribute to <img>tags. In other scenarios, you can use similar techniques to identify the cause of a blurry image.

Troubleshooting blurry images

The following steps help to identify the cause of a blurry image on a published page.

Step 1: Check native image’s size
Brightspot displays images in different sizes depending on the context. If the editor uploaded a very small image, Brightspot likely enlarges it, resulting in a blurry presentation.

Referring to the previous examples, the native image is small, 65 × 65 pixels. The image in the byline is 100 ×100, and in the bio page 240 × 240. At each level of zoom, Brightspot needs to fill in pixels, resulting in a blurry effect.

The best way to check a native image’s size is to view it in a browser or graphic editor. The following instructions apply to the Chrome browser; the procedure for other browsers is similar.

To view a native image:

1. In a published page, right-click the blurry image, and select Inspect from the popup menu.
2. In the Elements tab, right-click the img element and select Copy > Copy element.

3. Paste the element into a text editor.

   • The element contains a srcset attribute for displaying different image sizes on different pixel densities.
   • Each entry in the srcset attribute has the form DIMSurl?NativeImageURLEncoded, as in the following illustration.
     

     

4. Copy and paste the encoded URL into a decoder, such as URL Decoder.
5. Paste the decoded URL into your browser. The image you see is the native image uploaded by the editor.

Result:

• If the image is small, the blurries are due to enlarging the image. Inform the editor to upload a larger image, ideally three times the size of the largest size listed in srcset. (Uploading an image this size allows devices with pixel-density ratios up to 3 to display images without introducing the blurries.)
• If the native image size is large, the blurries are due to another reason. Save the native image to your local drive, and continue to the next step.

Step 2: Check quality of native image
View the native image you saved in Step 1: Check native image’s size in your browser.

Result:

• If the native image is blurry, then no amount of editing (either by Brightspot or by a graphic artist) can make it crisp. Inform the editor to upload a different image.
• If the image is crisp, the blurries are due to another reason. Continue to the next step.

Step 3: Check native image’s pixel density
Images taken with a low-ppi camera or created on a low-ppi monitor appear blurry on high-ppi screens.

Open the native image in a graphic editor and view the ppi, or use the ImageMagick command identify -format “PPI (x,y): %x x %y\n” filename.ext.

Result:

• If the native image’s ppi is much smaller than that of the monitor, the client device is adding pixels to compensate, resulting in a blurry image. Inform the editor to upload a higher ppi image, ideally three times the size of the largest size listed in srcset. (Uploading an image this size allows devices with pixel-density ratios up to 3 to display images without introducing the blurries.)
• If the native image’s ppi is close to that of the native image, search for blurry images on the Internet for other possible resolutions.

Troubleshooting missing images

Images uploaded to Brightspot can be missing in the preview pane or in a published page. The following steps help to identify the cause of a missing image.

Step 1: Check native image’s URL

Ensure the native image’s URL is valid. The following instructions apply to the Chrome browser; the procedure for other browsers is similar.

To verify a native image’s URL:

1. In a published page, right-click the missing image, and select Inspect from the popup menu.
2. In the Elements tab, right-click the img element and select Copy > Copy element.

3. Paste the element into a text editor.

   • The element contains a srcset attribute for displaying different image sizes on different pixel densities.
   • Each entry in the srcset attribute has the form DIMSurl?NativeImageURLEncoded, as in the following illustration.
     

     

4. Copy and paste the encoded URL into a decoder, such as URL Decoder.
5. Paste the decoded URL into your browser.

Result:

• If the image is missing (error 404), or if the URL points to something other than an image, then inform the editor to upload a new image.
• If the URL appears in your browser, continue to the next step.

Step 2: Check native image’s format
Before delivering an image to a client, Brightspot performs some edits, such as cropping and resizing. On some versions of Brightspot, these operations fail on TIFFs. Use the following procedure to determine if this failure is occurring on your version of Brightspot.

1. Examine the URL you pasted into the text editor in Step 1: Check native image’s URL. Does the native URL have a .tifor .tiff extension?
   

   

2. Is there a path parameter format/jpg?

Result:

• If the answer to 1 is Yes and the answer to 2 is No, then the conversion from TIFF to JPG is failing, and the image appears as if missing. Do one of the following:

  • Inform the editor to convert the image to JPG, PNG, or GIF and upload the image again.
  • Update your theme to include the conversion from TIFF to JPG, PNG, or GIF.
• In all other cases, continue to the next step.

Step 3: Check for zero-width crops
Some previous versions of Brightspot intermittently injected zero-width crops.

• Examine the URL you pasted into the text editor in Step 1: Check native image’s URL.

Result:

• If there is a path parameter crop/0x0+0+0, contact your Brightspot representative to receive a patch.
• If there is no crop parameter or if the crop parameter has reasonable dimensions, continue to the next step.

Step 4: Check for access to native image from the DIMS server
At run time, the DIMS server retrieves the native image, performs graphic editing, and delivers the modified image to the client. In this step, you verify the DIMS server has access to the native image.

To check for DIMS access:

1. SSH in to the DIMS server.
2. Use curl or wget to retrieve the missing image, pasting the decoded URL from Step 1: Check native image’s URL into the command line.

Result:

• If the request from the DIMS server fails, perform network debugging to resolve the error. Typical causes are firewalls, timeouts, and allowed/blocked access control.