View Source Image.Histogram (image v0.53.0)

A histogram is a graphical representation of the tonal distribution in a digital image. It plots the number of pixels for each tonal value. By looking at the histogram for a specific image a viewer will be able to judge the entire tonal distribution at a glance.

The horizontal axis of the graph represents the tonal variations, while the vertical axis represents the total number of pixels in that particular tone.

The left side of the horizontal axis represents the dark areas, the middle represents mid-tone values and the right hand side represents light areas. The vertical axis represents the size of the area (total number of pixels) that is captured in each one of these zones.

Thus, the histogram for a very dark image will have most of its data points on the left side and center of the graph.

Conversely, the histogram for a very bright image with few dark areas and/or shadows will have most of its data points on the right side and center of the graph.

The histograms generated in this module have red, green, blue and luminance layers and can be returned as either an svg string or as an t:Vimage.t/0.

The current implementation does not applying any scale compression or expansion and therefore where the image has very wide tonality differences the differences may be difficult to distinguish if :height is small.

Summary

Histogram

as_image(image, options \\ [])

Returns an image representing a red, green, blue and luminance histogram for an image.

as_image!(image, options \\ [])

Returns an image representing a red, green, blue and luminance histogram for an image or raises an exception.

as_svg(image, options \\ [])

Returns an svg string representing a red, green, blue and luminance histogram for an image.

as_svg!(image, options \\ [])

Returns an svg string representing a red, green, blue and luminance histogram for an image or raises an exception.

Histogram

Link to this function

as_image(image, options \\ [])

View Source (since 0.36.0) 
@spec as_image(Vix.Vips.Image.t(), Image.Options.Histogram.histogram_options()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Returns an image representing a red, green, blue and luminance histogram for an image.

Arguments

Options

  • :width is the integer width of the SVG image. The default is :auto which means the image is sized to its parent container.

  • :height is the integer height of the SVG image. The default is :auto which means the image is sized to its parent container.

Returns

  • {:ok, histogram_image} or

  • {:error, reason}.

Histogram image sizing

With Image.Histogram.as_image/2 it is recommended that the :width and/or :height options be provided (in pixels) to ensure the image is generated at the desired size.

The default of :auto will generate an image the size of the underlying SVG viewbox which is 255 pixels wide and 255 pixels high.

Link to this function

as_image!(image, options \\ [])

View Source (since 0.36.0) 
@spec as_image!(Vix.Vips.Image.t(), Image.Options.Histogram.histogram_options()) ::
  Vix.Vips.Image.t() | no_return()

Returns an image representing a red, green, blue and luminance histogram for an image or raises an exception.

Arguments

Options

  • :width is the integer width of the SVG image. The default is :auto which means the image is sized to its parent container.

  • :height is the integer height of the SVG image. The default is :auto which means the image is sized to its parent container.

Returns

  • histogram_image or

  • raises an exception.

Histogram image sizing

With Image.Histogram.as_image/2 it is recommended that the :width and/or :height options be provided (in pixels) to ensure the image is generated at the desired size.

The default of :auto will generate an image the size of the underlying SVG viewbox which is 255 pixels wide and 255 pixels high.

Link to this function

as_svg(image, options \\ [])

View Source (since 0.36.0) 
@spec as_svg(Vix.Vips.Image.t(), Image.Options.Histogram.histogram_options()) ::
  {:ok, String.t()} | {:error, Image.error_message()}

Returns an svg string representing a red, green, blue and luminance histogram for an image.

Arguments

Options

  • :width is the integer width of the SVG image. The default is :auto which means the image is sized to its parent container.

  • :height is the integer height of the SVG image. The default is :auto which means the image is sized to its parent container.

Returns

  • {:ok, svg_string} or

  • {:error, reason}.

Histogram image sizing

SVG will, by default, resize to fit its parent container in an HTMl page. Image.Histogram.as_svg/2 will generate SVG with a default width and height of auto the reflects this intent.

In some cases, such as generating images with Image.Histogram.as_image/2, :width and :height options should be provided (in pixels) to ensure the image is generated at the desired size.

Attribution

Thanks to Alex Plescan for the inspiration for the SVG design.

Link to this function

as_svg!(image, options \\ [])

View Source (since 0.36.0) 
@spec as_svg!(Vix.Vips.Image.t(), Image.Options.Histogram.histogram_options()) ::
  String.t() | no_return()

Returns an svg string representing a red, green, blue and luminance histogram for an image or raises an exception.

Arguments

Options

  • :width is the integer width of the SVG image. The default is :auto which means the image is sized to its parent container.

  • :height is the integer height of the SVG image. The default is :auto which means the image is sized to its parent container.

Returns

  • svg_string or

  • raises an exception.

Histogram image sizing

SVG will, by default, resize to fit its parent container in an HTMl page. Image.Histogram.as_svg/2 will generate SVG with a default width and height of auto the reflects this intent.

In some cases, such as generating images with Image.Histogram.as_image/2, :width and :height options should be provided (in pixels) to ensure the image is generated at the desired size.

Attribution

Thanks to Alex Plescan for the inspiration for the SVG design.