Skip to main content

General technical notes

This documentation explains how the Pdftools SDK interacts with your local operating system to locate fonts, locate color profiles, and store temporary files and cache files.

Locating fonts​

Some Pdftools SDK features require fonts to be installed locally.

For example, the PDF/A standard requires all fonts to be embedded in the PDF file. If non-embedded fonts are used in the original PDF, the fonts must be embedded during conversion to PDF/A. To embed fonts, a matching font has to be located in the font directories.

Font directories​

The location of the font directories depends on the operating system.

The SDK traverses font directories recursively in the order specified. If two fonts with the same name are found, the latter takes precedence. As a result, user fonts always take precedence over system fonts.

Installing fonts on Windows​

By default, Windows installs fonts only for a particular user. Either install fonts for all users or make sure you run the Pdftools SDK under that user and load the user profile.

The font directories for Windows are:

  1. %SystemRoot%\Fonts
  2. User fonts listed in the registry key: 
    \HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Fonts
    Fonts listed in the registry key include user specific fonts from: 
    C:\Users\<user>\AppData\Local\Microsoft\Windows\Fonts
    Also, app specific fonts from: 
    C:\Program Files\WindowsApps
  3. Fonts directory, which must be a direct subdirectory of where PdfToolsSdkAPI.dll resides.

The SDK traverses the directories recursively in this order.

Installing fonts on Linux and Debian systems​

On Linux, install the Liberation fonts, Google Noto CJK fonts, and the OpenSymbol font.

On Debian-based systems, the packages are fonts-liberation2, fonts-noto-cjk, and fonts-opensymbol.

Many PDF documents use Microsoft core fonts such as Arial, Times New Roman, and other fonts commonly used on Windows. Therefore, install these fonts to your default font directories.

Linux distributions often offer an installable package for Microsoft TrueType core fonts. For instance, on Debian-based systems, the package is ttf-mscorefonts-installer. Alternatively, you can download the fonts from SourceForge Core Fonts.

For more information on Microsoft core fonts and licensing, see Font redistribution FAQ for Windows.

The font directories for Linux are the following:

  1. /usr/share/fonts
  2. /usr/local/share/fonts
  3. ~/.fonts
  4. /usr/lib/X11/fonts/Type1, which can be overridden by setting the environment variable PDFFONTDIR.

The SDK traverses the directories recursively in this order.

Installing fonts on macOS​

On macOS, install the Liberation fonts, Google Noto CJK fonts, and the OpenSymbol font.

Many PDF documents use Microsoft core fonts such as Arial, Times New Roman, and other fonts commonly used on Windows. Therefore, install these fonts to your default font directories. You can download the fonts from SourceForge Core Fonts.

For more information on Microsoft core fonts and licensing, see Font redistribution FAQ for Windows.

The font directories for macOS are the following:

  1. /System/Library/Fonts
  2. /Library/Fonts

The SDK traverses the directories recursively in this order.

Adding custom font lookup paths​

In addition to the directories listed above, developers can specify custom font lookup paths using the following methods:

Font cache​

A cache of all fonts in all font directories is created. If fonts are added or removed from the font directories, the cache is updated automatically.

To achieve optimal performance, make sure that the cache directory is writable for the Pdftools SDK. Otherwise, the font cache cannot be updated and the font directories have to be scanned on each program startup.

The font cache is created in the subdirectory <CacheDirectory>/Installed Fonts of the cache directory.

Locating color profiles​

If no color profiles are available, default profiles for both RGB and CMYK are generated on the fly by the Pdftools SDK. If no specific color profiles are set, default profiles are used. By default, the SDK uses the color profile “sRGB Color Space Profile.icm” for device RGB colors, and “USWebCoatedSWOP.icc” for device CMYK. It searches for these profiles in the specified directories:

  1. %SystemRoot%\System32\spool\drivers\color
  2. directory Icc, which must be a direct sub-directory of where the PdfToolsSdkAPI.dll resides.

Most systems have pre-installed color profiles. For example, on Windows at %SystemRoot%\system32\spool\drivers\color\.

You can download color profiles from the links provided in the bin\Icc\ directory or from these websites:

Special directories​

The Pdftools SDK uses special directories during file processing. For optimal performance, the application should have write access to these directories.

Temporary files directory​

The directory of temporary files is used for data specific to one instance of a program. The data isn’t shared between different invocations and is deleted after the program is terminated.

The SDK determines the directory as follows by checking for the existence of environment variables in the following order and using the first path found:

  1. The path specified by the %TMP% environment variable.
  2. The path specified by the %TEMP% environment variable.
  3. The path specified by the %USERPROFILE% environment variable.
  4. The Windows directory.

Cache directory​

The cache directory is used for data that persists and is shared between different invocations of a program. The SDK creates the actual caches in subdirectories. You can safely delete the content of this directory to clean all caches.

The application must be able to write to this directory. Otherwise, the SDK can’t create or update caches, leading to significantly decreased performance.

If the user has a profile:

%LOCAL_APPDATA%\PDF Tools AG\Caches

If the user has no profile:

<TempDirectory>\PDF Tools AG\Caches