View Source Image.Text (image v0.5.0)

Functions for the creation of images from text.

Link to this section Summary

Functions

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

Adds a background to an image generated from text.

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

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

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

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

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

Creates an image from the provided text.

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

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

Link to this section Functions

Link to this function

add_background!(image, options \\ [])

View Source
@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

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".
Link to this function

add_background(image, options \\ [])

View Source
@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

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".
Link to this function

add_background_border!(image, options \\ [])

View Source
@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".
Link to this function

add_background_border(image, options \\ [])

View Source
@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".
Link to this function

add_background_padding!(image, options \\ [])

View Source
@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

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".
Link to this function

add_background_padding(image, options \\ [])

View Source
@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

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".
Link to this function

simple_text!(string, options \\ [])

View Source
@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-escapeed 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 dfault 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.

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

Link to this function

simple_text(string, options \\ [])

View Source
@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-escapeed 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 dfault 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.

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

Link to this function

text!(string, options \\ [])

View Source
@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-escapeed 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 dfault 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".

Link to this function

text(string, options \\ [])

View Source
@spec text(Phoenix.HTML.safe() | String.t(), Keyword.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-escapeed 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 dfault 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".