VintaSoft Imaging .NET SDK v8.8 for .NET Framework
In This Topic
    Forms processing: Form template
    In This Topic

    A form template is represented by two objects: an instance of VintasoftImage class, which defines an image of form template, and an instance of FormPageTemplate class, which defines a list of form field templates.

    FormTemplateManager class is a manager of form templates and it is used for simplifying the work with form templates. The class stores the link between the instance of VintasoftImage class and the instance of FormPageTemplate class for each form template.

    Form field template is represented by FormFieldTemplate class, which defines the field name, its type and location on page. Here is a list of standard classes defining form field templates:



    Architecture of the FormFieldTemplate class is open, so it is possible to define own custom form fields if necessary. Forms Processing Demo application contains an example of form field template that defines a barcode.

    FormDocumentTemplate class allows to unite one or more form templates into a form templates document. This allows to work with several form fields as with one object and thus to simplify serialization and deserialization of form templates.


    Create a form template

    To create a form template is necessary to do the following steps:

    Here is an example, that demonstrates how to scan a document with blank form and create a form template.
    ' The project, which uses this code, must have references to the following assemblies:
    ' - Vintasoft.Imaging
    ' - Vintasoft.Imaging.FormsProcessing
    
    ''' <summary>
    ''' Scans the template document and creates page templates.
    ''' </summary>
    ''' <returns>
    ''' A <see cref="Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager"/> instance that contains
    ''' images of template document and the templates of document pages.
    ''' </returns>
    Public Shared Function ScanAndCreatePageTemplates() As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager
        Dim templateManager As New Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager()
    
        System.Console.WriteLine("Create TWAIN device manager...")
        Using deviceManager As New Vintasoft.Twain.DeviceManager()
            System.Console.WriteLine("Open TWAIN device manager...")
            deviceManager.Open()
    
            Dim device As Vintasoft.Twain.Device = deviceManager.DefaultDevice
    
            Dim acquireState As Vintasoft.Twain.AcquireModalState
            Do
                System.Console.WriteLine("Acquire image from scanner...")
                acquireState = device.AcquireModal()
                If acquireState = Vintasoft.Twain.AcquireModalState.ImageAcquired Then
                    ' create VintasoftImage from acquired image
                    Dim image As New Vintasoft.Imaging.VintasoftImage(device.AcquiredImage.GetAsBitmap(), True)
                    ' if image is not black-white
                    If image.PixelFormat <> Vintasoft.Imaging.PixelFormat.BlackWhite Then
                        ' convert to black-white image (1-bpp pixel format)
                        image.ConvertToBlackWhite()
                    End If
    
                    ' add page to PDF document
                    System.Console.WriteLine("Add page to template manager...")
                    templateManager.AddPageTemplate(image, New Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate())
    
                    ' dispose the acquired image
                    device.AcquiredImage.Dispose()
                End If
            Loop While acquireState <> Vintasoft.Twain.AcquireModalState.None
    
            System.Console.WriteLine("Scan finished.")
            Return templateManager
        End Using
    End Function
                  
    
    // The project, which uses this code, must have references to the following assemblies:
    // - Vintasoft.Imaging
    // - Vintasoft.Imaging.FormsProcessing
    
    /// <summary>
    /// Scans the template document and creates page templates.
    /// </summary>
    /// <returns>
    /// A <see cref="Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager"/> instance that contains
    /// images of template document and the templates of document pages.
    /// </returns>
    public static Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager ScanAndCreatePageTemplates()
    {
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager templateManager = 
            new Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager();
    
        System.Console.WriteLine("Create TWAIN device manager...");
        using (Vintasoft.Twain.DeviceManager deviceManager = 
            new Vintasoft.Twain.DeviceManager())
        {
            System.Console.WriteLine("Open TWAIN device manager...");
            deviceManager.Open();
    
            Vintasoft.Twain.Device device = deviceManager.DefaultDevice;
    
            Vintasoft.Twain.AcquireModalState acquireState;
            do
            {
                System.Console.WriteLine("Acquire image from scanner...");
                acquireState = device.AcquireModal();
                if (acquireState == Vintasoft.Twain.AcquireModalState.ImageAcquired)
                {
                    // create VintasoftImage from acquired image
                    Vintasoft.Imaging.VintasoftImage image = 
                        new Vintasoft.Imaging.VintasoftImage(device.AcquiredImage.GetAsBitmap(), true);
                    // if image is not black-white
                    if (image.PixelFormat != Vintasoft.Imaging.PixelFormat.BlackWhite)
                        // convert to black-white image (1-bpp pixel format)
                        image.ConvertToBlackWhite();
    
                    // add page to PDF document
                    System.Console.WriteLine("Add page to template manager...");
                    templateManager.AddPageTemplate(image, 
                        new Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate());
    
                    // dispose the acquired image
                    device.AcquiredImage.Dispose();
                }
            }
            while (acquireState != Vintasoft.Twain.AcquireModalState.None);
    
            System.Console.WriteLine("Scan finished.");
            return templateManager;
        }
    }
                    
    


    Edit a form template

    A form template can be edited visually or programmatically. The FormFieldTemplateEditorTool class can be used for visual editing of form template.

    To add the form field template to a form template programmatically is necessary to do the following:

    To edit a form field template in a form template programmatically is necessary to do the following:

    To remove a form field template from a form template programmatically is necessary to do the following:

    Here is an example, that demonstrates how to create a form template and add some form field templates to it programmatically.
    ' The project, which uses this code, must have references to the following assemblies:
    ' - Vintasoft.Imaging.FormsProcessing
    ' - Vintasoft.Imaging.FormsProcessing.Ocr
    ' - Vintasoft.Imaging.Ocr
    
    ''' <summary>
    ''' Creates a page template and adds field templates.
    ''' </summary>
    ''' <returns>
    ''' A <see cref="Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate"/> instance that contains
    ''' created form field templates.
    ''' </returns>
    Public Shared Function CreatePageTemplateAndAddFieldTemplates() As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate
        ' create empty page template
        Dim pageTemplate As New Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate()
    
        ' create OMR field
        Dim omrFieldTemplate As Vintasoft.Imaging.FormsProcessing.FormRecognition.Omr.OmrFieldTemplate = New Vintasoft.Imaging.FormsProcessing.FormRecognition.Omr.OmrRectangularFieldTemplate()
        omrFieldTemplate.Name = "'I agree' check box"
        omrFieldTemplate.BoundingBox = New System.Drawing.RectangleF(1200, 2400, 40, 40)
        omrFieldTemplate.Threshold = 0.1F
        omrFieldTemplate.FilledValue = "YES"
        omrFieldTemplate.UnfilledValue = ""
        omrFieldTemplate.UndefinedValue = "?"
    
        ' add field template to page template
        pageTemplate.Items.Add(omrFieldTemplate)
    
        ' create OCR field
        Dim ocrFieldTemplate As New Vintasoft.Imaging.FormsProcessing.FormRecognition.Ocr.OcrFieldTemplate()
        ocrFieldTemplate.Name = "Last name"
        ocrFieldTemplate.BoundingBox = New System.Drawing.RectangleF(300, 400, 500, 200)
        ocrFieldTemplate.OcrEngineSettings = New Vintasoft.Imaging.Ocr.OcrEngineSettings(Vintasoft.Imaging.Ocr.OcrLanguage.English)
    
        ' add field template to page template
        pageTemplate.Items.Add(ocrFieldTemplate)
    
        Return pageTemplate
    End Function
                  
    
    // The project, which uses this code, must have references to the following assemblies:
    // - Vintasoft.Imaging.FormsProcessing
    // - Vintasoft.Imaging.FormsProcessing.Ocr
    // - Vintasoft.Imaging.Ocr
    
    /// <summary>
    /// Creates a page template and adds field templates.
    /// </summary>
    /// <returns>
    /// A <see cref="Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate"/> instance that contains
    /// created form field templates.
    /// </returns>
    public static Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate CreatePageTemplateAndAddFieldTemplates()
    {
        // create empty page template
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate pageTemplate = 
            new Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate();
    
        // create OMR field
        Vintasoft.Imaging.FormsProcessing.FormRecognition.Omr.OmrFieldTemplate omrFieldTemplate = 
            new Vintasoft.Imaging.FormsProcessing.FormRecognition.Omr.OmrRectangularFieldTemplate();
        omrFieldTemplate.Name = "'I agree' check box";
        omrFieldTemplate.BoundingBox = new System.Drawing.RectangleF(1200, 2400, 40, 40);
        omrFieldTemplate.Threshold = 0.1f;
        omrFieldTemplate.FilledValue = "YES";
        omrFieldTemplate.UnfilledValue = "";
        omrFieldTemplate.UndefinedValue = "?";
    
        // add field template to page template
        pageTemplate.Items.Add(omrFieldTemplate);
    
        // create OCR field
        Vintasoft.Imaging.FormsProcessing.FormRecognition.Ocr.OcrFieldTemplate ocrFieldTemplate = 
            new Vintasoft.Imaging.FormsProcessing.FormRecognition.Ocr.OcrFieldTemplate();
        ocrFieldTemplate.Name = "Last name";
        ocrFieldTemplate.BoundingBox = new System.Drawing.RectangleF(300, 400, 500, 200);
        ocrFieldTemplate.OcrEngineSettings = 
            new Vintasoft.Imaging.Ocr.OcrEngineSettings(Vintasoft.Imaging.Ocr.OcrLanguage.English);
    
        // add field template to page template
        pageTemplate.Items.Add(ocrFieldTemplate);
    
        return pageTemplate;
    }
                    
    


    Edit a form template on image in WinForms image viewer

    To create and edit a form template visually is necessary to do the following:

    Here is an example, which demonstrates how to create a form template on image in WinForms image viewer and add some field templates to the form.
    ' The project, which uses this code, must have references to the following assemblies:
    ' - Vintasoft.Imaging
    ' - Vintasoft.Imaging.FormsProcessing
    
    Class FormFieldTemplateEditorToolForm
        Inherits System.Windows.Forms.Form
        Private imageViewer1 As Vintasoft.Imaging.UI.ImageViewer
        Private buildFieldTemplateButton As System.Windows.Forms.Button
    
        ' ...
    
        ''' <summary>
        ''' Form template manager.
        ''' </summary>
        Private _templateManager As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager
    
        ''' <summary>
        ''' The template editor tool.
        ''' </summary>
        Private _templateEditorTool As Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.VisualTools.FormFieldTemplateEditorTool
    
        ' ...
    
        Public Sub New()
            ' ...
    
            _templateEditorTool = New Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.VisualTools.FormFieldTemplateEditorTool()
            imageViewer1.VisualTool = _templateEditorTool
    
            AddHandler imageViewer1.FocusedIndexChanged, New System.EventHandler(Of Vintasoft.Imaging.UI.FocusedIndexChangedEventArgs)(AddressOf imageViewer1_FocusedIndexChanged)
    
    
                ' ...
            AddHandler buildFieldTemplateButton.Click, New System.EventHandler(AddressOf buildFieldTemplateButton_Click)
        End Sub
    
        ''' <summary>
        ''' Handles the FocusedIndexChanged event of the imageViewer1
        ''' to change the collection of form field templates of the visual tool.
        ''' </summary>
        ''' <param name="sender">The source of the event.</param>
        ''' <param name="e">The <see cref="Vintasoft.Imaging.UI.FocusedIndexChangedEventArgs"/> instance
        ''' containing the event data.</param>
        Private Sub imageViewer1_FocusedIndexChanged(sender As Object, e As Vintasoft.Imaging.UI.FocusedIndexChangedEventArgs)
            If imageViewer1.Image Is Nothing Then
                _templateEditorTool.FieldTemplateCollection = Nothing
            Else
                ' get the form page template
                Dim pageTemplate As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate = _templateManager.GetPageTemplate(imageViewer1.Image)
                ' set items of page template as current items of the visual tool
                _templateEditorTool.FieldTemplateCollection = pageTemplate.Items
            End If
        End Sub
    
        ' ...
    
        ''' <summary>
        ''' Handles the Click event of the buildFieldTemplateButton
        ''' to create a form field template and start building of it.
        ''' </summary>
        ''' <param name="sender">The source of the event.</param>
        ''' <param name="e">The <see cref="System.EventArgs"/> instance containing the event data.</param>
        Private Sub buildFieldTemplateButton_Click(sender As Object, e As System.EventArgs)
            ' create an OMR rectangular field template
            Dim fieldTemplate As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormFieldTemplate = New Vintasoft.Imaging.FormsProcessing.FormRecognition.Omr.OmrRectangularFieldTemplate()
            ' create a view for the field template
            Dim fieldTemplateView As Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.FormFieldTemplateView = Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.FormFieldTemplateViewFactory.CreateView(fieldTemplate)
    
            ' add field template to the collection of visual tool and
            ' start building of field template
            _templateEditorTool.AddAndBuild(fieldTemplateView)
        End Sub
    
        ' ...
    
    End Class
                  
    
    // The project, which uses this code, must have references to the following assemblies:
    // - Vintasoft.Imaging
    // - Vintasoft.Imaging.FormsProcessing
    
    class FormFieldTemplateEditorToolForm : System.Windows.Forms.Form
    {
        Vintasoft.Imaging.UI.ImageViewer imageViewer1;
        System.Windows.Forms.Button buildFieldTemplateButton;
    
        // ...
    
        /// <summary>
        /// Form template manager.
        /// </summary>
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager _templateManager;
    
        /// <summary>
        /// The template editor tool.
        /// </summary>
        Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.VisualTools.FormFieldTemplateEditorTool _templateEditorTool;
    
        // ...
    
        public FormFieldTemplateEditorToolForm()
        {
            // ...
    
            _templateEditorTool = new Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.VisualTools.FormFieldTemplateEditorTool();
            imageViewer1.VisualTool = _templateEditorTool;
    
            imageViewer1.FocusedIndexChanged += 
                new System.EventHandler<Vintasoft.Imaging.UI.FocusedIndexChangedEventArgs>(imageViewer1_FocusedIndexChanged);
    
            buildFieldTemplateButton.Click += 
                new System.EventHandler(buildFieldTemplateButton_Click);
    
            // ...
        }
    
        /// <summary>
        /// Handles the FocusedIndexChanged event of the imageViewer1
        /// to change the collection of form field templates of the visual tool.
        /// </summary>
        /// <param name="sender">The source of the event.</param>
        /// <param name="e">The <see cref="Vintasoft.Imaging.UI.FocusedIndexChangedEventArgs"/> instance
        /// containing the event data.</param>
        private void imageViewer1_FocusedIndexChanged(object sender, Vintasoft.Imaging.UI.FocusedIndexChangedEventArgs e)
        {
            if (imageViewer1.Image == null)
            {
                _templateEditorTool.FieldTemplateCollection = null;
            }
            else
            {
                // get the form page template
                Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate pageTemplate = 
                    _templateManager.GetPageTemplate(imageViewer1.Image);
                // set items of page template as current items of the visual tool
                _templateEditorTool.FieldTemplateCollection = pageTemplate.Items;
            }
        }
    
        // ...
    
        /// <summary>
        /// Handles the Click event of the buildFieldTemplateButton
        /// to create a form field template and start building of it.
        /// </summary>
        /// <param name="sender">The source of the event.</param>
        /// <param name="e">The <see cref="System.EventArgs"/> instance containing the event data.</param>
        private void buildFieldTemplateButton_Click(object sender, System.EventArgs e)
        {
            // create an OMR rectangular field template
            Vintasoft.Imaging.FormsProcessing.FormRecognition.FormFieldTemplate fieldTemplate = 
                new Vintasoft.Imaging.FormsProcessing.FormRecognition.Omr.OmrRectangularFieldTemplate();
            // create a view for the field template
            Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.FormFieldTemplateView fieldTemplateView = 
                Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.FormFieldTemplateViewFactory.CreateView(fieldTemplate);
    
            // add field template to the collection of visual tool and
            // start building of field template
            _templateEditorTool.AddAndBuild(fieldTemplateView);
        }
    
        // ...
    
    }
                    
    


    Edit a form template on image in WPF image viewer

    To create and edit a form template visually is necessary to do the following:


    Define a template of form field

    The FormFieldTemplate.Name property allows to specify the name of form field template.

    The FormFieldTemplate.BoundingBox property allows to specify the area on image, of form template, where the data of form field template is located.

    By default, the image area, which contains the data of form field template, is considered empty, i.e. the image area contains the white pixels only. In case when the image area, which contains the data of form field template, is not empty (image area contains black and white pixels), is necessary to call FormFieldTemplate.CompensateTemplateImageBackground method in order to ignore black pixels during the recognition of form field.


    Save and load a form template

    The SDK allows to save a form template to a file or stream, as well as load a form template from a file or stream.

    To save a form template document is necessary to use FormDocumentTemplate.Serialize method, to load a form template document is necessary to use FormDocumentTemplate.Deserialize method. To save a form template is necessary to use FormPageTemplate.Serialize method, to load a form template is necessary to use FormPageTemplate.Deserialize method.
    The form data are stored in a format based on XML format.

    Here is an example, that demonstrates how to save a form template to a file and load the form template from the file.
    ' The project, which uses this code, must have references to the following assemblies:
    ' - Vintasoft.Imaging.FormsProcessing
    
    ''' <summary>
    ''' Saves the page templates as a document template to the specified stream.
    ''' </summary>
    ''' <param name="pageTemplates">The page templates.</param>
    ''' <param name="stream">The stream to save the document to.</param>
    ''' <remarks>
    ''' Use the <see cref="Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager"/>
    ''' class to preserve links to template images.
    ''' </remarks>
    Public Sub SavePageTemplatesAsDocumentTemplate(pageTemplates As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate(), stream As System.IO.Stream)
        ' create new template document
        Dim documentTemplate As New Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate()
        ' set arbitrary name
        documentTemplate.Name = "Combined document template"
        ' for each template page
        For Each pageTemplate As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate In pageTemplates
            ' add to the document
            documentTemplate.Pages.Add(pageTemplate)
        Next
        ' save the document to the stream
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate.Serialize(stream, documentTemplate)
    End Sub
    
    ''' <summary>
    ''' Opens the document template and saves every page to a separate file.
    ''' </summary>
    ''' <param name="filename">The path to the file that contains the document template.</param>
    ''' <returns><b>true</b> if the document template contains pages; otherwise, <b>false</b>.</returns>
    Public Shared Function OpenDocumentTemplateAndSaveEveryPage(filename As String) As Boolean
        ' deserialize the document template
        Dim documentTemplate As Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate = Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate.Deserialize(filename)
    
        If documentTemplate.Pages.Count = 0 Then
            Return False
        End If
        ' for each page of the document template
        For i As Integer = 0 To documentTemplate.Pages.Count - 1
            ' compose a filename
            Dim pageFilename As String = String.Format("{0}{1}_page{2}{3}", System.IO.Path.GetDirectoryName(filename), System.IO.Path.GetFileNameWithoutExtension(filename), i + 1, System.IO.Path.GetExtension(filename))
            ' save page template to a file
            Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate.Serialize(pageFilename, documentTemplate.Pages(i))
        Next
    
        Return True
    End Function
                  
    
    // The project, which uses this code, must have references to the following assemblies:
    // - Vintasoft.Imaging.FormsProcessing
    
    /// <summary>
    /// Saves the page templates as a document template to the specified stream.
    /// </summary>
    /// <param name="pageTemplates">The page templates.</param>
    /// <param name="stream">The stream to save the document to.</param>
    /// <remarks>
    /// Use the <see cref="Vintasoft.Imaging.FormsProcessing.FormRecognition.FormTemplateManager"/>
    /// class to preserve links to template images.
    /// </remarks>
    public void SavePageTemplatesAsDocumentTemplate(
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate[] pageTemplates, 
        System.IO.Stream stream)
    {
        // create new template document
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate documentTemplate = 
            new Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate();
        // set arbitrary name
        documentTemplate.Name = "Combined document template";
        // for each template page
        foreach (Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate pageTemplate in pageTemplates)
        {
            // add to the document
            documentTemplate.Pages.Add(pageTemplate);
        }
        // save the document to the stream
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate.Serialize(stream, documentTemplate);
    }
    
    /// <summary>
    /// Opens the document template and saves every page to a separate file.
    /// </summary>
    /// <param name="filename">The path to the file that contains the document template.</param>
    /// <returns><b>true</b> if the document template contains pages; otherwise, <b>false</b>.</returns>
    public static bool OpenDocumentTemplateAndSaveEveryPage(string filename)
    {
        // deserialize the document template
        Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate documentTemplate = 
            Vintasoft.Imaging.FormsProcessing.FormRecognition.FormDocumentTemplate.Deserialize(filename);
    
        if (documentTemplate.Pages.Count == 0)
            return false;
        // for each page of the document template
        for (int i = 0; i < documentTemplate.Pages.Count; i++)
        {
            // compose a filename
            string pageFilename = string.Format(
                "{0}{1}_page{2}{3}",
                System.IO.Path.GetDirectoryName(filename),
                System.IO.Path.GetFileNameWithoutExtension(filename),
                i + 1,
                System.IO.Path.GetExtension(filename));
            // save page template to a file
            Vintasoft.Imaging.FormsProcessing.FormRecognition.FormPageTemplate.Serialize(pageFilename, documentTemplate.Pages[i]);
        }
    
        return true;
    }