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

example

RGB = insertText(I,position,text) returns a truecolor image with text inserted. The input image, I, can be either a truecolor or grayscale image.

example

RGB = insertText(I,position,numericValue) returns a truecolor image with numeric values inserted.

RGB = insertText(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, Color="red".

Examples

collapse all

Open Live Script

Read the image.

I = imread("board.tif");

Create texts 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 with new font size, box color, opacity, and text color.

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

Display the image.

figure
imshow(RGB)
title("Board");

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

Open Live Script

Read the image.

I = imread('peppers.png');

Define the ( x,_y_ ) position for the text and the value.

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

Insert text using the bottom-left as the anchor point.

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

Display the image with the numeric text inserted.

figure
imshow(RGB),title('Numeric values');

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

Display non-ASCII character (U+014C)

OWithMacron=native2unicode([hex2dec('C5') hex2dec('8C')],'UTF-8');
RGB = insertText(RGB,[256 50],OWithMacron,'Font','LucidaSansRegular','BoxColor','w');

Display the image with the numeric text inserted.

figure
imshow(RGB),title('Numeric values');

Figure contains an axes object. The 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 image or an M-by-N 2-D grayscale image.

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

Unicode text, specified as a single UNICODE text string or a cell array of UNICODE strings of length M, where M is the number of rows in position. The function overwrites pixels with the value of text. The length of the cell array must equal the number of rows in the position matrix. If you specify a single string, 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: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Numeric value text, specified as a scalar or a vector. If you specify a scalar value, that value is used for all positions. The vector length must equal the number of rows in the position matrix. Numeric values are converted to a character vector using the sprintf format '%0.5g'.

Data Types: char

Position of inserted text, specified as a vector or an M-by-2 matrix of [x y] coordinates. Each row represents the [x y] coordinate for the AnchorPoint of the text bounding 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.

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

Example: Font="Calibri" sets the font face to Calibri.

Font face of text, specified as a character vector. 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, type listTrueTypeFonts at the MATLAB® command prompt.

Data Types: char

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

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

Text color, specified as a character vector, cell array of character vectors, vector, or M-by-3 matrix. You can specify a different color for each text string or one color for all text strings. Color values must be specified in the range [0,255]. Values that have a range of [0,1] must be scaled by a value of 255 before using it with this function. For example, [255 255 255].*colorvalue

Supported colors are: "blue", "green", "red", "cyan", "magenta", "yellow","black", and "white".

ColorFormatExample
Specify one color for all text strings

String or character color name

"r"

"red"

1-by-3 vector (RGB triplet)

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

Specify a color for each text stringM-element vector

["red","yellow","blue"]

M-by-3 matrix, as a list of RGB values

255 0 0
255 0 0
0 255 255
M-by-3 grid, with columns labeled r,g,b respectively.

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

Box color, specified as a character vector, cell array of character vectors, vector, or an M-by-3 matrix. You can specify a different color for each box or one color for all boxes. Color values must be specified in the range [0,255]. Values that have a range of [0,1] must be scaled by a value of 255 before using it with this function. For example, [255 255 255].*colorvalue.

Supported colors are: "blue", "green", "red", "cyan", "magenta", "yellow","black", and "white".

ColorFormatExample
Specify one color for all boxes

String or character color name

"r"

"red"

1-by-3 vector (RGB triplet)

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

Specify a color for each boxM-element vector

["red","yellow","blue"]

M-by-3 matrix, as a list of RGB values

255 0 0
255 0 0
0 255 255
M-by-3 grid, with columns labeled r,g,b respectively.

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

Opacity of text box, specified as a scalar value in the range [0,1]. A value of 0 corresponds to a fully transparent text box, or no box. A value of 1 corresponds to a fully opaque text box.

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

Text box reference point, specified as a character vector value. The anchor point defines a relative location on the text box. You can position the text box by placing its anchor point at the [x,y] coordinate defined by the corresponding position for the text. For example, to place the center of the text box to be at the [x,y] coordinate you specified with the position input, then set AnchorPoint to Center.

Supported positions are LeftTop, LeftCenter, LeftBottom, CenterTop, Center, CenterBottom, RightTop, RightCenter, and RightBottom.

Data Types: char

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 characters in the output image, it means that the font did not contain the character. Select a different font. To get a list of available fonts on your system, at the MATLAB prompt, type 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

See Also

| | |

Topics