LEADTOOLS Drawing Engine and Multi-Platform Consideration

Parts of LEADTOOLS SDKs require the use of a draw (rendering) engine. For instance, loading a Microsoft Word DOCX file as a raster image requires first creating a drawing surface. Then, any file objects such as text, shapes, and images are rendered onto the surface. Rendering text requires resolving the fonts used (determining whether they exist on the system or need replacing). Font operations are also used during text recognition to find the text's properties and determine when to generate the final output.

All of this is handled internally and automatically by the LEADTOOLS tookit. In certain situations, however, customization is necessary to produce the desired results.

In the following discussion, "other platforms" refers to platforms other than the Windows desktop. These are platforms such as Linux, Android, macOS, iOS, and Universal Windows Platform (UWP).

Draw Engines

LEADTOOLS ships with the following draw engines, defined by the DrawEngineType enumeration:

DrawEngineType.DefaultEngine

The default engine for Windows is an internal rendering engine which uses Windows GDI/GDI+. This engine produces the fastest results for Windows.

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

The default engine is included in the following DLL/Library/Assembly:

DrawEngineType.Multiplatform

The multi-platform engine is also an internal rendering engine. It uses code independent of the operating system. This engine will always produce the same exact rendering results on all platforms. Currently, this engine is based on the OpenGL and FreeType libraries.

Currently, this is the default(only) rendering engine type supported by the LEADTOOLS toolkits for other platform environments.

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

Set the draw engine (globally) at the start or at any point of an application with the methods of the static DrawEngine class. This can be done easily, as shown in the following code:

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

Containers and Azure App Services

Some Docker Containers or Microsoft Azure App Services use a version of LEADTOOLS lacking most of the GDI/GDI+ functionality. Thus, errors will occur when trying to use LEADTOOLS with DrawEngineType.DefaultEngine. To avoid this, set the application to use DrawEngineType.Multiplatform at the start of the application as shown in the code above.

Shadow Fonts

Sometimes LEADTOOLS will have to create a font based on its 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: almost all Windows Desktops will have the "Arial" font family installed globally on the system. However, Linux or Android environments may not have the font. The rendering engine will then use the system's 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.

Font substitution can produce different results when running under Windows as opposed to Linux. Also, the font the system will use depends on the operating system version and any extra components 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 can ask the system if a font will be substituted, and can override this behavior to supply its own font data instead. LEADTOOLS setups ship with free fonts, hand-picked to be the most suitable substitution for the most common fonts found in documents. These fonts are stored in this folder:

Or add this package reference to the project if the application is using NuGet:

<PackageReference Include="Leadtools.SubstitutionFonts" Version="20.*" />

By using shadow fonts, LEADTOOLS can ensure that the document will:

• Use the best font substitution possible if a font is not found in the system

• Ensure the same behavior across all platforms

Font Substitution Control

The DrawShadowFontMode enumeration members control how and when font substitution occurs, as follows:

If the operation fails, then LEADTOOLS will use the system's font substitution. For instance, assume the mode is set to DrawShadowFontMode.SystemFirst while running on a Linux machine and LEADTOOLS is trying to create an "Arial" font which is not installed in the system. The following logic is used:

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

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

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

The following code 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); 

User Fonts

Applications may have a requirement to use custom fonts that are not installed in the operating system. For instance, to load and render a PDF or DOCX file containing a private non-system font that is shipped with the application. Adding the font to the operating system requires elevated administrative privileges and a separate process to distribute and install the fonts.

LEADTOOLS has support for using custom private fonts using the DrawEngine.AddUserFont methods.

These methods allow the application to add custom font(s) to the current process using LEADTOOLS only. Afterwards, LEADTOOLS will treat this font as if it was installed in the operating system and can participate as any other system font in any font substitution described in the section above. Standard TrueType (.ttf) and OpenType (.otf) fonts are currently supported.

DrawEngine.ClearUserFonts can be used to delete all user fonts previously added to LEADTOOLS.

This sample code will add all the fonts found in a private application directory to LEADTOOLS:

static void AddUserFonts(string fontsDirectory) 
{ 
   // Optional: Clear any previous user fonts. 
   DrawEngine.ClearUserFonts(); 
 
   // Iterate over all the font files found in the directory and add them 
   foreach (string fontFile in Directory.EnumerateFiles(fontsDirectory, "*.*")) 
   { 
      // Is it a font file? 
      string extension = Path.GetExtension(fontFile); 
      if (extension == ".ttf" || extension == ".otf") 
      { 
         DrawEngine.AddUserFont(fontFile); 
      } 
   } 
} 

Multi-Platform Identical Rendering on OCR, Document Reader/Writer and Document Conversion

In order to produce identical rendering when using OCR, Document Reader/Writer and Document Conversion on multiple platforms (such as Windows and Linux), the following conditions must be satisfied:

• The multi-platform engine must be used

• (Optional but recommended), the shadow fonts pack must be available and their usage identical in all platforms.

For instance, consider a .NET Core application which is using LEADTOOLS to use the Document Converter including OCR. This application can be deployed on Windows and Linux machines. Further, one of the requirements might be that the application should produce 100% identical rendering across all platforms. To achieve this, insert the following code at the start of the application:

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

See Also

• RasterImage and GDI/GDI+