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":

FormFieldTemplate - a base class for each "form field template"
- OmrFieldTemplate - a template for a "form field", which defines an abstract optical mark
  - OmrEllipticalFieldTemplate - a template for a "form field", which defines an optical mark bounded by ellipse
  - OmrRectangularFieldTemplate - a template for a "form field", which defines an optical mark bounded by rectangle
  - OmrFieldTemplateTable - a template that defines a table, which table cells are optical mark fields
- OcrFieldTemplate - a template for a "form field", which contains typed text or handwritten digits
- FormFieldTemplateGroup - a template for a group of "form fields"
  - FormFieldTemplateTable - a template for a table of "form fields"

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:

Scan an image with blank form.
Create a manager of "form templates" - an instance of FormTemplateManager class.
Add the scanned image into a manager of form templates.
Determine a list of "form field templates" visually or programmatically.

Here is C#/VB.NET code, that demonstrates how to scan a document with blank form and create a form template.

/// <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.GetAsVintasoftBitmap(), 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;
    }
}

VB.NET

''' <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.GetAsVintasoftBitmap(), 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

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:

Create a "form field template"
Add the "form field template" to a "form template"

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

Find the "form field template" that should be edited
Edit the "form field template"

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

Find the "form field template" that should be edited
Remove the "form field template"

Here is C#/VB.NET code, that demonstrates how to create a form template and add some form field templates to it programmatically.

/// <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;
}

VB.NET

''' <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

Edit a form template on image in WinForms image viewer

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

Load an image with blank form into an image viewer
Create FormFieldTemplateEditorTool visual tool and select it as active tool in image viewer
Add "form field templates" of the "form template" into the FormFieldTemplateEditorTool visual tool
Add, edit or remove "form field templates" onto the image with blank form in the image viewer via mouse

Here is C#/VB.NET code, which demonstrates how to create a form template on image in WinForms image viewer and add some field templates to the form.

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>
    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>
    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);
    }

    // ...

}

VB.NET

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>
    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>
    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

Edit a form template on image in WPF image viewer

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

Load an image with blank form into WPF image viewer
Create WpfFormFieldTemplateEditorTool visual tool and select it as active tool in image viewer
Add "form field templates" of the "form template" into the WpfFormFieldTemplateEditorTool visual tool
Add, edit or remove "form field templates" onto the image with blank form in the image viewer via mouse

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 C#/VB.NET code, that demonstrates how to save a form template to a file and load the form template from the file.

/// <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;
}

VB.NET

''' <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

Send Feedback