LEADTOOLS Drawing Engine and Multi-Platform Consideration

Parts of LEADTOOLS require the use of a drawing (rendering) engine. For instance, loading a Microsoft Word DOCX file as a raster image requires creating a drawing surface and rendering the file objects such as text, shapes and images into the surface. When rendering the text objects, LEADTOOLS must also try to resolve the fonts used (whether they exist on the system or be substituted by a suitable font). The fonts operations are also used by the LEADTOOLS OCR engine when recognizing the text of a document to find the properties of the text and when to generate the final output document.

All of this is handled internally and automatically by LEADTOOLS. However, in certain situation, the mechanism must be customized to produce the desired results.

In the next discussion, other platforms will indicate platforms other than Windows Desktop such as Linux, Android, macOS, iOS and Universal Windows Platform (UWP).

Draw Engines

LEADTOOLS ships with the following drawing engines defined by the DrawEngineType enumeration:


In the Windows Desktop environment, this is an internal rendering engine that uses Windows GDI/GDI+. This engine produces the fastest results for Windows and is used as the default engine in this version of LEADTOOLS.

In other platform environments, DrawEngineType.DefaultEngine is the same as DrawEngineType.Multiplatform.

This engine is included in the following DLL/Library/Assembly:

Platform DLL/Library/Assembly
Windows .NET Leadtools.Drawing.dll
Windows CDLL ltdrw?.dll
Linux N/A
Android N/A
macOS N/A


This is an internal rendering engine that uses code independent on the operation system. Using this engine will always produce the same exact results in all platforms. Currently, this is based on the OpenGL and freetype libraries.

In other platform environments, this is the default (and only) rendering engine type supported currently supported by LEADTOOLS.

This engine is included in the following DLL/Library/Assembly:

Platform DLL/Library/Assembly
Windows .NET Leadtools.Drawing.MP.dll
Windows CDLL ltdrwmp?.dll
Linux libltdrw.so
Android libleadtools.drawing.so
macOS Leadtools.Drawing.framework
iOS Leadtools.Drawing.framework
UWP Leadtools.Drawing.Native.dll

The draw engine can be set globally at the start or during any point of an application using LEADTOLS using the methods of the static DrawEngine class:

DrawEngineOptions options = DrawEngine.GetOptions(); 
options.DrawEngine = DrawEngineType.Multiplatform; 

Containers and Azure App Service

Certain Docker Container or Microsoft Azure App Services uses a version of LEADTOOLS lacking most of the GDI/GDI+ functionality. Therefore, errors will occur when trying to use LEADTOOLS with the default drawing engine that uses this system. Therefore it is recommended (or even necessary) to set up the application to the multi-platform engine at the start of the application as shown above.

Shadow Fonts

LEADTOOLS will sometimes have to create a font based on a family name only, for example, when a Microsoft Word DOCX file containing a font of family name "Arial" is rendered. Here, LEADTOOLS will use the current drawing engine to create an internal font object. In a Windows environment, this is not a problem since almost all Windows Desktop will have the "Arial" font family installed globally in the system. However, the font might not be available on a Linux or Android environment. The rendering engine will then use the system standard font substitution (https://en.wikipedia.org/wiki/Font_substitution) to replace the font with the most suitable one available. In the case of "Arial", this might be the "Generic Sans Serif" font.

This operation may result in a program producing different results when running under Windows or under Linux. Also, which font the system will use depends on the operating system version and on the extra components are installed. For instance, "Arial" can be installed on Linux systems using the Microsoft Fonts package for Linux. If this component is installed, "Arial" is found and used, otherwise "Generic Sans Serif" will be used.

The draw engine has the capability to enquire the system if a font will be substituted and can override this behavior to supply its own font data to be used instead. LEADTOOLS setup ships with free fonts that are hand-picked to be the most suitable substitution for the most common fonts found in documents. These fonts are stored in the [Your Installation Folder]\Bin\Common\ShadowFonts folder. By using the shadow fonts, LEADTOOLS can ensure that the document will a) use the best font possible if not found in the system, and/or b) ensure that that behavior is the same across all platforms.

LEADTOOLS allows the user to control how and when fonts are substituted using the DrawShadowFontMode enumeration members as follows:

DrawShadowFontMode Description
Auto Default mode. Same as SystemFirst in Windows. Same as ShadowFirst in other platforms.
SystemFirst Tries the system (operating system) first. If the font is not available, tries the shadow fonts directory. This is the default mode in Windows.
ShadowFirst Tries the shadow fonts first. If the font is not available, tries the system. This is the default mode in the other platforms.

If the operation fails, then LEADTOOLS will use the system font substitution. For instance, assume the mode was set to DrawShadowFontMode.SystemFirst while running on a Linux machine and LEADTOOLS is trying to create the font "Arial" that is not installed in the system:

  1. First checks the system if "Arial" is installed or not. If so, it uses it.
  2. If no "Arial" font is installed, then checks that the shadow font directory is set and a font with the name "lt-liberationsans-regular.ttf" is found. If so, it uses it. Otherwise:
  3. Lets Linux substitute the font. This will usually create a font of type "Generic Sans Serif"

The shadow font mode can be set globally at the start or during any point of an application using LEADTOOLS using:

DrawEngineOptions options = DrawEngine.GetOptions(); 
options.ShadowFontMode = DrawShadowFontMode.ShadowFirst; 

The following can be used to get or set the folder where LEADTOOLS looks for the shadow fonts in the system:

string value = RasterDefaults.GetResourceDirectory(LEADResourceDirectory.Fonts); 
RasterDefaults.SetResourceDirectory(LEADResourceDirectory.Fonts, value); 

Multi-Platform Identical Results on OCR and Document Conversion

To produce identical results when using OCR or Document Conversion on multiple platforms (such as Windows and Linux). The multi-platform engine must be used and optionally (but recommended), the shadow fonts pack must be available and their usage identical in all platforms.

For instance, a .NET Core application uses the LEADTOOLS to Document Converter including OCR. This application can then be deployed on Windows and Linux machines. One of the requirements might be that the application should produce 100% identical results across platforms. Therefore, at the start of the application:

void Initialize() 
   DrawEngineOptions options = DrawEngine.GetOptions(); 
   // Setup LEADTOOLS to use the multi-platform draw engine 
   options.DrawEngine = DrawEngineType.Multiplatform; 
   // Always use the shadow fonts first: 
   options.ShadowFontMode = DrawShadowFontMode.ShadowFirst; 
   // Set the shadow fonts directory (under LEADTOOLS/ShadowFonts in this system) 
   string shadowDirPath = Path.Combine(AppContext.BaseDirectory, "LEADTOOLS", "ShadowFonts"); 
   RasterDefaults.SetResourceDirectory(LEADResourceDirectory.Fonts, shadowDirPath); 

Help Version 20.0.2018.9.5
Products | Support | Contact Us | Copyright Notices
© 1991-2018 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Imaging, Medical, and Document