View Source Image.Text (image v0.54.3)
Functions for the creation of images from text.
Summary
Functions
Adds a background to an image generated from text.
Adds a background to an image generated from text returning and image or raising an exception.
Adds a border on an image, typically an image generated from a string.
Adds a border on an image, typically an image generated from a string. Returns an image or raises an exception.
Adds padding to a background to an image generated from text.
Adds padding to a background to an image generated from text returning an image or raising an exception.
Creates an image from the provided text.
Creates an image from the provided text and returns an image or raises an exception.
Create a new image from the provided string and formatting options.
Create a new image from the provided string and formatting options returning an image or raising an exception.
Functions
@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 anyt:Vimage.t/0
but is expected to be an image generated byImage.Text.text/2
.options
is aKeyword.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 between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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 and image or raising an exception.
Arguments
image
is anyt:Vimage.t/0
but is expected to be an image generated byImage.Text.text/2
.options
is aKeyword.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 between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.7
.
Returns
image
orraises 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 anyt:Vimage.t/0
options
is aKeyword.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 is1
.:background_stroke_opacity
is the opacity of the background string. It is a float between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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 anyt:Vimage.t/0
options
is aKeyword.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 is1
.:background_stroke_opacity
is the opacity of the background string. It is a float between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.7
.
Returns
image
orraises 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 anyt:Vimage.t/0
but is expected to be an image generated byImage.Text.add_background/2
.options
is aKeyword.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 between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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 at: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 anyt:Vimage.t/0
but is expected to be an image generated byImage.Text.add_background/2
.options
is aKeyword.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 between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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 at: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
orraises 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(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
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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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. A black background will be forced if a:background_fill_color
is not provided:dpi
sets the resolution of the text generation. The default72
which is suitable for screen output.300
may be more appropriate for printed output.: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 is50
. If set to0
, 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 isfalse
.: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 commandfc-list
can be used to see what fonts are available.:font_weight
is the font weight. The alternatives are:normal
,:bold
,:lighter
,:bolder
, or an integer between1
and1_000
. The default is:normal
which is equivalent to400
.
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!(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
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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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. A black background will be forced if a:background_fill_color
is not provided:font_size
is an integer font size in pixels. The default is50
.:dpi
sets the resolution of the text generation. The default72
which is suitable for screen output.300
may be more appropriate for printed output.: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 is50
. If set to0
, 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 isfalse
.: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 commandfc-list
can be used to see what fonts are available.:font_weight
is the font weight. The alternatives are:normal
,:bold
,:lighter
,:bolder
, or an integer between1
and1_000
. The default is:normal
which is equivalent to400
.
Returns
image
orraises 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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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".:font_size
is an integer font size in pixels. The default is50
.:dpi
sets the resolution of the text generation. The default72
which is suitable for screen output.300
may be more appropriate for printed output.:font_weight
is the font weight. The alternatives:normal
,:bold
,:lighter
,:bolder
, or an integer between1
and1_000
. The default is:normal
which is equivalent to400
.: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 between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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 at: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. 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 is1
.:background_stroke_opacity
is the opacity of the background string. It is a float between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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.: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".
@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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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".:font_size
is an integer font size in pixels. The default is50
.:dpi
sets the resolution of the text generation. The default72
which is suitable for screen output.300
may be more appropriate for printed output.:font_weight
is the font weight. The alternatives:normal
,:bold
,:lighter
,:bolder
, or an integer between1
and1_000
. The default is:normal
which is equivalent to400
.: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 between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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 at: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. 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 is1
.:background_stroke_opacity
is the opacity of the background string. It is a float between0.0
and1.0
where0.0
means transparent and1.0
means opaque. The default is0.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.: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
orraises 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".