Video and Image Processing Blockset™

Insert Text - Draw text on image or video stream

Library

Text & Graphics

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 http://www.freetype.org/.

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

A single instance of one text string
Multiple instances of one text string
Multiple instances of text, with a different text string at each location

Input/Output	Description
Image	M-by-N matrix of intensity values or an M-by-N-by-P color video signal where P is the number of color planes.
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.
Select	Zero-based index value that indicates which text string to display.
Variables	Vector or matrix whose values are used to replace ANSI C `printf`-style format specifications.
Color	Intensity input — Scalar value used for all strings or 1-by-N vector of intensity values whose length is equal to the number of strings. Color input — Three-element vector that specifies one color for all strings or a 3-by-N matrix of color values, where N is the number of strings.
Location	2-by-N matrix, where N is the number of text strings to insert, that specifies the top-left corner of the text string bounding boxes.
Opacity	Scalar value that is used for all strings or vector of opacity values whose length is equal to the number of strings.

Use the Text parameter to specify the text string to be drawn on the image or video frame. This parameter can be a single text string, such as 'Figure1', a cell array of strings, such as {'Figure1','Figure2'}, or an ANSI C printf-style format specifications, such as %s.

If, for the Text parameter, you enter a cell array of strings, the Insert Text block does not display all of the strings simultaneously. Instead, the Select port appears on the block to let you indicate which text string to display. The input to this port must be a scalar value, where 0 indicates the first string. If the input is less than 0 or greater than one less than the number of strings in the cell array, the block does not draw text on the image or video frame.

If, for the Text parameter, 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 in turn. Use the %s option to specify a set of text strings 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

Use the Location source parameter to indicate where to specify the text location:

Specify via dialog — the Location [row column] parameter appears on the dialog box.
Input port — the Location port appears on the block.

The following table describes how to format the location of the text strings depending on the number of strings you specify to insert. You can specify more than one location regardless of how many text strings you specify, but the only way to get a different text string at each location is to use the %s option for the Text parameter to specify a set of text strings. 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 String Insertion

Parameter	One Instance of One Text String	Multiple Instances of the Same Text String	Multiple Instances of Unique Text Strings
Location [row column] parameter setting or the input to the Location port	Two-element vector of the form [rowcolumn] that indicates the top-left corner of the text bounding box.	2-by-N matrix, where N is the number of locations at which to display the text string. Each column indicates the row and column coordinate of the top-left corner of the text bounding box for the string, e.g., `[[row1 column1]' [row2 column2]']`	2-by-N matrix, where N is the number of text strings. Each column indicates the row and column coordinate of the top-left corner of the text bounding box for the corresponding string, e.g., `[[row1 column1]' [row2 column2]']`.

Use the Color value source parameter to indicate where to specify the text color:

Specify via dialog — the Color value parameter appears on the dialog box.
Input port — the Color port appears on the block.

The following table describes how to format the color of the text strings depending on the block input and the number of strings you want to insert. If the input image is a floating-point data type, the color values must be between 0 and 1. If the input image is an 8-bit unsigned integer data type, the color values must range between 0 and 255.

Text String Color Values

Block Input	One Text String	Multiple Text Strings
Intensity image	Color value parameter or the input to the Color port = Scalar intensity value	Color value parameter or the input to the Color port = Vector of intensity values whose length is equal to the number of strings
Color image	Color value parameter or the input to the Color port = RGB triplet that specifies the color of the text	Color value parameter or the input to the Color port = 3-by-N matrix of color values, where N is the number of strings

Use the Opacity source parameter to indicate where to specify the text's opaqueness:

Specify via dialog — the Opacity parameter appears on the dialog box.
Input port — the Opacity port appears on the block.

The following table describes how to format the opacity of the text strings depending on the number of strings 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 strings

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.

Use the Font face parameter to specify the font of your text. The block populates this list with the TrueType 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.

Use the Font size (points) parameter to specify the font size.

If you select the Anti-aliased check box, the block smooths the edges of the text, which can be computationally expensive. If you want your model to run faster, clear this check box.

Row-Major Data Format

MATLAB and the Video and Image Processing Blockset 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 Video and Image Processing Blockset 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.

See the DM642 EVM Video ADC and DM642 EVM Video DAC reference pages in the Target Support Package TC6 User's Guide for more information about data order in embedded targets.

Examples

See Annotating AVI Files with Video Frame Numbers and Annotating AVI Files at Two Separate Locations in the Video and Image Processing Blockset User's Guide. Many of the Video and Image Processing Blockset Demos make use of the Insert Text block.

Dialog Box

The Main pane of the Insert Text dialog box appears as shown in the following figure.

Text

Specify the text string to be drawn on the image or video stream. This parameter can be a single text string or a cell array of strings. To create a Select port enter a cell array of strings. To create a Variables port, enter ANSI C printf-style format specifications, such as %d, %f, or %s.

Color value source

Indicate where you want to specify the text color. Your choices are Specify via dialog or Input port.

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.

Location source

Indicate where you want to specify the text location. Your choices are Specify via dialog or Input port.

Location [row column]

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

Opacity source

Indicate where you want to specify the text's opaqueness. Your choices are Specify via dialog or Input port.

Opacity

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

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.

The Font pane of the Insert Text dialog box appears as shown in the following figure.

Font face

Specify the font of your text. The block populates this list with the fonts installed on your system.

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.

Supported Data Types

Port	Supported Data Types
Input/Image	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	Same as Input port
Select	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	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	Same as Input port (The input to this port must be the same data type as the input to the Input port.)
Location	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	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.)