Header: FILDL.h
Namespace: fil
Module: DeepLearning

Performs optical character recognition using a pretrained deep learning model.


void fil::DL_ReadCharacters
	const fil::Image& inImage,
	ftl::Optional<const fil::Rectangle2D&> inRoi,
	ftl::Optional<const fil::CoordinateSystem2D&> inRoiAlignment,
	const fil::ReadCharactersModelId& inModelId,
	const int inCharHeight,
	const float inWidthScale,
	ftl::Optional<const ftl::String&> inCharRange,
	const float inMinScore,
	ftl::Array<fil::OcrResult>& outCharacters,
	ftl::Array<fil::Image>& outMasks,
	ftl::Optional<fil::Rectangle2D&> outAlignedRoi = ftl::NIL,
	fil::Image& diagInputImage


Name Type Range Default Description
Input value
inImage const Image& Input image
Input value
inRoi Optional<const Rectangle2D&> NIL Limits the area where recognized characters are located
Input value
inRoiAlignment Optional<const CoordinateSystem2D&> NIL
Input value
inModelId const ReadCharactersModelId& Identifier of a Read Characters model
Input value
inCharHeight const int 8 - 35 Average height of characters in pixels
Input value
inWidthScale const float 0.1 - 10.0 1.0f Scales image width by the given factor
Input value
inCharRange Optional<const String&> \"A-Z,a-z,0-9,\\\\\\\\,/,-\" Limits the set of wanted characters
Input value
inMinScore const float 0.0 - 1.0 0.5f Sets a minimum required score for a character to be returned
Output value
outCharacters Array<OcrResult>&
Output value
outMasks Array<Image>& Masks of found characters. Contains empty images in case of using model not supporting masks.
Output value
outAlignedRoi Optional<Rectangle2D&> NIL Input roi after transformation
Diagnostic input
diagInputImage Image& Analysed area of the input image


For input inImage only pixel formats are supported: 1⨯uint8, 3⨯uint8.

Read more about pixel formats in Image documentation.

Optional Outputs

The computation of following outputs can be switched off by passing value ftl::NIL to these parameters: outAlignedRoi.

Read more about Optional Outputs.


This tool locates and recognizes characters. By default, it is suitable for reading characters:

  • horizontally oriented,
  • with height in pixels being between 60% of inCharHeight and 140% of inCharHeight
  • being latin letters (upper- or lower-case), digits or one of: !#$%&()*+,-./:;<=>[email protected][]^_`{|}~"'\€£¥.

This behavior can be configured with parameters described below.

The inRoi and inRoiAlignment inputs may be used to limit the analysed area, which, in most cases, leads to improved performance. Moreover, it may be used to adjust to text which is not horizontally oriented.

The inCharHeight should be set to the average height of characters in the analysed area. E.g. if image contains 2 kind of characters: one being 24 pixels high and the second being 40 pixels high, inCharHeight should be set to 32, irrespective of number of characters of each kind.

In case of fonts with exceptionally thin or wide symbols, inWidthScale may be used to reshape them to a more "typical" aspect ratio. The analysed area will be scaled by inWidthScale in the horizontal axis. It may improve quality of results. Furthermore, it may also help in reading a text with tight spaces between subsequent characters.

To limit the set of recognized characters, inCharRange may be used. This string has to be formatted according to the following rules:

  • allowed characters have to be separated with commas,
  • for ease of use, continuous range of letters or digits, may be written as starting_character-ending_character, e.g. A-Z or 1-6,
  • comma and backslash have to be prepended with backslash.

For example, inCharRange equal to A-F,g-o,0-9,X,Y,Z,-,\\,\, will result in recognizing only ABCDEFXYZghijklmno0123456789-\, characters.

The inMinScore parameter may be used to change minimum score of a character. By default, this threshold is set to 0.5.


  • It is recommended that the deep learning model is deployed with DL_ReadCharacters_Deploy first and connected through the inModelId input.
  • If one decides not to use DL_ReadCharacters_Deploy, then the model will be loaded in the first iteration. It will take up to several seconds.
  • In case of characters having too much differing height, it is advised to separate the analysed area (e.g. with inRoi input) to smaller parts containing symbols with a more consistent height.


This filter should not be executed along with running Deep Learning Service as it may result in degraded performance or even out-of-memory errors.


List of possible exceptions:

Error type Description
DomainError Not supported inImage pixel format in DL_ReadCharacters. Supported formats: 1xUInt8, 3xUInt8.

See Also