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.

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

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

Insert Text into Image

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

Insert Numeric Values into Image

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

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");

Input Arguments

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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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"
	RGB triplet	[1 0 0]
Specify a color for each shape (or marker)	Vector of color names	["red","yellow","blue"]
	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	Appearance
"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]

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

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.

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 strings, specify FontColor as a color name or an [R G B] vector.

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

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.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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

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

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