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

Functions for the creation of images from text.

# `add_background`

```elixir
@spec add_background(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Adds a background to an image generated from
text.

### Arguments

* `image` is any `t:Vimage.t/0` but is expected
  to be an image generated by `Image.Text.text/2`.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:background_fill_color` is the background fill color behind
  the text. The default is `:none` which indicates no
  background. Note that if

* `:background_fill_opacity` is the opacity of the background. It is a
  float between `0.0` and `1.0` where `0.0` means transparent
  and `1.0` means opaque. The default is `0.7`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

# `add_background!`

```elixir
@spec add_background!(Vix.Vips.Image.t(), Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Adds a background to an image generated from
text returning an image or raising an exception.

### Arguments

* `image` is any `t:Vimage.t/0` but is expected
  to be an image generated by `Image.Text.text/2`.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:background_fill_color` is the background fill color behind
  the text. The default is `:none` which indicates no
  background.

* `:background_fill_opacity` is the opacity of the background. It is a
  float between `0.0` and `1.0` where `0.0` means transparent
  and `1.0` means opaque. The default is `0.7`.

### Returns

* `image` or

* raises an exception

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

# `add_background_border`

```elixir
@spec add_background_border(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Adds a border on an image, typically an
image generated from a string.

### Arguments

* `image` is any `t:Vimage.t/0`

* `options` is a `t:Keyword.t/0` list of options

### Options

* `:background_stroke_color` is the colour of the outline
  of the background. The default is ":none",

* `:background_stroke_width` is the integer size in pixels
  of the background border. The default is `1`.

* `:background_stroke_opacity` is the opacity of the background
  string. It is a float between `0.0` and `1.0` where `0.0` means
  transparent and `1.0` means opaque. The default is `0.7`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

# `add_background_border!`

```elixir
@spec add_background_border!(Vix.Vips.Image.t(), Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Adds a border on an image, typically an
image generated from a string. Returns an
image or raises an exception.

### Arguments

* `image` is any `t:Vimage.t/0`

* `options` is a `t:Keyword.t/0` list of options

### Options

* `:background_stroke_color` is the colour of the outline
  of the background. The default is "none",

* `:background_stroke_width` is the integer size in pixels
  of the background border. The default is `1`.

* `:background_stroke_opacity` is the opacity of the background
  string. It is a float between `0.0` and `1.0` where `0.0` means
  transparent and `1.0` means opaque. The default is `0.7`.

### Returns

* `image` or

* raises an exception

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

# `add_background_padding`

```elixir
@spec add_background_padding(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Adds padding to a background to an image generated from
text.

### Arguments

* `image` is any `t:Vimage.t/0` but is expected
  to be an image generated by `Image.Text.add_background/2`.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:background_fill_color` is the background fill color behind
  the text. The default is `:none` which indicates no
  background.

* `:background_fill_opacity` is the opacity of the background. It is a
  float between `0.0` and `1.0` where `0.0` means transparent
  and `1.0` means opaque. The default is `0.7`.

* `:padding` is the padding in pixels between the
  text and the edge of the background.  It can be expressed
  as a single integer integer in which case the same padding
  is applied to all four sides of the image.  It can also
  be expressed as a list of two integers like `[0, 0]`.
  The first integer will be used as the padding for the
  left and right of the image. The second integer will be used
  for the top and bottom of the image.  Another alternative is
  to pass a `t:Vimage.t/0` in which case the padding will be derived
  from the image dimensions such that the background covers the
  whole of the image.  The default is `[0, 0]`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

# `add_background_padding!`

```elixir
@spec add_background_padding!(Vix.Vips.Image.t(), Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Adds padding to a background to an image generated from
text returning an image or raising an exception.

### Arguments

* `image` is any `t:Vimage.t/0` but is expected
  to be an image generated by `Image.Text.add_background/2`.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:background_fill_color` is the background fill color behind
  the text. The default is `:none` which indicates no
  background.

* `:background_fill_opacity` is the opacity of the background. It is a
  float between `0.0` and `1.0` where `0.0` means transparent
  and `1.0` means opaque. The default is `0.7`.

* `:padding` is the padding in pixels between the
  text and the edge of the background.  It can be expressed
  as a single integer integer in which case the same padding
  is applied to all four sides of the image.  It can also
  be expressed as a list of two integers like `[0, 0]`.
  The first integer will be used as the padding for the
  left and right of the image. The second integer will be used
  for the top and bottom of the image.  Another alternative is
  to pass a `t:Vimage.t/0` in which case the padding will be derived
  from the image dimensions such that the background covers the
  whole of the image.  The default is `[0, 0]`.

### Returns

* `image` or

* raises an exception

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

# `simple_text`

```elixir
@spec simple_text(String.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Creates an image from the provided text.

This function creates an image from the text
but does not apply a background or padding.

### Arguments

* `string` is any string. The string will be
  HTML-escaped to avoid malicious code injection. If you
  are completely confident that the text is safe then
  you can pass it by calling with `Phoenix.HTML.raw/1`
  on the string first.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:text_fill_color` is the fill color of the text.
  The default is "white". If set to `:transparent` then
  the text will be rendered transparently against
  a background.

* `:width` is the maximum width of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options.

* `:height` is the maximum height of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options.

* `:justify` is a boolean indicating whether to justify text.
  The default is `false`.

* `:letter_spacing` is the amount of space in pixels between each letter.
  Default is `:normal`.

* `:font` is any font recognised on the host system.
  The default is "Helvetica". The system command `fc-list`
  can typically be used to see what fonts are available.

* `:font_weight` is one of `:ultralight`, `:light`, `:normal`, `:bold`,
  `:ultrabold`, `:heavy` or an integer between `1` and `1_000`.
  The default is `:normal` which is equivalent to `400`.

* `:font_size` is an integer font size in pixels. The
  default is `50`. If set to `0`, the font size will
  be calculated to fit the text within the specified `:width`
  and `:height`.

* `:dpi` sets the resolution of the text generation. The
  default `72` which is suitable for screen output. `300`
  may be more appropriate for printed output.

### Returns

* `{:ok, image}` or

* `{:error, reason}`.

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

### Examples

    iex> {:ok, image} = Image.Text.simple_text("hi", font_size: 24)
    iex> Image.bands(image)
    4

# `simple_text!`

```elixir
@spec simple_text!(String.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()
```

Creates an image from the provided text and
returns an image or raises an exception.

This function creates an image from the text
but does not apply a background or padding.

### Arguments

* `string` is any string. The string will be
  HTML-escaped to avoid malicious code injection. If you
  are completely confident that the text is safe then
  you can pass it by calling with `Phoenix.HTML.raw/1`
  on the string first.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:text_fill_color` is the fill color of the text.
  The default is "white". If set to `:transparent` then
  the text will be rendered transparently against
  a background.

* `:width` is the maximum width of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options.

* `:height` is the maximum height of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options.

* `:justify` is a boolean indicating whether to justify text.
  The default is `false`.

* `:letter_spacing` is the amount of space in pixels between each letter.
  Default is `:normal`.

* `:font` is any font recognised on the host system.
  The default is "Helvetica". The system command `fc-list`
  can typically be used to see what fonts are available.

* `:font_weight` is one of `:ultralight`, `:light`, `:normal`, `:bold`,
  `:ultrabold`, `:heavy` or an integer between `1` and `1_000`.
  The default is `:normal` which is equivalent to `400`.

* `:font_size` is an integer font size in pixels. The
  default is `50`. If set to `0`, the font size will
  be calculated to fit the text within the specified `:width`
  and `:height`.

* `:dpi` sets the resolution of the text generation. The
  default `72` which is suitable for screen output. `300`
  may be more appropriate for printed output.

### Returns

* `image` or

* raises an exception.

### Notes

* There is no text wrapping, justification or kerning
  applied. This means this function is not a general
  purpose text layout function and is suitable mostly
  for overlaying text for emphasis over another image.

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

# `text`

```elixir
@spec text(Phoenix.HTML.safe() | String.t(), Image.Options.Text.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Create a new image from the provided string and
formatting options.

`text/2` creates an image with the
following steps:

* Render the text
* Add an optional background color
* Expand the background according to the required padding

The text can be rendered as a positive (the default)
in which an image of the provided string is rendered
in the provided font, weight, size, fill color and
stroke color.

It can also be rendered transparently in which case
a background color is required against which the
transparent text can be composed. If not provided,
the background color will be black.

After rendering the text and composing it against
the (optional) background, the background can
be expanded to provide some padding between the
text and any base image onto which it is later
composed.  The default no padding.

### The Pango markup language

The text string can take advantage of
[Pango markup language](https://docs.gtk.org/Pango/pango_markup.html) that
provides some simple HTML-like text transformation
capabilities. Note that some of the options to `Image.Text.text/2`,
such as `:font_weight` and `:letter_spacing` operate by adding markup
to the provided string.

### Arguments

* `string` is any string. The string will be
  HTML-escaped to avoid malicious code injection. If you
  are completely confident that the text is safe then
  you can pass it by calling with `Phoenix.HTML.raw/1`
  on the string first.

* `options` is a `t:Keyword.t/0` list of options.

### Options

See also the options for `Image.Text.simple_text/2` which
is ultimately called by this function.

* `:font` is any font recognised on the host system.
  The default is "Helvetica". The system command `fc-list`
  can typically be used to see what fonts are available.

* `:font_size` is an integer font size in pixels. The
  default is `50`.

* `:font_weight` is one of `:ultralight`, `:light`, `:normal`, `:bold`,
  `:ultrabold`, `:heavy` or an integer between `1` and `1_000`.
  The default is `:normal` which is equivalent to `400`.

* `:font_file` is a path to any `.ttf` font file. If specfied,
  the `:font` parameter is also required. Note that this option
  is not supported on MacOS systems.

* `:dpi` sets the resolution of the text generation. The
  default `72` which is suitable for screen output. `300`
  may be more appropriate for printed output.

* `:text_fill_color` is the fill color of the text.
  The default is "white". If set to `:transparent` then
  the text will be rendered transparently against
  a background. A black background will be forced if a
  `:background_fill_color` is not provided

* `:background_fill_opacity` is the opacity of the background fill.
  It is a float between `0.0` and `1.0` where `0.0` means transparent
  and `1.0` means opaque. The default is `0.7`.

* `:padding` is the padding in pixels between the
  text and the edge of the background.  It can be expressed
  as a single integer integer in which case the same padding
  is applied to all four sides of the image.  It can also
  be expressed as a list of two integers like `[0, 0]`.
  The first integer will be used as the padding for the
  left and right of the image. The second integer will be used
  for the top and bottom of the image.  Another alternative is
  to pass a `t:Vimage.t/0` in which case the padding will be derived
  from the image dimensions such that the background covers the
  whole of the image.  The default is `[0, 0]`.

* `:align` indicates how multiple lines of text are aligned.
  The options are `:left`, `:right` and `:center`. The default
  is `:left`.

* `:letter_spacing` is the amount of space in pixels between each letter.
  Default is `:normal`.

* `:background_fill_color` is the background fill color behind
  the text. The default is `:none` which indicates no
  background.

* `:background_stroke_color` is the colour of the outline
  of the background. The default is "none",

* `:background_stroke_width` is the integer size in pixels
  of the background border. The default is `1`.

* `:background_stroke_opacity` is the opacity of the background
  string. It is a float between `0.0` and `1.0` where `0.0` means
  transparent and `1.0` means opaque. The default is `0.7`.

* `:width` is the maximum width of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options.

* `:height` is the maximum height of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options. `:height` may only be specified if `:width` is
  also specified.

* `:x` is the horizontal location of the text on its background.
  The value is either a non-negative integer or one of `:left`,
  `:right` or `:center`. The default is `:center` if `:width` is
  specified and `:left` if it is not.

* `:y` is the vertical location of the text on its background.
  The value is either a non-negative integer or one of `:top`,
  `:middle` or `:bottom`. The default is `:middle` if `:height`
  is specified and `:top` if it is not.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

* The options `:font_weight` and `:letter_spacing` are implemented by
  wrapping the text in a [Pango markup](https://docs.gtk.org/Pango/pango_markup.html) `span`
  tag. If the `string` parameter starts with `<span` then these two
  options are ignored since this implies the user is taking full control
  of the markup.

### Examples

    iex> {:ok, text_image} = Image.Text.text("hello", font_size: 24)
    iex> Image.bands(text_image)
    4

    iex> {:ok, _} = Image.Text.text("ok", text_fill_color: :red)
    iex> :ok
    :ok

# `text!`

```elixir
@spec text!(String.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()
```

Create a new image from the provided string and
formatting options returning an image or raising
an exception.

`text!/2` creates an image with the
following steps:

* Render the text
* Add an optional background color
* Expand the background according to the required padding

The text can be rendered as a positive (the default)
in which an image of the provided string is rendered
in the provided font, weight, size, fill color and
stroke color.

It can also be rendered transparently in which case
a background color is required against which the
transparent text can be composed. If not provided,
the background color will be black.

After rendering the text and composing it against
the (optional) background, the background can
be expanded to provide some padding between the
text and any base image onto which it is later
composed.  The default no padding.

### The Pango markup language

The text string can take advantage of
[Pango markup language](https://docs.gtk.org/Pango/pango_markup.html) that
provides some simple HTML-like text transformation
capabilities. Note that some of the options to `Image.Text.text/2`,
such as `:font_weight` and `:letter_spacing` operate by adding markup
to the provided string.

### Arguments

* `string` is any string. The string will be
  HTML-escaped to avoid malicious code injection. If you
  are completely confident that the text is safe then
  you can pass it by calling with `Phoenix.HTML.raw/1`
  on the string first.

* `options` is a `t:Keyword.t/0` list of options

### Options

See also the options for `Image.Text.simple_text/2` which
is ultimately called by this function.

* `:font` is any font name recognised on the host system.
  The default is "Helvetica". The system command `fc-list`
  can typically be used to see what fonts are available.

* `:font_size` is an integer font size in pixels. The
  default is `50`.

* `:font_file` is a path to any `.ttf` font file. If specfied,
  the `:font` parameter is also required. Note that this option
  is not supported on MacOS systems.

* `:font_weight` is one of `:ultralight`, `:light`, `:normal`, `:bold`,
  `:ultrabold`, `:heavy` or an integer between `1` and `1_000`.
  The default is `:normal` which is equivalent to `400`.

* `:dpi` sets the resolution of the text generation. The
  default `72` which is suitable for screen output. `300`
  may be more appropriate for printed output.

* `:text_fill_color` is the fill color of the text.
  The default is "white". If set to `:transparent` then
  the text will be rendered transparently against
  a background. A black background will be forced if a
  `:background_fill_color` is not provided.

* `:background_fill_opacity` is the opacity of the background fill.
  It is a float between `0.0` and `1.0` where `0.0` means transparent
  and `1.0` means opaque. The default is `0.7`.

* `:padding` is the padding in pixels between the
  text and the edge of the background.  It can be expressed
  as a single integer integer in which case the same padding
  is applied to all four sides of the image.  It can also
  be expressed as a list of two integers like `[0, 0]`.
  The first integer will be used as the padding for the
  left and right of the image. The second integer will be used
  for the top and bottom of the image.  Another alternative is
  to pass a `t:Vimage.t/0` in which case the padding will be derived
  from the image dimensions such that the background covers the
  whole of the image.  The default is `[0, 0]`.

* `:align` indicates how multiple lines of text are aligned.
  The options are `:left`, `:right` and `:center`. The default
  is `:left`.

* `:letter_spacing` is the amount of space in pixels between each letter.
  Default is `:normal`.

* `:background_fill_color` is the background fill color behind
  the text. The default is `:none` which indicates no
  background.

* `:background_stroke_color` is the colour of the outline
  of the background. The default is "none",

* `:background_stroke_width` is the integer size in pixels
  of the background border. The default is `1`.

* `:background_stroke_opacity` is the opacity of the background
  string. It is a float between `0.0` and `1.0` where `0.0` means
  transparent and `1.0` means opaque. The default is `0.7`.

* `:width` is the maximum width of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options.

* `:height` is the maximum height of the generated text image in pixels. The
  default is calculated by the rendering engine based upon the font
  and other options. `:height` may only be specified if `:width` is
  also specified.

* `:x` is the horizontal location of the text on its background.
  The value is either a non-negative integer or one of `:left`,
  `:right` or `:center`. The default is `:center` if `:width` is
  specified and `:left` if it is not.

* `:y` is the vertical location of the text on its background.
  The value is either a non-negative integer or one of `:top`,
  `:middle` or `:bottom`. The default is `:middle` if `:height`
  is specified and `:top` if it is not.

### Returns

* `image` or

* raises an exception.

### Notes

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

* The options `:font_weight` and `:letter_spacing` are implemented by
  wrapping the text in a [Pango markup](https://docs.gtk.org/Pango/pango_markup.html) `span`
  tag. If the `string` parameter starts with `<span` then these two
  options are ignored since this implies the user is taking full control
  of the markup.

---

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