| MIL 10 Reference
| Customize Help
| Save Settings

MocrAllocFont


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
None.
Previous
MocrAllocResult
Synopsis
Allocate an OCR font context.
Syntax
MIL_ID MocrAllocFont(
MIL_ID SystemId, //in
MIL_INT64 FontType, //in
MIL_INT CharNumber, //in
MIL_INT CharCellSizeX, //in
MIL_INT CharCellSizeY, //in
MIL_INT CharOffsetX, //in
MIL_INT CharOffsetY, //in
MIL_INT CharSizeX, //in
MIL_INT CharSizeY, //in
MIL_INT CharThickness, //in
MIL_INT StringLength, //in
MIL_INT64 InitFlag, //in
MIL_ID *FontContextOcrIdPtr //out
)
Description

This function allocates an OCR font context on the specified system. An OCR font context contains the OCR font, target image information, and processing controls. When the OCR font context is no longer required, you should release its memory, using MocrFree().

If the OCR font context already exists as an OCR font file that matches your constraints and character sizes, such as SEMI_M12-92.mfo (SEMI M12-92) or SEMI_M13-88.mfo (SEMI M13-88), restore it using MocrRestoreFont(). If you need a modified version of a SEMI font (changing its character size, offset, thickness, or the number of characters in the OCR font context) or need a user-defined font, you should allocate a new OCR font context. Note that using either M_SEMI_M12_92 or M_SEMI_M13_88 automatically sets the OCR font context type to M_CONSTRAINED.

A newly allocated OCR font context must have its grayscale character representations initialized using MocrImportFont() or MocrCopyFont(). Each part of the OCR font context can be changed using MocrControl() and MocrModifyFont(). Constraints are set using MocrSetConstraint().

When allocating an OCR font context, you must specify an OCR font context type. This can be modified later using MocrControl() with M_CONTEXT_CONVERT. If your target image has a visible threshold difference between the target characters and the background, uniform illumination, and unknown spacing between characters, and unknown string lengths, and if your font is proportional, start by allocating an M_GENERAL OCR font context. If your target image contains noisy, scratched, or low contrast characters, or if the illumination is not uniform, or if your font includes broken characters start by allocating an M_CONSTRAINED OCR font context.

You must calibrate the OCR font context when the cell, offset, size, or thickness of the characters in your target image differs from the OCR font. Calibration can be either automatic (using MocrCalibrateFont()) or manual (using MocrControl()). Note, to use MocrCalibrateFont(), you must use an M_CONSTRAINED OCR font context.

If you change any controls or constraints, use MocrPreprocess() to speed up any following read or verify operation.

If you intend to reuse a font that you modified, save it using MocrSaveFont(), and restore it using MocrRestoreFont() when you need it.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
SystemId INQ

Specifies the system on which to allocate the OCR font context. This parameter should be set to one of the following values:

function map For specifying the system identifier
CollapseValue Description
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.
Collapse MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().
FontType INQ

Specifies the OCR font context type and the type of its font. This parameter should be set to one of the following values:

function map For specifying the context type and the type of its font
CollapseValue Description
Collapse M_DEFAULT

Same as M_USER_DEFINED.
Collapse M_SEMI_M12_92

Specifies a font respecting the SEMI M12-92 standard as the type of font. StringLength must be set to 12, the constraints (MocrSetConstraint()) for the target image are preset, and a checksum calculation is activated.

(summarize)
Collapse M_SEMI_M13_88

Specifies a font respecting the SEMI M13-88 standard as the type of font. StringLength must be set to 18, the constraints (MocrSetConstraint()) for the target image are preset, and a checksum calculation is activated.

(summarize)
Collapse M_USER_DEFINED +

Specifies a general, user-defined type of font. No maximum string length is set, the scale is set to 1.0, and the character spacing is the same as CharCellSizeX. No checksum is automatically associated with this OCR font context.


You must specify a combination value from the following table:
(summarize)
Combination constants for M_USER_DEFINED.

You must add one of the following values to the above-mentioned value to set the OCR font context type.

For more information about which context type to use, see the Guidelines for choosing context types section of Chapter 10: Optical character recognition.

function map For M_USER_DEFINED to specify the context type INQ
CollapseCombination value Description
Collapse M_CONSTRAINED

Specifies an OCR font context that works well with degraded target images and requires more information about the target string, but provides a more robust search. Note that using either M_SEMI_M12_92 or M_SEMI_M13_88 automatically sets the OCR font context type to M_CONSTRAINED.

This is the default value.

(summarize)
Collapse M_GENERAL

Specifies an OCR font context that works well with clean target images. It requires less information about the target string, but provides a less robust search.

If you are using clean target images but they are complex, have lighting variations, or require better binarization, you might consider trying the MIL String Reader module, which is more suitable for these cases. Note that under the correct conditions, OCR is typically faster.

(summarize)
CharNumber INQ

Specifies how many characters can be stored in the OCR font context. The maximum number of characters supported is 256.

CharCellSizeX INQ

Specifies the width of the characters in the OCR font context, in pixels.

function map For specifying the width of the characters in the context
CollapseValue Description
Collapse 6 <= Value <= 256

Specifies the width, in pixels.
CharCellSizeY INQ

Specifies the height of the characters in the OCR font context, in pixels.

function map For specifying the height of the characters in the context
CollapseValue Description
Collapse 6 <= Value <= 256

Specifies the height, in pixels.
CharOffsetX INQ

Specifies the distance between the edge of each character and their surrounding cell, along the X-axis, in pixels. The minimum recommended value is 1.

Typically, this is set to the same value as the character thickness.

CharOffsetY INQ

Specifies the distance between the edge of each character and their surrounding cell, along the Y-axis, in pixels. The minimum recommended value is 1.

CharSizeX INQ

Specifies the width of the widest character in the font without its surrounding cell, in pixels.

function map For specifying the width of the widest character in the font without its surrounding cell
CollapseValue Description
Collapse 6 <= Value <= 256

Specifies the width, in pixels. This should be equal to: CharCellSizeX - ( CharOffsetX *2).

Note that, to be able to search for a string over a range of angles, the font context's character size must be greater than 16x16.

(summarize)
CharSizeY INQ

Specifies the height of the tallest character in the font without its surrounding cell, in pixels.

function map For specifying the height of the tallest character in the font without its surrounding cell
CollapseValue Description
Collapse 6 <= Value <= 256

Specifies the height, in pixels. This should be equal to: CharCellSizeY - ( CharOffsetY *2).

Note that, to be able to search for a string over a range of angles, the font context's character size must be greater than 16x16.

(summarize)
CharThickness INQ

Specifies the maximum thickness (stroke width) of the characters in the OCR font context, in pixels.

StringLength INQ

Specifies the maximum length of the string that can be read or verified using the OCR font context. Note that if M_SEMI_M12_92 is used, the string length must be 12. If M_SEMI_M13_88 is used, the string length must be 18. The maximum string length is 100 characters.

InitFlag INQ

Specifies whether the characters are brighter than the background. This parameter should be set to one of the following values:

function map For specifying the character brightness
CollapseValue Description
Collapse M_FOREGROUND_BLACK

Specifies that the characters to read or verify are darker than the background.
Collapse M_FOREGROUND_WHITE

Specifies that the characters to read or verify are brighter than the background.
FontContextOcrIdPtr

Specifies the address of the variable to which the OCR font context identifier is to be written. Since the MocrAllocFont() function also returns the OCR font context identifier, you can set this parameter to M_NULL.

Return value
The returned value is the OCR font context identifier if the allocation is successful. If allocation fails, M_NULL is returned.
Example

An example of one character from the font, the letter 'E', follows:

MIL_ID FontID = M_NULL;
MocrAllocFont(M_DEFAULT, M_USER_DEFINED+M_GENERAL,
              26, 8, 11, 1, 1, 6, 9, 1, 26, M_FOREGROUND_BLACK, &FontID);

Would look as follows:

Compilation information
Header Include mil.h.
Library Use mil.lib; milocr.lib.
DLL Requires mil.dll; milocr.dll.
DEFAULT HOST DEFAULT SEMI M12 92 SEMI M13 88 USER DEFINED CONSTRAINED GENERAL FOREGROUND BLACK FOREGROUND WHITE