View Source Image.Text (image v0.32.0)
Functions for the creation of images from text.
Link to this section 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.
Link to this section 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
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
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
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 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
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
Returns
image
orraises 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 anyt:Vimage.t/0
options
is aKeyword.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 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
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 anyt:Vimage.t/0
options
is aKeyword.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 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
Returns
image
orraises 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 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
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 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 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
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 impage. THe default is[0, 0]
.
returns
Returns
image
orraises 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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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 and font weight can 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 is1
:font_size
is an integer font size in pixels. The default is50
.
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 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
.: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 between1
and1_000
. The default is:normal
which is equivalent to400
.
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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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 is1
:font_size
is an integer font size in pixels. The default is50
.
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 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
.: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 between1
and1_000
. The default is:normal
which is equivalent to400
.
returns
Returns
image
orraises 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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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 is50
.: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: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 is1
.: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 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 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
.: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
.: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
.
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 withPhoenix.HTML.raw/1
on the string first.options
is aKeyword.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 is50
.: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: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 is1
.: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 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 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
.: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
.: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
.
returns
Returns
image
orraises 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".