Header: FIL.h
Namespace: fil
Module: DL_OCR

Performs text detection using a pre-trained deep learning model.


void fil::FisFilter_DL_LocateText
	const fil::Image& inImage,
	ftl::Optional<const fil::Rectangle2D&> inRoi,
	ftl::Optional<const fil::CoordinateSystem2D&> inRoiAlignment,
	const fil::LocateTextModelId& inModelId,
	const int inCharHeight,
	const float inWidthScale,
	const int inOpenRadius,
	const int inMinTextArea,
	const int inExpandPixels,
	fil::Heatmap& outHeatmap,
	ftl::Array<fil::Region>& outTextRegions,
	ftl::Array<fil::LocateTextResult>& outResults,
	ftl::Optional<fil::Rectangle2D&> outAlignedRoi = ftl::NIL


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 LocateTextModelId& 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
inOpenRadius const int 0 - 0 Additional filtering of smaller blobs before merging characters into groups
Input value
inMinTextArea const int 0 - 50 Minimal character area to be considered as a candidate for a text part
Input value
inExpandPixels const int 0 - 11 Additional padding around the found character to be added before merging characters into text
Output value
outHeatmap Heatmap& Raw heatmap returned by network. It may be useful for more complex analysis
Output value
outTextRegions Array<Region>& Extracted characters regions after filtering
Output value
outResults Array<LocateTextResult>&
Output value
outAlignedRoi Optional<Rectangle2D&> NIL


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 oriented text on image. Without additional training, it is suitable for locating text:
  1. oriented with angle up to ± 90 degrees,
  2. if height between 60% and 140% of inCharHeight (in pixels)
  3. being latin letters (upper- or lower-case), digits or one of: !#$%&()*+,-./:;<=>?@[]^_`{|}~"'\€£¥¢.

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 (specifically, capital letters) 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 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.


inWidthScale = 1

inWidthScale = 1

The inMinTextArea parameter may be used to change minimum area of predicted text. Detected text with area below this limit will be discarded. By default, this parameter is set to 50.

The inOpenRadius helps disjoint merged words, by applying Open Morphological filter on heatmap. By default, it's set to 0. Example:

inOpenRadius = 0

inOpenRadius = 3

The inExpandPixels parameter adds extra padding to outResults.Box. By default it's set to 11.

Too big inOpenRadius value on image with small text may cause issues with disappearing or wrong oriented boxes. Try to reduce this value if it happens. Example of too big inOpenRadius value:


  1. Reducing ROI may give a high performance boost.
  2. 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.
  3. Too big inOpenRadius value on image with small text may cause issues with disappearing or wrong oriented boxes. Try to reduce this value if it happens.


List of possible exceptions:

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