insertText

Insert text in image or video

Syntax

RGB = insertText(I,position,text)

RGB = insertText(I,position,numericValue)

RGB = insertText(___,Name=Value)

Description

RGB = insertText(I,position,text) insert text into the truecolor or grayscale image I. The function returns a truecolor image.

example

RGB = insertText(I,position,numericValue) inserts numeric values into the input image.

example

RGB = insertText(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of input arguments from previous syntaxes. For example, FontColor="red" renders the inserted text or numeric values in red.

Examples

collapse all

Insert Text into Image

Open Live Script

Read the image into the workspace.

I = imread("board.tif");

Create text string that contain fractions.

text_str = cell(3,1);
conf_val = [85.212 98.76 78.342]; 
for ii = 1:3
   text_str{ii} = ['Confidence: ' num2str(conf_val(ii), '%0.2f') '%'];
end

Define the positions and colors of the text boxes.

position = [23 373; 35 185; 77 107]; 
box_color = {"red","green","yellow"};

Insert the text strings with their respective box colors, and specify the font size, opacity, and text color of all strings.

RGB = insertText(I,position,text_str,FontSize=18,TextBoxColor=box_color, ...
    BoxOpacity=0.4,TextColor="white");

Display the image with annotations.

figure
imshow(RGB)
title("Board")

Figure contains an axes object. The hidden axes object with title Board contains an object of type image.

Insert Numeric Values into Image

Open Live Script

Read the image into the workspace.

I = imread("peppers.png");

Define the numeric values and their xy-positions.

position =  [1 50; 100 50];
value = [555 pi];

Insert the numeric values using the bottom-left corner of each text box as its anchor point.

RGB = insertText(I,position,value,AnchorPoint="LeftBottom");

Display the image with the numeric values inserted.

figure
imshow(RGB)
title("Numeric Values")

Figure contains an axes object. The hidden axes object with title Numeric Values contains an object of type image.

Insert the Unicode U+014C into the image.

OWithMacron = native2unicode([hex2dec("C5") hex2dec("8C")],"UTF-8");
RGB = insertText(RGB,[256 50],OWithMacron,font="LucidaSansRegular",TextBoxColor="white");

Display the image with the Unicode character inserted.

figure
imshow(RGB)
title("Numeric Values");

Figure contains an axes object. The hidden axes object with title Numeric Values contains an object of type image.

Input Arguments

collapse all

`I` — Input image
M-by-N-by-3 truecolor image | M-by-N grayscale image

Input image, specified as an M-by-N-by-3 truecolor or an M-by-N grayscale image.

Data Types: single | double | int16 | uint8 | uint16

`text` — Unicode text character vector
character vector | string scalar | M-element cell array of character vectors | M-element string array

Unicode text, specified as a character vector, string scalar, M-element cell array of character vectors, or M-element string array. M is the number of specified text positions in position. The function overwrites pixels with the value of text. If you specify a single string or character vector, the function uses it for all positions in the position matrix. Most unicode fonts contain ASCII characters. You can display non-English and English characters, including English numeric values, with a single font.

Data Types: char | string | cell

`numericValue` — Numeric value text
numeric scalar | M-element numeric vector

Numeric value text, specified as a numeric scalar or an M-element numeric vector. M is the number of specified positions in position. If you specify a scalar value, the function uses that value for all specified positions. The function converts each numeric value to a character vector using the sprintf format '%0.5g'.

Data Types: numeric

`position` — Position of inserted text
M-by-2 matrix

Position of the inserted text, specified as M-by-2 matrix. M is the number of specified text positions, and each row specifies the xy-coordinates of the AnchorPoint of a text box.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: insertText(I,position,text,Font="Calibri") sets the font face to Calibri.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: insertText(I,position,text,"Font","Calibri") sets the font face to Calibri.

`Font` — Font face of text
`"LucidaSansRegular"` (default) | character vector | string scalar

Font face of the text, specified as a character vector or a string scalar. The font face must be one of the available truetype fonts installed on your system. To get a list of available fonts on your system, use the listTrueTypeFonts function from the MATLAB^® command prompt.

Data Types: char | string

`FontSize` — Font size
`12` (default) | positive integer in range [1, 200]

Font size, specified as a positive integer in the range [1, 200] in pixels.

`FontColor` — Font color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

Font color, specified as a short color name, color name, vector of color names, three-column matrix of RGB triplets.

The supported colors table lists RGB intensities in the range [0, 1], but you must specify RGB triplets in the range of your selected data type. For example, if specifying this argument as a matrix of uint8 values, you must convert each intensity value to the range [0, 255]. To convert the listed intensity values to a uint8 data type, use the code uint8(255*intensity), where intensity is an RGB triplet value listed in the table.

You can specify a different color for each font string or one color for all strings. To specify one color for all markers, specify FontColor as a color name or an [R G B] vector.

Specification	Format	Example
Specify one color for all shapes (or markers)	Short color name or color name	`"r"` `"red"`
Specify one color for all shapes (or markers)	RGB triplet	`[1 0 0]`
Specify a color for each shape (or marker)	Vector of color names	`["red","yellow","blue"]`
Specify a color for each shape (or marker)	Three-column matrix of RGB triplets	[1 0 0 0 1 1 1 0 1 1 1 1]

This table lists the supported marker colors.

Color Name	Short Name	RGB Triplet
`"red"`	`"r"`	`[1 0 0]`
`"green"`	`"g"`	`[0 1 0]`
`"blue"`	`"b"`	`[0 0 1]`
`"cyan"`	`"c"`	`[0 1 1]`
`"magenta"`	`"m"`	`[1 0 1]`
`"yellow"`	`"y"`	`[1 1 0]`
`"black"`	`"k"`	`[0 0 0]`
`"white"`	`"w"`	`[1 1 1]`

`TextBoxColor` — Text box color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

Text box color, specified as a short color name, color name, vector of color names, three-column matrix of RGB triplets.

You can specify a different color for each font string or one color for all strings. To specify one color for all strings, specify FontColor as a color name or an [R G B] vector.

`BoxOpacity` — Text box opacity
`0.6` (default) | scalar in the range of [`0` `1`]

Text box opacity of the text label box background, specified as a scalar in the range of [0, 1]. A value of 0 renders the background of the label text box as fully transparent, while a value of 1 renders it as fully opaque.

`AnchorPoint` — Text box reference point
`"LeftTop"` (default) | `"LeftCenter"` | `"LeftBottom"` | `"CenterTop"` | `"Center"` | `"CenterBottom"` | `"RightTop"` | `"RightCenter"` | `"RightBottom"`

Text box reference point, specified as one of these values:

"LeftTop"
"LeftCenter"
"LeftBottom"
"CenterTop"
"Center"
"CenterBottom"
"RightTop"
"RightCenter"
"RightBottom"

The anchor point defines the relative location on each text box. You can position the text box specified by the corresponding row of position. For example, to place the center of the text box at the xy-coordinate specified by position, set AnchorPoint to Center.

Data Types: char | string

Output Arguments

collapse all

`RGB` — Output image
M-by-N-by-3 truecolor image

Output image, returned as an M-by-N-by-3 truecolor image with the specified text inserted.

Limitations

If you do not see a character in the output image, then the specified font does not contain the character. Select a different font. To get a list of available fonts on your system, at the MATLAB command prompt, enter listTrueTypeFonts.
Increasing the font size also increases the preprocessing time and memory usage.
The insertText function does not work for certain composite characters. For example, you cannot insert text when the rendering of one glyph corresponding to a character code influences the position, shape, or size of the adjacent glyph.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Font and FontSize must be compile-time constants.
Non-ASCII characters are not supported.
Code generation requires a C++ compiler. For a list of supported compilers, see Supported and Compatible Compilers

Version History

Introduced in R2013a

expand all

R2023b: Specify RGB color in the range [0,1]

Starting in R2023b, you can specify marker color with RGB values in the range [0,1].

insertText

Syntax

Description

Examples

Insert Text into Image

Insert Numeric Values into Image

Input Arguments

`I` — Input image
M-by-N-by-3 truecolor image | M-by-N grayscale image

`text` — Unicode text character vector
character vector | string scalar | M-element cell array of character vectors | M-element string array

`numericValue` — Numeric value text
numeric scalar | M-element numeric vector

`position` — Position of inserted text
M-by-2 matrix

Name-Value Arguments

`Font` — Font face of text
`"LucidaSansRegular"` (default) | character vector | string scalar

`FontSize` — Font size
`12` (default) | positive integer in range [1, 200]

`FontColor` — Font color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

`TextBoxColor` — Text box color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

`BoxOpacity` — Text box opacity
`0.6` (default) | scalar in the range of [`0` `1`]

`AnchorPoint` — Text box reference point
`"LeftTop"` (default) | `"LeftCenter"` | `"LeftBottom"` | `"CenterTop"` | `"Center"` | `"CenterBottom"` | `"RightTop"` | `"RightCenter"` | `"RightBottom"`

Output Arguments

`RGB` — Output image
M-by-N-by-3 truecolor image

Limitations

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

R2023b: Specify RGB color in the range [0,1]

See Also

Topics

insertText

Syntax

Description

Examples

Insert Text into Image

Insert Numeric Values into Image

Input Arguments

I — Input image M-by-N-by-3 truecolor image | M-by-N grayscale image

text — Unicode text character vector character vector | string scalar | M-element cell array of character vectors | M-element string array

numericValue — Numeric value text numeric scalar | M-element numeric vector

position — Position of inserted text M-by-2 matrix

Name-Value Arguments

Font — Font face of text "LucidaSansRegular" (default) | character vector | string scalar

FontSize — Font size 12 (default) | positive integer in range [1, 200]

FontColor — Font color "green" (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

TextBoxColor — Text box color "green" (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

BoxOpacity — Text box opacity 0.6 (default) | scalar in the range of [0 1]

AnchorPoint — Text box reference point "LeftTop" (default) | "LeftCenter" | "LeftBottom" | "CenterTop" | "Center" | "CenterBottom" | "RightTop" | "RightCenter" | "RightBottom"

Output Arguments

RGB — Output image M-by-N-by-3 truecolor image

Limitations

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Version History

R2023b: Specify RGB color in the range [0,1]

See Also

Topics

`I` — Input image
M-by-N-by-3 truecolor image | M-by-N grayscale image

`text` — Unicode text character vector
character vector | string scalar | M-element cell array of character vectors | M-element string array

`numericValue` — Numeric value text
numeric scalar | M-element numeric vector

`position` — Position of inserted text
M-by-2 matrix

`Font` — Font face of text
`"LucidaSansRegular"` (default) | character vector | string scalar

`FontSize` — Font size
`12` (default) | positive integer in range [1, 200]

`FontColor` — Font color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

`TextBoxColor` — Text box color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

`BoxOpacity` — Text box opacity
`0.6` (default) | scalar in the range of [`0` `1`]

`AnchorPoint` — Text box reference point
`"LeftTop"` (default) | `"LeftCenter"` | `"LeftBottom"` | `"CenterTop"` | `"Center"` | `"CenterBottom"` | `"RightTop"` | `"RightCenter"` | `"RightBottom"`

`RGB` — Output image
M-by-N-by-3 truecolor image

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.