Insert Text

Draw text on image or video stream.

Library

Text & Graphics

visiontextngfix

Description

The Insert Text block draws formatted text or numbers on an image or video stream. The block uses the FreeType 2.3.5 library, an open-source font engine, to produce stylized text bitmaps. To learn more about the FreeType Project, visit https://www.freetype.org/. The Insert Text block does not support character sets other than ASCII.

The Insert Text block lets you draw one or more instances of text including:

• A single instance of text

• Multiple instances of the same text

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

Port Description

Port	Description	Supported Data Types
Image	M-by-N matrix of intensity values or an M-by-N-by-P color video signal where P represents the number of color planes.	Double-precision floating point Single-precision floating point Fixed point(signed, word length less than or equal to 32.) Boolean 8-, 16-, 32-bit signed integer 8-, 16-, 32-bit unsigned integer
R, G, B	Matrix that represents one plane of the RGB video stream. Outputs from the R, G, or B ports have the same dimensions and data type.	Same as Input port
Select	One-based index value that indicates which text to display.	Double-precision floating point. (This data type is only supported if the input to the I or R, G, and B ports is a floating-point data type.) Single-precision floating point. (This data type is only supported if the input to the I or R, G, and B ports is a floating-point data type.) Boolean 8-, 16-, 32-bit signed integer 8-, 16-, 32-bit unsigned integer
Variables	Vector or matrix whose values are used to replace ANSI C printf-style format specifications.	The data types supported by this port depend on the conversion specification you are using in the Text parameter. %d, %i, and %u: 8-, 16-, 32-bit signed integer 8-, 16-, 32-bit unsigned integer %c and %s: 8-bit unsigned integer %f: Double-precision floating point Single-precision floating point %o, %x, %X, %e, %E, %g, and %G: Double-precision floating point Single-precision floating point 8-, 16-, 32-bit signed integer 8-, 16-, 32-bit unsigned integer
Color	Intensity input — Scalar value used for all character vectors or a vector of intensity values whose length is equal to the number of character vectors. Color input — Three-element vector that specifies one color for all of the character vectors or anM-by-3 matrix of color values, where M represents the number of character vectors.	Same as Input port (The input to this port must be the same data type as the input to the Input port.)
Location	M-by-2 matrix of one-based [x y] coordinates, where M represents the number of text character vectors to insert. Location specifies the top-left corner of the text character vector bounding box.	Double-precision floating point. (This data type is only supported if the input to the I or R, G, and B ports is a floating-point data type.) Single-precision floating point. (This data type is only supported if the input to the I or R, G, and B ports is a floating-point data type.) Boolean 8-, 16-, 32-bit signed integer 8-, 16-, 32-bit unsigned integer
Opacity	Scalar value that is used for all character vectors or vector of opacity values whose length is equal to the number of character vectors.	Double-precision floating point. (This data type is only supported if the input to the Input or R, G, and B ports is a double-precision floating-point data type.) Single-precision floating point. (This data type is only supported if the input to the I or R, G, and B ports is a single-precision floating-point data type.) ufix8_En7 (This data type is only supported if the input to the I or R, G, and B ports is a fixed-point data type.)

Row-Major Data Format

MATLAB^® and the Computer Vision Toolbox™ blocks use column-major data organization. However, the Insert Text block gives you the option to process data that is stored in row-major format. When you select the Input image is transposed (data order is row major) check box, the block assumes that the input buffer contains contiguous data elements from the first row first, then data elements from the second row second, and so on through the last row. Use this functionality only when you meet all the following criteria:

• You are developing algorithms to run on an embedded target that uses the row-major format.

• You want to limit the additional processing required to take the transpose of signals at the interfaces of the row-major and column-major systems.

When you use the row-major functionality, you must consider the following issues:

• When you select this check box, the first two signal dimensions of the Insert Text block's input are swapped.

• All Computer Vision Toolbox software blocks can be used to process data that is in the row-major format, but you need to know the image dimensions when you develop your algorithms.

  For example, if you use the 2-D FIR Filter block, you need to verify that your filter coefficients are transposed. If you are using the Rotate block, you need to use negative rotation angles, etc.

• Only three blocks have the Input image is transposed (data order is row major) check box. They are the Chroma Resampling, Deinterlacing, and Insert Text blocks. You need to select this check box to enable row-major functionality in these blocks. All other blocks must be properly configured to process data in row-major format.

Use the following two-step workflow to develop algorithms in row-major format to run on an embedded target.

Parameters

Text

Specify the text character vector to be drawn on the image or video stream. This parameter can be a single text character vector, such as 'Figure1', a cell array of character vectors, such as {'Figure1','Figure2'}, or an ANSI C printf-style format specifications, such as %s.. To create a Select port enter a cell array of character vectors. To create a Variables port, enter ANSI C printf-style format specifications, such as %d, %f, or %s.

When you enter a cell array of character vectors, the Insert Text block does not display all of the character vectors simultaneously. Instead, the Select port appears on the block to let you indicate which text character vectors to display. The input to this port must be a scalar value, where 1 indicates the first character vector. If the input is less than 1 or greater than one less than the number of character vectors in the cell array, no text will be drawn on the image or video frame.

When you enter ANSI C printf-style format specifications, such as %d, %f, or %s, the Variables port appears on the block. The block replaces the format specifications in the Text parameter with each element of the input vector . Use the %s option to specify a set of text character vectors for the block to display simultaneously at different locations. For example, using a Constant block, enter [uint8('Text1') 0 uint8('Text2')] for the Constant value parameter. The following table summarizes the supported conversion specifications.

Text Parameter Supported Conversion Specifications

Supported specifications	Support for multiple instances of the same specification	Support for mixed specifications
%d, %i, %u, %c, %f, %o, %x, %X, %e, %E, %g, and %G	Yes	No
%s	No	No

Color value source

Select where to specify the text color. Your choices are:

• Specify via dialog — the Color value parameter appears on the dialog box.

• Input port — the Color port appears on the block.

Color value

Specify the intensity or color of the text. This parameter is visible if, for the Color source parameter, you select Specify via dialog. Tunable.

The following table describes how to format the color of the text character vectors, which depend on the block input and the number of character vectors you want to insert. Color values for a floating-point data type input image must be between 0 and 1. Color values for an 8-bit unsigned integer data type input image must between 0 and 255.

Text Character Vector Color Values

Block Input	One Text Character Vector	Multiple Text Character Vectors
Intensity image	Color value parameter or the input to the Color port specified as a scalar intensity value	Color value parameter or the input to the Color port specified as a vector of intensity values whose length is equal to the number of character vectors.
Color image	Color value parameter or the input to the Color port specified as an RGB triplet that defines the color of the text	Color value parameter or the input to the Color port specified as an M-by-3 matrix of color values, where M represents the number of character vectors.

Location source

Indicate where you want to specify the text location. Your choices are:

• Specify via dialog — the Location [x y] parameter appears on the dialog box.

• Input port — the Location port appears on the block.

Location [x y]

Specify the text location. This parameter is visible if, for the Location source parameter, you select Specify via dialog. Tunable.

The following table describes how to format the location of the text character vectors depending on the number of character vectors you specify to insert. You can specify more than one location regardless of how many text character vectors you specify, but the only way to get a different text character vector at each location is to use the %s option for the Text parameter to specify a set of text character vectors. You can enter negative values or values that exceed the dimensions of the input image or video frame, but the text might not be visible.

Location Parameter Text Character Vector Insertion

Parameter	One Instance of One Text Character Vector	Multiple Instances of the Same Text Character Vector	Multiple Instances of Unique Text Character Vector
Location [x y] parameter setting or the input to the Location port	Two-element vector of the form [x y] that indicates the top-left corner of the text bounding box.	M-by-2 matrix, where M represents the number of locations at which to display the text . Each row contains the coordinates of the top-left corner of the text bounding box for the character vector, e.g., [x1 y1; x2 y2]	M-by-2 matrix, where M represents the number of text character vectors. Each row contains the coordinates of the top-left corner of the text bounding box for the character vector, e.g., [x1 y1; x2 y2].

Opacity source

Indicate where you want to specify the text's opaqueness. Your choices are:

• Specify via dialog — the Opacity parameter appears on the dialog box.

• Input port — the Opacity port appears on the block.

Opacity

Specify the opacity of the text. This parameter is visible if, for the Opacity source parameter, you select Specify via dialog. Tunable.

The following table describes how to format the opacity of the text character vectors depending on the number of character vectors you want to insert.

Text String Opacity Values

Parameter	One Text String	Multiple Text Strings
Opacity parameter setting or the input to the Opacity port	Scalar value between 0 and 1, where 0 is translucent and 1 is opaque	Vector whose length is equal to the number of character vectors

Use the Image signal parameter to specify how to input and output a color video signal:

• One multidimensional signal — the block accepts an M-by-N-by-P color video signal, where P is the number of color planes, at one port.

• Separate color signals — additional ports appear on the block. Each port accepts one M-by-N plane of an RGB video stream.

Image signal

Specify how to input and output a color video signal. If you select One multidimensional signal, the block accepts an M-by-N-by-P color video signal, where P is the number of color planes, at one port. If you select Separate color signals, additional ports appear on the block. Each port accepts one M-by-N plane of an RGB video stream.

Input image is transposed (data order is row major)

When you select this check box, the block assumes that the input buffer contains data elements from the first row first, then data elements from the second row second, and so on through the last row.

Font face

Specify the font of your 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 X Server's font path for font files.

Font size (points)

Specify the font size.

Anti-aliased

Select this check box if you want the block to smooth the edges of the text. This can be computationally expensive. If you want your model to run faster, clear this check box.