View Source Image.Blurhash (image v0.55.2)

BlurHash is an algorithm developed by Wolt that allows encoding of an image into a compact string representation called a blurhash. This string can then be decoded back into an image, providing a low-resolution placeholder that can be displayed quickly while the actual image is being loaded.

It combines the benefits of data compression and perceptual hashing to create visually pleasing representations of images.

The blurhash string consists of a short sequence of characters that represents the image's colors and their distribution. By adjusting the length of the blurhash, you can control the level of detail and the amount of data required to represent the image.

The encode and decoder in this implementation are a fork of the rinpatch_blurhash library by @rinpatch.

Summary

Operations

decode(blurhash, width, height)

Decodes an blurhash to an image.

encode(image, options \\ [])

Encodes an image as a blurhash.

Operations

Link to this function

decode(blurhash, width, height)

View Source (since 0.44.0) 
@spec decode(blurhash :: String.t(), width :: pos_integer(), height :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Decodes an blurhash to an image.

Arguments

  • blurhash is a blurhash returned by Image.Blurhash.encode/2.

  • width is the required width of the returned image.

  • height is the required height of the returned image.

Returns

  • {:ok, image} or

  • {:error, reason}

Examples 

iex> image = Image.open!("./test/support/images/Kip_small.jpg")
iex> {:ok, blurhash} = Image.Blurhash.encode(image)
iex> {:ok, _image} = Image.Blurhash.decode(blurhash, 400, 200)

iex> Image.Blurhash.decode("nonsense", 400, 200)
{:error, "Invalid blurhash"}
Link to this function

encode(image, options \\ [])

View Source (since 0.44.0) 
@spec encode(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, String.t()} | {:error, Image.error_message()}

Encodes an image as a blurhash.

Image.Blurhash.encode/2 takes an image and returns a short string (only 20-30 characters) that represents the placeholder for this image.

It is intended that calculating a blurhash is performed in a background process and stored for retrieval on demand when rendering a page.

Arguments

  • image is any Vix.Vips.Image.t/0. Only 3-band images are supported by blurhash. Therefore if image has an alpha band it is necessary to flatten image or remove the alpha band before calling Image.Blurhash.encode/2.

  • options is a keyword list of options. The default is [x_components: 4, y_components: 3].

Options

  • :x_components represents the number of horizontal blocks used to calculate the blurhash.

  • :y_components represents the number of vertical blocks used to calculate the blurhash.

Returns

  • {:ok, blurhash} or

  • {:error, reason}

Selecting the number of X and Y components

A higher :x_components and :y_components value will result in more details in the blurhash in the X and Y direction respectively. A lower value will create a more abstract representation.

By adjusting the X and Y components, you can control the level of granularity and complexity in the generated blurhash. However, it's important to note that increasing the X and Y values also increases the size of the blurhash string, which may impact performance and bandwidth usage.

The default of [x_components: 4, y_components: 3] is a good starting points but if the the image aspect ratio is portrait, a higher :y_compnents value may be appropriate.

Example 

iex> image = Image.open!("./test/support/images/Kip_small.jpg")
iex> Image.Blurhash.encode(image)
{:ok, "LBA,zk9F00~qofWBt7t700%M?bD%"}