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) returns a truecolor image with text inserted. The input image, I, can be either a truecolor or grayscale image.

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

Insert Numbers and Text on Image

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

Insert Numeric Text on Image

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

Display non-ASCII character (U+014C)

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

Display the image with the numeric text inserted.

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

Input Arguments

I — Input image

M-by-N-by-3 truecolor | M-by-N 2-D grayscale image

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

text — Unicode text character vector

character vector | string scalar | cell array of character vectors | string array

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

numericValue — Numeric value text

scalar | vector

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 — Position of inserted text

vector | matrix

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

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'AnchorPoint','LeftTop'

'Font' — Font face of text

'LucidaSansRegular' (default) | character vector

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

'FontSize' — Font size

12 (default) | positive integer in the range [1,200]

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

'TextColor' — Text color

'black' (default) | character vector | cell array of character vectors | [R G B] vector | M-by-3 matrix

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

'BoxColor' — Text box color

'yellow' (default) | character vector | cell array of character vectors | [R G B] vector | M-by-3 matrix

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

'BoxOpacity' — Opacity of text box

0.6 (default) | scalar value in the range of [0 1]

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

'AnchorPoint' — Text box reference point

'LeftTop' (default) | 'LeftCenter' | 'LeftBottom' | 'CenterTop' | 'Center' | 'CenterBottom' | 'RightTop' | 'RightCenter' | 'RightBottom'

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

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Font, FontSize must be compile-time constants.

• Non-ASCII characters are not supported.