Expand all

ThumbnailWidthCalculator

A helper class for bucketing image sizes. Bucketing helps to avoid cache fragmentation and thus speed up image loading: instead of generating potentially hundreds of different thumbnail sizes, we restrict ourselves to a short list of acceptable thumbnail widths, and only ever load thumbnails of that size. Final size adjustment is done in a thumbnail.

See also the Standardized thumbnail sizes RFC.

Constructor

new ThumbnailWidthCalculator([options]) #

Parameters:

Name Type Attributes Description
options Object optional
Properties:
Name Type Attributes Description
widthBuckets Array.<number> optional

see ThumbnailWidthCalculator#widthBuckets
devicePixelRatio number optional

see ThumbnailWidthCalculator#devicePixelRatio; will be autodetected if omitted
Source:

Properties

devicePixelRatio #

Screen pixel count per CSS pixel.

Properties:

Type Description
number
Source:
Screen pixel count per CSS pixel.

widthBuckets #

List of thumbnail width bucket sizes, in pixels.

Properties:

Type Description
Array.<number>
Source:
List of thumbnail width bucket sizes, in pixels.

Methods

calculateFittingWidth(boundingWidth, boundingHeight, sampleWidth, sampleHeight) → {number}protected #

Finds the largest width for an image so that it will still fit into a given bounding box, based on the size of a sample (some smaller version of the same image, like the thumbnail shown in the article) which is used to calculate the ratio.

This is for internal use, you should probably use calculateWidths() instead.

Parameters:

Name Type Description
boundingWidth number

width of the bounding box
boundingHeight number

height of the bounding box
sampleWidth number

width of the sample image
sampleHeight number

height of the sample image
Source:

Returns:

the largest width so that the scaled version of the sample image fits into the bounding box (either horizontal or vertical edges touch on both sides).

Type
number

Finds the largest width for an image so that it will still fit into a given bounding box, based on the size of a sample (some smaller version of the same image, like the thumbnail shown in the article) which is used to calculate the ratio.

calculateWidths(boundingWidth, boundingHeight, sampleWidth, sampleHeight) → {ThumbnailWidth} #

Finds the largest width for an image so that it will still fit into a given bounding box, based on the size of a sample (some smaller version of the same image, like the thumbnail shown in the article) which is used to calculate the ratio.

Returns two values, a CSS width which is the size in pixels that should be used so the image fits exactly into the bounding box, and a real width which should be the size of the downloaded image in pixels. The two will be different for two reasons:

  • Images are bucketed for more efficient caching, so the real width will always be one of the numbers in this.widthBuckets. The resulting thumbnail will be slightly larger than the bounding box so that it takes roughly the same amount of bandwidth and looks decent when resized by the browser.
  • For devices with high pixel density (multiple actual pixels per CSS pixel) we want to use a larger image so that there will be roughly one image pixel per physical display pixel.

Parameters:

Name Type Description
boundingWidth number

width of the bounding box, in CSS pixels
boundingHeight number

height of the bounding box, in CSS pixels
sampleWidth number

width of the sample image (in whatever - only used for aspect ratio)
sampleHeight number

height of the sample image (in whatever - only used for aspect ratio)
Source:

Returns:

Type
ThumbnailWidth

Finds the largest width for an image so that it will still fit into a given bounding box, based on the size of a sample (some smaller version of the same image, like the thumbnail shown in the article) which is used to calculate the ratio.

findNextBucket(target) → {number} #

Finds the smallest bucket which is large enough to hold the target size (i. e. the smallest bucket whose size is equal to or greater than the target). If none of the buckets are large enough, returns the largest bucket.

Parameters:

Name Type Description
target number
Source:

Returns:

Type
number

Finds the smallest bucket which is large enough to hold the target size (i.