@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

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

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

Returns

• {:ok, image} or

• {:error, reason}

notes

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 and image or raising an exception.

arguments

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

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

Returns

• image or

• raises an exception

notes

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

Arguments

• image is any t:Vimage.t/0

• options is a Keyword.t/0 list of options

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

Returns

• {:ok, image} or

• {:error, reason}

notes

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

Arguments

• image is any t:Vimage.t/0

• options is a Keyword.t/0 list of options

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

Returns

• image or

• raises an exception

notes

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

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

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.

• :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 impage. THe default is [0, 0].

returns

Returns

• {:ok, image} or

• {:error, reason}

notes

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

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

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.

• :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 impage. THe default is [0, 0].

returns

Returns

• image or

• raises an exception

notes

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(Vix.Vips.Image.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

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

Options

The applicable options vary slightly depending on whether :autofit is set to true or false.

When false (the default), the text is rendered using svg and therefore separate text stroke color, text fill colour, text stroke width cand font weight an be specified. However the size of the text box will be determined by the combination of the font size and text length - there is no line wrapping.

If true the text is formatted to fit within the options :width and :height and the text is sized to fit within the box. :height can be ommitted and it will expand to fit the text of the specified size.

Options for when autofit: false

• :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

• :text_stroke_color is the color of the outline of each character in the string. The default is "none".

• :text_stroke_width is the integer width in pixels of the outline of each character in the string. The default is 1

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

Options for when autofit: true

• :width is the width of the generated text image.

• :height is the height of the generated text image.

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

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

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

Options applicable in all cases

• :font is any font recognised on the host system. The default is"Helvetica".

• :font_weight is the font weight. The alternatives are :normal, :bold, :lighter, :bolder, or an integer between 1 and 1_000. The default is :normal which is equivalent to 400.

returns

Returns

• {:ok, image} or

• {:error, reason}

notes

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 simple_text!(Vix.Vips.Image.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

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

Options

The applicable options vary slightly depending on whether :autofit is set to true or false.

When false (the default), the text is rendered using svg and therefore separate text stroke color, text fill colour, text stroke width cand font weight an be specified. However the size of the text box will be determined by the combination of the font size and text length - there is no line wrapping.

If true the text is formatted to fit within the options :width and :height and the text is sized to fit within the box. :height can be ommitted and it will expand to fit the text of the specified size.

Options for when autofit: false

• :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

• :text_stroke_color is the color of the outline of each character in the string. The default is "none".

• :text_stroke_width is the integer width in pixels of the outline of each character in the string. The default is 1

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

Options for when autofit: true

• :width is the width of the generated text image.

• :height is the height of the generated text image.

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

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

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

Options applicable in all cases

• :font is any font recognised on the host system. The default is"Helvetica".

• :font_weight is the font weight. The alternatives are :normal, :bold, :lighter, :bolder, or an integer between 1 and 1_000. The default is :normal which is equivalent to 400.

returns

Returns

• image or

• raises an exception

notes

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.

arguments

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

Options

• :font is any font recognised on the host system. The default is"Helvetica".

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

• :font_weight is the font weight. The alternatives :normal, :bold, :lighter, :bolder, or an integer between 1 and 1_000. The default is :normal which is equivalent to 400.

• :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

• :text_stroke_color is the color of the outline of each character in the string. The default is "none".

• :text_stroke_width is the integer width in pixels of the outline of each character in the string. The default is 1.

• :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 impage. THe default is [0, 0].

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

• :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

Returns

• {:ok, image} or

• {:error, reason}

notes

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

arguments

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

Options

• :font is any font recognised on the host system. The default is"Helvetica".

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

• :font_weight is the font weight. The alternatives :normal, :bold, :lighter, :bolder, or an integer between 1 and 1_000. The default is :normal which is equivalent to 400.

• :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

• :text_stroke_color is the color of the outline of each character in the string. The default is "none".

• :text_stroke_width is the integer width in pixels of the outline of each character in the string. The default is 1.

• :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 impage. THe default is [0, 0].

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

• :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

Returns

• image or

• raises an exception

notes

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