Main Content

insertText

Insert text in image or video

collapse all in page

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

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.

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

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

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

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

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

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.

SpecificationFormatExample
Specify one color for all shapes (or markers)

Short color name or color name

"r"

"red"

RGB triplet

[1 0 0]1-by-3 grid, with columns labeled r,g,b respectively.

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]
M-by-3 grid, with columns labeled r,g,b respectively.

This table lists the supported marker colors.

Color NameShort NameRGB TripletAppearance
"red""r"[1 0 0]

Sample of the color red

"green""g"[0 1 0]

Sample of the color green

"blue""b"[0 0 1]

Sample of the color blue

"cyan" "c"[0 1 1]

Sample of the color cyan

"magenta""m"[1 0 1]

Sample of the color magenta

"yellow""y"[1 1 0]

Sample of the color yellow

"black""k"[0 0 0]

Sample of the color black

"white""w"[1 1 1]

Sample of the color white

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

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

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

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

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

Version History

Introduced in R2013a

expand all

See Also

| | |

Topics
Go to top of page