classdef TextInserter
%TextInserter Draw text on image or video stream
%   HTXTINS = vision.TextInserter returns a System object, HTXTINS, that
%   draws formatted text onto an image or video stream.
%
%   HTXTINS = vision.TextInserter('PropertyName', PropertyValue, ...)
%   returns a text inserter object, HTXTINS, with each specified property
%   set to the specified value.
%
%   HTXTINS = vision.TextInserter(TEXT, 'PropertyName', PropertyValue, ...)
%   returns a text inserter object, HTXTINS, with the Text property set to
%   TEXT and other specified properties set to the specified values.
%
%   Step method syntax:
%
%   TXTIMG = step(HTXTINS, IMG) draws the specified text onto input image
%   IMG and returns the modified image TXTIMG. The image IMG can either be
%   an 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.
%
%   TXTIMG = step(HTXTINS, IMG, CELLIDX) draws the text string selected
%   by index, CELLIDX, when the Text property is a cell array of strings.
%   For example, when Text property is {'str1','str2'}, and CELLIDX = 1, 
%   'str1' will be drawn in the image. Values of CELLIDX, outside of valid
%   range result in no text drawn in the image.
%
%   TXTIMG = step(HTXTINS, IMG, VARS) uses the data in VARS for variable
%   substitution, when the Text property contains ANSI C printf-style
%   format specifications (%d, %.2f, etc.). VARS is a scalar or a vector
%   having length equal to the number of format specifiers in each element
%   in the specified text string.
%
%   TXTIMG = step(HTXTINS, IMG, COLOR) uses a scalar or 3-element
%   vector, COLOR, for the text color. This option is available when the 
%   ColorSource property is 'Input port'.
%
%   TXTIMG = step(HTXTINS, IMG, LOC) places the text at the [x y] 
%   coordinates specified by LOC, when the LocationSource property is 
%   'Input port'.
%
%   TXTIMG = step(HTXTINS, IMG, OPAC) uses OPAC for the text opacity when
%   the OpacitySource property is set to 'Input port'.
%
%   The above operations can be used simultaneously, provided the object
%   properties are set appropriately. For example,
%       TXTIMG = step(HTXTINS, IMG, CELLIDX, VARS, COLOR, LOC, OPAC) 
%   draws the specified text onto image IMG using text selected by 
%   index CELLIDX, text variable substitution data VARS, color value COLOR
%   at location LOC with opacity OPAC.
%
%   TextInserter methods:
%
%   step     - See above description for use of this method
%   release  - Allow property value and input characteristics changes
%   clone    - Create text inserter object with same property values
%   isLocked - Locked status (logical)
%
%   TextInserter properties:
%
%   Text            - Text string to draw on image or video stream
%   ColorSource     - Source of intensity or color of text
%   Color           - Intensity or color of text
%   LocationSource  - Source of text location
%   Location        - Top-left corner of text bounding box
%   OpacitySource   - Source of opacity of text
%   Opacity         - Opacity of text
%   TransposedInput - Specifies if input image data order is row major
%   Font            - Font face of text
%   FontSize        - Font size in points
%   Antialiasing    - Perform smoothing algorithm on text edges
%
%   % EXAMPLE:  Draw a basic text string on a static image.
%      I = imread('peppers.png');
%      htxtins = vision.TextInserter('Peppers are good for you!');
%      % maximum for uint8 image I is 255 which results in brightest color
%      htxtins.Color = [255, 255, 255]; % [red, green, blue]
%      htxtins.FontSize = 24;
%      htxtins.Location = [100 315]; % [x y]
%      J = step(htxtins, I);
%      imshow(J);
%
%   See also vision.AlphaBlender, vision.MarkerInserter, vision.ShapeInserter.

 
%   Copyright 2004-2010 The MathWorks, Inc.

    methods
        function out=TextInserter
            %TextInserter Draw text on image or video stream
            %   HTXTINS = vision.TextInserter returns a System object, HTXTINS, that
            %   draws formatted text onto an image or video stream.
            %
            %   HTXTINS = vision.TextInserter('PropertyName', PropertyValue, ...)
            %   returns a text inserter object, HTXTINS, with each specified property
            %   set to the specified value.
            %
            %   HTXTINS = vision.TextInserter(TEXT, 'PropertyName', PropertyValue, ...)
            %   returns a text inserter object, HTXTINS, with the Text property set to
            %   TEXT and other specified properties set to the specified values.
            %
            %   Step method syntax:
            %
            %   TXTIMG = step(HTXTINS, IMG) draws the specified text onto input image
            %   IMG and returns the modified image TXTIMG. The image IMG can either be
            %   an 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.
            %
            %   TXTIMG = step(HTXTINS, IMG, CELLIDX) draws the text string selected
            %   by index, CELLIDX, when the Text property is a cell array of strings.
            %   For example, when Text property is {'str1','str2'}, and CELLIDX = 1, 
            %   'str1' will be drawn in the image. Values of CELLIDX, outside of valid
            %   range result in no text drawn in the image.
            %
            %   TXTIMG = step(HTXTINS, IMG, VARS) uses the data in VARS for variable
            %   substitution, when the Text property contains ANSI C printf-style
            %   format specifications (%d, %.2f, etc.). VARS is a scalar or a vector
            %   having length equal to the number of format specifiers in each element
            %   in the specified text string.
            %
            %   TXTIMG = step(HTXTINS, IMG, COLOR) uses a scalar or 3-element
            %   vector, COLOR, for the text color. This option is available when the 
            %   ColorSource property is 'Input port'.
            %
            %   TXTIMG = step(HTXTINS, IMG, LOC) places the text at the [x y] 
            %   coordinates specified by LOC, when the LocationSource property is 
            %   'Input port'.
            %
            %   TXTIMG = step(HTXTINS, IMG, OPAC) uses OPAC for the text opacity when
            %   the OpacitySource property is set to 'Input port'.
            %
            %   The above operations can be used simultaneously, provided the object
            %   properties are set appropriately. For example,
            %       TXTIMG = step(HTXTINS, IMG, CELLIDX, VARS, COLOR, LOC, OPAC) 
            %   draws the specified text onto image IMG using text selected by 
            %   index CELLIDX, text variable substitution data VARS, color value COLOR
            %   at location LOC with opacity OPAC.
            %
            %   TextInserter methods:
            %
            %   step     - See above description for use of this method
            %   release  - Allow property value and input characteristics changes
            %   clone    - Create text inserter object with same property values
            %   isLocked - Locked status (logical)
            %
            %   TextInserter properties:
            %
            %   Text            - Text string to draw on image or video stream
            %   ColorSource     - Source of intensity or color of text
            %   Color           - Intensity or color of text
            %   LocationSource  - Source of text location
            %   Location        - Top-left corner of text bounding box
            %   OpacitySource   - Source of opacity of text
            %   Opacity         - Opacity of text
            %   TransposedInput - Specifies if input image data order is row major
            %   Font            - Font face of text
            %   FontSize        - Font size in points
            %   Antialiasing    - Perform smoothing algorithm on text edges
            %
            %   % EXAMPLE:  Draw a basic text string on a static image.
            %      I = imread('peppers.png');
            %      htxtins = vision.TextInserter('Peppers are good for you!');
            %      % maximum for uint8 image I is 255 which results in brightest color
            %      htxtins.Color = [255, 255, 255]; % [red, green, blue]
            %      htxtins.FontSize = 24;
            %      htxtins.Location = [100 315]; % [x y]
            %      J = step(htxtins, I);
            %      imshow(J);
            %
            %   See also vision.AlphaBlender, vision.MarkerInserter, vision.ShapeInserter.
        end

        function isInactivePropertyImpl(in) %#ok<MANU>
        end

        function setPortDataTypeConnections(in) %#ok<MANU>
        end

    end
    methods (Abstract)
    end
    properties
        %Antialiasing Perform smoothing algorithm on text edges
        %   Set this property to true to smooth the edges of the text. The
        %   default value of this property is true.
        Antialiasing;

        %Color Intensity or color of text
        %   Specify the intensity or color of the text as a scalar integer value
        %   or a 3-element vector respectively. Alternatively, if the Text
        %   property is a cell array of strings, specify an M-by-1 vector of 
        %   intensity values or M-by-3 matrix of color values that correspond 
        %   to each of M strings. The default value of this property is 
        %   [0 0 0]. The color values must be selected appropriately for the 
        %   given input data range. This property is applicable when the 
        %   ColorSource property is 'Property'. This property is tunable.
        Color;

        %ColorSource Source of intensity or color of text
        %   Select how to specify the intensity or color value of the text as one
        %   of [{'Property'} | 'Input port'].
        ColorSource;

        %Font Font face of text
        %   Specify the font of the text as one of the available fonts installed
        %   on the system.
        Font;

        %FontSize Font size in points
        %   Specify the font size as any positive integer value. The default
        %   value of this property is 12.
        FontSize;

        %Location Top-left corner of text bounding box
        %   Specify the top-left corner of the text bounding box as a 2-element
        %   vector of integers, [x y]. The default value of this property
        %   is [1 1]. This property is applicable when the LocationSource
        %   property is 'Property'. This property is tunable.
        Location;

        %LocationSource Source of text location
        %   Select how to specify the location of the text as one of
        %   [{'Property'} | 'Input port'].
        LocationSource;

        %Opacity Opacity of text
        %   Specify the opacity of the text as numeric scalar between 0 and 1.
        %   The default value of this property is 1. This property is applicable
        %   when the OpacitySource property is 'Property'. This property is
        %   tunable.
        Opacity;

        %OpacitySource Source of opacity of text
        %   Select how to specify the opacity of the text as one of [{'Property'}
        %   | 'Input port'].
        OpacitySource;

        %Text Text string to draw on image or video stream
        %   Specify the text string to be drawn on image or video stream as a
        %   single text string or a cell array of strings. The string(s) can
        %   include ANSI C printf-style format specifications, such as %d, %f, or
        %   %s.
        Text;

        %TransposedInput Specifies if input image data order is row major
        %   Set this property to true to indicate that the input image data order
        %   is row major. The default value of this property is false.
        TransposedInput;

    end
end
