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. |
|
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. |
|
Variables | Vector or matrix whose values are used to replace ANSI
C | The data types supported by this port depend on the conversion specification you are using in the Text parameter. %d, %i, and %u:
%c and %s:
%f:
%o, %x, %X, %e, %E, %g, and %G:
|
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. |
|
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. |
|
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 Cprintf-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
1indicates the first character vector. If the input is less than1or 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%soption to specify a set of text character vectors for the block to display simultaneously at different locations. For example, using a Constant (Simulink) 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
0and1. Color values for an 8-bit unsigned integer data type input image must between0and255.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 0and1, where0is translucent and1is opaqueVector 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 selectSeparate 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.
See Also
Computer Vision Toolbox | |
Computer Vision Toolbox |