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) uses additional options specified by one or more Name,Value pair arguments.

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 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: 'AnchorPoint','LeftTop'

Font face of text, specified as the comma-separated pair consisting of 'Font' and 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 the comma-separated pair consisting of 'FontSize' and a positive integer in the range [1,200].

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

Text color, specified as the comma-separated pair consisting of 'TextColor' and a character vector, cell array of character vectors, or matrix. You can specify a different color for each character vector or one color for all character vectors.

  • To specify a color for each text character vector, set TextColor to a cell array of M number of color character vectors. Or, you can set it to an M-by-3 matrix of RGB character vector color values.

  • To specify one color for all text character vectors, set TextColor to either a color character vector or an [R G B] vector of red, green, and blue values.

  • RGB values must be in the range of the image data type. Supported colors: 'blue', 'green', 'red', 'cyan', 'magenta', 'yellow','black', and 'white'.

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

Text box color, specified as the comma-separated pair consisting of 'BoxColor' and a character vector, cell array of character vector, or matrix. You can specify a different color for each text box or one color for all the boxes.

  • To specify a color for each text box, set BoxColor to a cell array of M number of color character vectors. Or, you can set it to an M-by-3 matrix of M number of RGB (red, green, and blue) character vector color values.

  • To specify one color for all the text boxes, set BoxColor to either a color character vector or an [R G B] vector. The [R G B] vector contains the red, green, and blue values.

  • RGB values must be in the range of the image data type. Supported colors: 'blue', 'green', 'red', 'cyan', 'magenta', 'yellow','black', and 'white'.

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

Opacity of text box, specified as the comma-separated pair consisting of 'BoxOpacity' and 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 the comma-separated pair consisting of 'AnchorPoint' and 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