CogOCRMaxTool Tune Method Cognex VisionPro 9.5
Tunes the OCRMax Tool based on the collection of Tune Records contained in the TuneData property and the current tool parameters.

Tuning searches for OCRMax parameters that produce line results that match the tune records in TuneData (which are known to be correct).

Namespace: Cognex.VisionPro.OCRMax
Assembly: Cognex.VisionPro.OCRMax (in Cognex.VisionPro.OCRMax.dll) Version: 69.0.0.0
Syntax
Copy to ClipboardPrint
public void Tune()
Exceptions
ExceptionCondition
InvalidOperationException
  • Thrown if TuneParams is null.
  • Thrown if TuneData is null.
  • Thrown if Segmenter is null.
  • Thrown if ClassifierRunParams is null.
  • Thrown if Classifier.TrainParams is null.
CogOCRMaxInvalidTuneRecordException
  • Thrown if any tune record has an unallocated image
  • Thrown if any tune record contains no character codes
  • Thrown if any tune record has a character code which is the unknown character marker
  • Thrown if any tune records has a mark rect which has an angle or skew greater than 45 degrees relative to the region
  • Thrown if (number of mark rects != number of cell rects != number of character codes) for any tune record
Remarks

Correct tune records are added to the TuneData by calling AutoTune() on the OCRMax tool, or by calling AddTuneRecord() directly on the OCRMaxTool's TuneData property.

A "correct" record contains the image, region, and correct string of character codes, and the mark and cell rects which correctly identify the location of each character in the image.

Examples
Copy to ClipboardPrint
' Create a new CogOCRMaxTool to demonstrate OCRMax tuning.
Dim myOCRMaxTool As New CogOCRMaxTool()

' Load an image which contains the text "Date:10/01/2009"
Dim ifPath As String = System.Environment.GetEnvironmentVariable("VPRO_ROOT")  & _
                       "\images\OCRMax_dotmatrix_multiline.idb"

Dim imageFileTool As New CogImageFileTool()
imageFileTool.[Operator].Open(ifPath, CogImageFileModeConstants.Read)
imageFileTool.Run()
Dim image As CogImage8Grey = TryCast(imageFileTool.OutputImage, CogImage8Grey)
myOCRMaxTool.InputImage = image

' Set up the OCRMaxTool's Region so that it contains the text
' we wish to read.
Dim region As New CogRectangleAffine()
region.SetCenterLengthsRotationSkew(236.822, 65.6591, 433.645, 43.7727, 0, 0)
myOCRMaxTool.Region = region

' Run the OCRMaxTool on the image
myOCRMaxTool.Run()

' Note that the OCRMaxTool was unable to correctly read the string.

' Here we extract a tune record from the OCRMaxTool's line result.
Dim extractedRecord As CogOCRMaxTuneRecord = _
  myOCRMaxTool.LineResult.CreateTuneRecordFromResult(myOCRMaxTool.InputImage, _
                                                     myOCRMaxTool.Region)

' A collection of UTF-32 character codes is created which represents
' the string contained in the image.
Dim characterCodes As New CogOCRMaxCharKeyCollection("Date:10/01/2009", "?")

' Here we update the extracted tune records with the 
' character codes we expect the tool to read.
extractedRecord.CharacterCodes = characterCodes

' Now use the OCRMaxTool's Auto Correct feature to locate the 
' enclosing cell and mark rectangle of each character.
Dim autoCorrectResult As CogOCRMaxTuneRecordCollection = _
  myOCRMaxTool.AutoCorrect(extractedRecord)

' Here we assume the first autoCorrectResult is correct.
' In practice we would want to display the autoCorrectResults 
' and get confirmation before proceeding to the next step.
Dim correctedRecord As CogOCRMaxTuneRecord = autoCorrectResult(0)

' To display the record call:
' CogGraphicCollection myGraphics = correctRecord.CreateTuneRecordGraphics("?");
' myCogDisplay.Image = correctRecord.Image;
' myCogDisplay.StaticGraphics.AddList(myGraphics, "tuneRecordGraphics");

' Note that if none of the autoCorrectResult records are actually correct, we
' must choose one of the records and manually modify it so that it is correct.
' The process to manually modify a record is more complex and is beyond the 
' scope of this sample.

' Note that if you do manually correct an autoCorrectResult record before
' passing it to AutoTune you must also set the SegmenterCorrected and
' ClassifierCorrected properties of the record to indicate that it was
' manually corrected.

' Once we have a correct record, the OCRMaxTool can be tuned.
' Tuning the OCRMaxTool updates the Segmenter and Classifier.Font
' properties of the OCRMaxTool such that the new settings can 
' successfully read the tune record image (and future images
' which are similar).
myOCRMaxTool.AutoTune(correctedRecord)

' All tuned records are stored in the OCRMaxTool's TuneData property.
' Copies of the tuned records can be accessed like this:      
'   CogOCRMaxTuneRecordCollection tunedRecords = 
'     myOCRMaxTool.TuneData.GetTuneRecords();

' Tune Records can be removed from the OCRMaxTool's TuneData like this:     
'   myOCRMaxTool.TuneData.RemoveTuneRecord(0); 

' After the OCRMaxTool has been tuned it should be able to
' succesfully read the image.
myOCRMaxTool.Run()

' Check to see that the tool now reads the record correctly
Assert.IsTrue(myOCRMaxTool.LineResult.ResultString = "Date:10/01/2009")

' At this point the user would continue running the OCRMaxTool
' on new images until an image which could not be read is encountered.

' When this happens the steps, starting with extracting the tune record
' from the failing result, are repeated.
Copy to ClipboardPrint
// Create a new CogOCRMaxTool to demonstrate OCRMax tuning.
CogOCRMaxTool myOCRMaxTool = new CogOCRMaxTool();

// Load an image which contains the text "Date:10/01/2009" 
string ifPath = System.Environment.GetEnvironmentVariable("VPRO_ROOT") +
@"\images\OCRMax_dotmatrix_multiline.idb";

CogImageFileTool imageFileTool = new CogImageFileTool();
imageFileTool.Operator.Open(ifPath, CogImageFileModeConstants.Read);
imageFileTool.Run();
CogImage8Grey image = imageFileTool.OutputImage as CogImage8Grey;
myOCRMaxTool.InputImage = image;

// Set up the OCRMaxTool's Region so that it contains the text 
// we wish to read.
CogRectangleAffine region = new CogRectangleAffine();
region.SetCenterLengthsRotationSkew(236.822, 65.6591, 433.645, 43.7727, 0, 0);
myOCRMaxTool.Region = region;

// Run the OCRMaxTool on the image
myOCRMaxTool.Run();

// Note that the OCRMaxTool was unable to correctly read the string. 

// Here we extract a tune record from the OCRMaxTool's line result.
CogOCRMaxTuneRecord extractedRecord =
myOCRMaxTool.LineResult.CreateTuneRecordFromResult(myOCRMaxTool.InputImage,
myOCRMaxTool.Region);

// A collection of UTF-32 character codes is created which represents 
// the string contained in the image.
CogOCRMaxCharKeyCollection characterCodes =
new CogOCRMaxCharKeyCollection(@"Date:10/01/2009", "?");

// Here we update the extracted tune records with the 
// character codes we expect the tool to read.
extractedRecord.CharacterCodes = characterCodes;

// Now use the OCRMaxTool's Auto Correct feature to locate the 
// enclosing cell and mark rectangle of each character.
CogOCRMaxTuneRecordCollection autoCorrectResult =
myOCRMaxTool.AutoCorrect(extractedRecord);

// Here we assume the first autoCorrectResult is correct. 
// In practice we would want to display the autoCorrectResults 
// and get confirmation before proceeding to the next step.
CogOCRMaxTuneRecord correctedRecord = autoCorrectResult[0];

// To display the record call: 
// CogGraphicCollection myGraphics = correctRecord.CreateTuneRecordGraphics("?"); 
// myCogDisplay.Image = correctRecord.Image; 
// myCogDisplay.StaticGraphics.AddList(myGraphics, "tuneRecordGraphics"); 

// Note that if none of the autoCorrectResult records are actually correct, we 
// must choose one of the records and manually modify it so that it is correct. 
// The process to manually modify a record is more complex and is beyond the 
// scope of this sample. 

// Note that if you do manually correct an autoCorrectResult record before 
// passing it to AutoTune you must also set the SegmenterCorrected and 
// ClassifierCorrected properties of the record to indicate that it was 
// manually corrected. 

// Once we have a correct record, the OCRMaxTool can be tuned. 
// Tuning the OCRMaxTool updates the Segmenter and Classifier.Font 
// properties of the OCRMaxTool such that the new settings can 
// successfully read the tune record image (and future images 
// which are similar).
myOCRMaxTool.AutoTune(correctedRecord);

// All tuned records are stored in the OCRMaxTool's TuneData property. 
// Copies of the tuned records can be accessed like this: 
//   CogOCRMaxTuneRecordCollection tunedRecords = 
//     myOCRMaxTool.TuneData.GetTuneRecords(); 

// Tune Records can be removed from the OCRMaxTool's TuneData like this: 
//   myOCRMaxTool.TuneData.RemoveTuneRecord(0); 

// After the OCRMaxTool has been tuned it should be able to 
// succesfully read the image.
myOCRMaxTool.Run();

// Check to see that the tool now reads the record correctly
Assert.IsTrue(myOCRMaxTool.LineResult.ResultString == "Date:10/01/2009");

// At this point the user would continue running the OCRMaxTool 
// on new images until an image which could not be read is encountered. 

// When this happens the steps, starting with extracting the tune record 
// from the failing result, are repeated.
See Also
CogOCRMaxTool Class
Cognex.VisionPro.OCRMax Namespace