VintaSoft Imaging .NET SDK 15.1: Documentation for .NET developer
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. The "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 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;
    }
}

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


Determine the templates of OMR marks in demo application "VintaSoft Forms Processing Demo"

Demo application "VintaSoft Forms Processing Demo" allows to detect seperate OMR marks or table of OMR marks automatically.

If you want automatically detect a rectangular/elliptical OMR mark on template image, please do the following steps: If you want automatically detect a table with rectangular/elliptical OMR marks on template image, please do the following steps:
Also demo application "VintaSoft Forms Processing Demo" allows to manually determine seperate OMR marks or table of OMR marks.

If you want manually determine a template of rectangular/elliptical OMR mark on template image, please do the following steps: If you want manually determine a table with rectangular/elliptical OMR marks on template image, please do the following steps:

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

''' <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:
Here is C#/VB.NET code that 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()
    {
        // ...

        // create the form field template editor tool
        _templateEditorTool =
            new Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.VisualTools.FormFieldTemplateEditorTool();
        // add the form field template editor tool to the image viewer
        imageViewer1.VisualTool =
            new Vintasoft.Imaging.UI.VisualTools.CompositeVisualTool(_templateEditorTool, _templateEditorTool.FieldTemplateWizardTool);

        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 image viewer does not have image
        if (imageViewer1.Image == null)
        {
            // clear form field template collection in the form field template editor tool
            _templateEditorTool.FieldTemplateCollection = null;
        }
        // if image viewer haS image
        else
        {
            // get the form page template for focused image
            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);
    }

    // ...

}

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

        ' create the form field template editor tool
        _templateEditorTool = New Vintasoft.Imaging.FormsProcessing.FormRecognition.UI.VisualTools.FormFieldTemplateEditorTool()
        ' add the form field template editor tool to the image viewer
        imageViewer1.VisualTool = New Vintasoft.Imaging.UI.VisualTools.CompositeVisualTool(_templateEditorTool, _templateEditorTool.FieldTemplateWizardTool)

        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 image viewer does not have image
        If imageViewer1.Image Is Nothing Then
            ' clear form field template collection in the form field template editor tool
            _templateEditorTool.FieldTemplateCollection = Nothing
        Else
            ' if image viewer haS image
            ' get the form page template for focused image
            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:

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

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


 

 

Copyright 2007-2026 VintaSoft LLC. All Rights Reserved.

Send Feedback