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

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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

@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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

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

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

Arguments

• image is any t:Vimage.t/0

• options is a 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

@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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

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

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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

@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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

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

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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

@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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

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

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

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