Main Content

Insert Text

Draw text on images or video frames

  • Library:
  • Computer Vision Toolbox / Text & Graphics

  • Insert Text block

Description

The Insert Text block draws formatted text on an input image or video stream. The block produces stylized text bitmaps using the open-source font engine Free Type 2.3.5 library. For more information about the library, see The FreeType Project website.

Note

This block supports only ASCII characters.

This block enables you to draw:

  • A single instance of text

  • Multiple instance of the same text

  • Multiple instances of text, with different text at each location

Ports

Input

expand all

Input image or video, specified as an M-by-N matrix, M-by-N-by-T array, M-by-N-by-C array, or M-by-N-by-C-by-T array. T is the number of frames in a video or image sequence, and C is the number of color channels.

Dependencies

To enable this port, set the Image signal parameter to One multidimensional signal.

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

Red color component of the input image or video, specified as an M-by-N matrix or M-by-N-by-T array, where T is the number of frames in the input video.

Note

Inputs to the R, G, and B ports must have the same dimensions and data type.

Dependencies

To enable this port, set the Image signal parameter to Separate color signals.

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

Green color component of the input image or video, specified as an M-by-N matrix or M-by-N-by-T array, where T is the number of frames in the input video.

Note

Inputs to the R, G, and B ports must have the same dimensions and data type.

Dependencies

To enable this port, set the Image signal parameter to Separate color signals.

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

Blue color component of the input image or video, specified as an M-by-N matrix or M-by-N-by-T array, where T is the number of frames in the input video.

Note

Inputs to the R, G, and B ports must have the same dimensions and data type.

Dependencies

To enable this port, set the Image signal parameter to Separate color signals.

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

Select text string, specified as a positive integer. When the value of the Text parameter is a cell array of character vectors, the Insert Text block displays the text string from only the cell indicated by the input value of the Select port. Input to this port must be in the range from 1 to the number of text strings in the cell array, where 1 indicates the first character vector.

Dependencies

To enable this port, specify the Text parameter as a cell array of character vectors, such as {'Text1','Text2'}.

Data Types: single | double

Text color value, specified as a scalar, vector or matrix. The data type of the input image determines the range of color values. For example, a color value for a floating-point input image data type must be in the range [0, 1]. For an input image with a uint8 data type, the value must be in the range [0, 255]. The shape of the input to this port depends on whether the input signal is intensity-based or color.

  • Intensity signal — Specify Color as either a scalar intensity value, in which case the block applies the intensity to all text strings, or as a vector of intensity values of length equal to the number of text strings specified to the Text parameter.

  • Color signal — Specify Color as either a three-element vector that defines the color of all text strings as an RGB triplet, or an S-by-3 matrix of color values, where S is the number of text strings specified to the Text parameter.

Note

The input to this port must be of the same data type as the input image.

Dependencies

To enable this port, set the Color value source parameter to Input port.

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

Location index, a two-element vector or an S-by-2 matrix, specifies the coordinates of input image at which to insert the text. If specified as a two-element vector, the first element represents the row and the second element represents the column of the image at which to insert the character vector. If specified as an S-by-2 matrix, each row contains the row and column indices of a location in the image at which to display the text.

Dependencies

To enable this port, set the Location source parameter to Input port.

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

Opacity factor, specified as a scalar or a vector. If specified as a scalar, the opacity factor applies to all text strings. If specified as a vector of opacity values, the length of the vector must be equal to the number of text strings specified in the Text parameter. Each element of the opacity factor can range from 0 to 1.

Dependencies

To enable this port, set the Opacity source parameter to Input port.

Data Types: single | double

Text variable values, specified as scalar or vector. The block replaces the format specifications in the Text parameter, such as %d, %f, or %s, with the elements of this input. Use the %s option to specify a set of text strings separated with a value 0 for the block to display simultaneously at different locations. For example, to insert two strings, use a Constant (Simulink) block, and specify its value to [uint8('Text1') 0 uint8('Text2')] at Variables input port. For more information on format specifiers see sprintf.

Dependencies

To enable this port, enter ANSI C printf-style format specifications, such as %d, %f, or %s to the Text parameter.

Data Types: uint8 | double

Output

expand all

Output image or video, returned as an M-by-N matrix, M-by-N-by-T array, M-by-N-by-C array, or M-by-N-by-C-by-T array. T is the number of frames in a video or image sequence, and C is the number of color channels.

Dependencies

To enable this port, set the Image signal parameter to One multidimensional signal.

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

Red color component of the output image or video, returned as an M-by-N matrix or M-by-N-by-T array, where T is the number of frames in the output video.

Dependencies

To enable this port, set the Image signal parameter to Separate color signals.

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

Green color component of the output image or video, returned as an M-by-N matrix or M-by-N-by-T array, where T is the number of frames in the output video.

Dependencies

To enable this port, set the Image signal parameter to Separate color signals.

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

Blue color component of the output image or video, returned as an M-by-N matrix or M-by-N-by-T array, where T is the number of frames in the output video.

Dependencies

To enable this port, set the Image signal parameter to Separate color signals.

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

Parameters

expand all

Main

Specify the text to insert into the input image.

  • You can specify this parameter as either a single text string or character vector, such as 'Text1', or as a cell array of character vectors, such as {'Text1','Text2'}. If you specify a cell array, then you must also specify which text string to display by using the Select input port.

  • You can include ANSI C printf-style format specifications, such as 'Text %d'. You must then specify their values by using the Variable input port. Supported format specifiers include %d, %i, %u, %c, %f, %o, %x, %X, %e, %E, %g, and %G. For more information on format specifiers see sprintf.

Select a text color source from these options: Specify via dialog and Input port. If you set this parameter to Specify via dialog, then you must specify text colors by using the Color value parameter. If you set this parameter to Input port, then you must specify text colors by using the Color input port.

Text color value, specified as a scalar, vector or matrix. The data type of the input image determines the range of color values. For example, a color value for a floating-point input image data type must be in the range [0, 1]. For an input image with a uint8 data type, the value must be in the range [0, 255]. The size of the text color value depends on whether the input signal is intensity-based or color.

  • Intensity signal — Specify Color as either a scalar intensity value, in which case the block applies the intensity to all text strings, or as a vector of intensity values of length equal to the number of text strings specified to the Text parameter.

  • Color signal — Specify Color as either a three-element vector that defines the color of all text strings as an RGB triplet, or an S-by-3 matrix of color values, where S is the number of text strings specified to the Text parameter.

Dependencies

To enable this parameter, set the Color value source parameter to Specify via dialog.

Select a text location source from these options: Specify via dialog and Input port. If you set this parameter to Specify via dialog, then you must specify text locations by using the Location [x y] parameter. If you set this parameter to Input port, then you must specify text locations by using the Location input port.

Text location index, a two-element vector or an S-by-2 matrix, specifies the coordinates of input image at which to insert the text. If specified as a two-element vector, the first element represents the row and the second element represents the column of the image at which to insert the character vector. If specified as an S-by-2 matrix, each row contains the row and column indices of a location in the image at which to display the text.

Dependencies

To enable this parameter, set the Location source parameter to Specify via dialog.

Select the opacity factor source from these options: Specify via dialog and Input port. If you set this parameter to Specify via dialog, then you must specify opacity factor by using the Opacity parameter. If you set this parameter to Input port then you must specify opacity factor by using the Opacity input port.

Opacity factor, specified as a scalar or a vector. If specified as a scalar, the opacity factor applies to all text strings. If specified as a vector of opacity values, the length of the vector must be equal to the number of text strings specified in the Text parameter. Each element of the opacity factor can range from 0 to 1.

Dependencies

To enable this parameter, set the Opacity source parameter to Specify via dialog.

Specify the format of the input and output images of the block using these options:

  • One multidimensional signal — The block has a single input port and single output port.

  • Separate color signals — The block has three input and output signals, one for each color channel, which accept and return the individual color channels of the image.

Enable this parameter to mirror the text string and reverse its location in the image from [x y] to [y x].

Font

Specify the font of the inserted text. The block populates this list with the fonts installed on your system. On Windows, the block searches the system registry for font files. On UNIX, the block searches the font path of the X Server for font files.

Specify the font size of the inserted text.

Enable this parameter to smooth the edges of the inserted text. The smoothing process is computationally expensive.

Block Characteristics

Data Types

Boolean | double | fixed point[a] | integer | single

Multidimensional Signals

yes

Variable-Size Signals

yes

[a] Supports word lengths less than or equal to 32 bits.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.

Introduced in R2013a