# `Image.Histogram`
[🔗](https://github.com/elixir-image/image/blob/v0.66.0/lib/image/histogram.ex#L1)

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](https://en.wikipedia.org/wiki/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.

# `as_image`
*since 0.36.0* 

```elixir
@spec as_image(Vix.Vips.Image.t(), Image.Options.Histogram.histogram_options()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

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

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0`.

* `options` is a keyword list of options.

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

# `as_image!`
*since 0.36.0* 

```elixir
@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

* `image` is any `t:Vix.Vips.Image.t/0`.

* `options` is a keyword list of options.

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

# `as_svg`
*since 0.36.0* 

```elixir
@spec as_svg(Vix.Vips.Image.t(), Image.Options.Histogram.histogram_options()) ::
  {:ok, String.t()} | {:error, Image.error()}
```

Returns an [svg](https://en.wikipedia.org/wiki/SVG) string
representing a red, green, blue and luminance histogram
for an image.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0`.

* `options` is a keyword list of options.

### 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](https://alexplescan.com/posts/2023/07/08/easy-svg-sparklines/)
for the inspiration for the SVG design.

# `as_svg!`
*since 0.36.0* 

```elixir
@spec as_svg!(Vix.Vips.Image.t(), Image.Options.Histogram.histogram_options()) ::
  String.t() | no_return()
```

Returns an [svg](https://en.wikipedia.org/wiki/SVG) string
representing a red, green, blue and luminance histogram for
an image or raises an exception.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0`.

* `options` is a keyword list of options.

### 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](https://alexplescan.com/posts/2023/07/08/easy-svg-sparklines/)
for the inspiration for the SVG design.

---

*Consult [api-reference.md](api-reference.md) for complete listing*