https://www.pdf-tools.com/docs/assets/js/3986f210.1d8d7164.js

1"use strict";(self.webpackChunkpdftools_doc=self.webpackChunkpdftools_doc||[]).push([["10411"],{660162(e,s,n){n.r(s),n.d(s,{metadata:()=>o,default:()=>x,frontMatter:()=>a,contentTitle:()=>h,toc:()=>p,assets:()=>f});var o=JSON.parse('{"id":"api-references/technical-notes/general-notes","title":"General technical notes","description":"Technical details about Pdftools SDK for all programming languages.","source":"@site/pdf-tools-sdk_versioned_docs/version-1.16/api-references/technical-notes/general-notes.mdx","sourceDirName":"api-references/technical-notes","slug":"/api-references/technical-notes/general-notes","permalink":"/docs/pdf-tools-sdk/1.16/api-references/technical-notes/general-notes","draft":false,"unlisted":false,"tags":[{"inline":false,"label":"Pdftools sdk","permalink":"/docs/pdf-tools-sdk/1.16/tags/pdftools-sdk","description":"General documentation and guides for Pdftools SDK PDF processing library."},{"inline":false,"label":"Technical notes","permalink":"/docs/pdf-tools-sdk/1.16/tags/technical-notes","description":"Technical notes and in-depth information about Pdftools SDK."},{"inline":false,"label":"Pdf library in c","permalink":"/docs/pdf-tools-sdk/1.16/tags/pdf-library-in-c","description":"Documentation and code samples for using Pdftools SDK in C applications."},{"inline":false,"label":"Pdf library in .net","permalink":"/docs/pdf-tools-sdk/1.16/tags/pdf-library-in-net","description":"Documentation and code samples for using Pdftools SDK in .NET applications."},{"inline":false,"label":"Pdf library in java","permalink":"/docs/pdf-tools-sdk/1.16/tags/pdf-library-in-java","description":"Documentation and code samples for using Pdftools SDK in Java applications."}],"version":"1.16","frontMatter":{"title":"General technical notes","description":"Technical details about Pdftools SDK for all programming languages.","sidebar_label":"General technical notes","tags":["Pdftools SDK","Technical notes","PDF library in C","PDF library in .NET","PDF library in Java"],"toc_max_heading_level":4},"sidebar":"toolsSdk","previous":{"title":"Technical notes","permalink":"/docs/pdf-tools-sdk/1.16/api-references/technical-notes/"},"next":{"title":"C","permalink":"/docs/pdf-tools-sdk/1.16/api-references/technical-notes/c-notes"}}'),r=n(474848),i=n(28453),t=n(327154),l=n.n(t),d=n(729694),c=n.n(d);let a={title:"General technical notes",description:"Technical details about Pdftools SDK for all programming languages.",sidebar_label:"General technical notes",tags:["Pdftools SDK","Technical notes","PDF library in C","PDF library in .NET","PDF library in Java"],toc_max_heading_level:4},h,f={},p=[{value:"Locate fonts",id:"locate-fonts",level:2},{value:"Font directories",id:"font-directories",level:3},{value:"Installing fonts on Windows",id:"installing-fonts-on-windows",level:4},{value:"Installing fonts on Linux and Debian systems",id:"installing-fonts-on-linux-and-debian-systems",level:4},{value:"Installing fonts on macOS",id:"installing-fonts-on-macos",level:4},{value:"Add custom font lookup paths",id:"add-custom-font-lookup-paths",level:3},{value:"Font cache",id:"font-cache",level:3},{value:"Locate color profiles",id:"locate-color-profiles",level:2},{value:"Special directories",id:"special-directories",level:2},{value:"Temporary files directory",id:"temporary-files-directory",level:3},{value:"Cache directory",id:"cache-directory",level:3}];function u(e){let s={a:"a",code:"code",h2:"h2",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)(s.p,{children:["This documentation explains how the Pdftools SDK interacts with your local operating system to ",(0,r.jsx)(s.a,{href:"#locate-fonts",children:"locate fonts"}),", ",(0,r.jsx)(s.a,{href:"#locate-color-profiles",children:"locate color profiles"}),", and store ",(0,r.jsx)(s.a,{href:"#temporary-files-directory",children:"temporary files"})," and ",(0,r.jsx)(s.a,{href:"#cache-directory",children:"cache files"}),"."]}),"\n","\n",(0,r.jsx)(s.h2,{id:"locate-fonts",children:"Locate fonts"}),"\n",(0,r.jsx)(s.p,{children:"Some Pdftools SDK features require fonts to be installed locally."}),"\n",(0,r.jsxs)(s.p,{children:["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 ",(0,r.jsx)(s.a,{href:"#font-directories",children:"font directories"}),"."]}),"\n",(0,r.jsx)(s.h3,{id:"font-directories",children:"Font directories"}),"\n",(0,r.jsx)(s.p,{children:"The location of the font directories depen

1ds on the operating system."}),"\n",(0,r.jsx)(s.p,{children:"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."}),"\n",(0,r.jsx)(s.h4,{id:"installing-fonts-on-windows",children:"Installing fonts on Windows"}),"\n",(0,r.jsx)(s.p,{children:"By default, Windows installs fonts only for a particular user.\nEither install fonts for all users or make sure you run the\nPdftools SDK under that user and load the user profile."}),"\n",(0,r.jsx)(s.p,{children:"The font directories for Windows are:"}),"\n",(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.code,{children:"%SystemRoot%\\Fonts"})}),"\n",(0,r.jsxs)(s.li,{children:["User fonts listed in the registry key:","\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"\\HKEY_CURRENT_USER\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Fonts\n"})}),"\n","Fonts listed in the registry key include user specific fonts from:","\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"C:\\Users\\<user>\\AppData\\Local\\Microsoft\\Windows\\Fonts\n"})}),"\n","Also, app specific fonts from:","\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"C:\\Program Files\\WindowsApps\n"})}),"\n"]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"Fonts"})," directory, which must be a direct subdirectory of where ",(0,r.jsx)(s.code,{children:"PdfToolsSdkAPI.dll"})," resides."]}),"\n"]}),"\n",(0,r.jsx)(s.p,{children:"The SDK traverses the directories recursively in this order."}),"\n",(0,r.jsx)(s.h4,{id:"installing-fonts-on-linux-and-debian-systems",children:"Installing fonts on Linux and Debian systems"}),"\n",(0,r.jsx)(s.p,{children:"On Linux, install the Liberation fonts, Google Noto CJK fonts, and the OpenSymbol font."}),"\n",(0,r.jsxs)(s.p,{children:["On Debian-based systems, the packages are ",(0,r.jsx)(s.code,{children:"fonts-liberation2"}),", ",(0,r.jsx)(s.code,{children:"fonts-noto-cjk"}),", and ",(0,r.jsx)(s.code,{children:"fonts-opensymbol"}),"."]}),"\n",(0,r.jsx)(s.p,{children:"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."}),"\n",(0,r.jsxs)(s.p,{children:["Linux distributions often offer an installable package for Microsoft TrueType core fonts. For instance, on Debian-based systems, the package is ",(0,r.jsx)(s.code,{children:"ttf-mscorefonts-installer"}),". Alternatively, you can download the fonts from ",(0,r.jsx)(s.a,{href:"http://corefonts.sourceforge.net/",children:"SourceForge Core Fonts"}),"."]}),"\n",(0,r.jsxs)(s.p,{children:["For more information on Microsoft core fonts and licensing, see ",(0,r.jsx)(s.a,{href:"https://docs.microsoft.com/en-us/typography/fonts/font-faq",children:"Font redistribution FAQ for Windows"}),"."]}),"\n",(0,r.jsx)(s.p,{children:(0,r.jsx)(s.strong,{children:"The font directories for Linux are the following:"})}),"\n",(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.code,{children:"/usr/share/fonts"})}),"\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.code,{children:"/usr/local/share/fonts"})}),"\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.code,{children:"~/.fonts"})}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"/usr/lib/X11/fonts/Type1"}),", which can be overridden by setting the environment variable ",(0,r.jsx)(s.code,{children:"PDFFONTDIR"}),"."]}),"\n"]}),"\n",(0,r.jsx)(s.p,{children:"The SDK traverses the directories recursively in this order."}),"\n",(0,r.jsx)(s.h4,{id:"installing-fonts-on-macos",children:"Installing fonts on macOS"}),"\n",(0,r.jsx)(s.p,{children:"On macOS, install the Liberation fonts, Google Noto CJK fonts, and the OpenSymbol font."}),"\n",(0,r.jsxs)(s.p,{children:["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 ",(0,r.jsx)(s.a,{href:"http://corefonts.sourceforge.net/",children:"SourceForge Core Fonts"}),"."]}),"\n",(0,r.jsxs)(s.p,{children:["For more information on Microsoft core fonts and licensing, see ",(0,r.jsx)(s.a,{href:"https://docs.microsoft.com/en-us

1/typography/fonts/font-faq",children:"Font redistribution FAQ for Windows"}),"."]}),"\n",(0,r.jsx)(s.p,{children:(0,r.jsx)(s.strong,{children:"The font directories for macOS are the following:"})}),"\n",(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.code,{children:"/System/Library/Fonts"})}),"\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.code,{children:"/Library/Fonts"})}),"\n"]}),"\n",(0,r.jsx)(s.p,{children:"The SDK traverses the directories recursively in this order."}),"\n",(0,r.jsx)(s.h3,{id:"add-custom-font-lookup-paths",children:"Add custom font lookup paths"}),"\n",(0,r.jsx)(s.p,{children:"In addition to the directories listed above, developers can specify custom font lookup paths using the following methods:"}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:["C: ",(0,r.jsx)(s.a,{href:"https://api-reference.pdf-tools.com/pdfsdk/1.16/cdoc/_pdf_tools___pdf_tools_8h.html#afb5780e0a309889566e945040deffb74",children:"PdfTools_Sdk_AddFontDirectoryA"})," or ",(0,r.jsx)(s.a,{href:"https://api-reference.pdf-tools.com/pdfsdk/1.16/cdoc/_pdf_tools___pdf_tools_8h.html#a8b13e5d769c96c96edf4af36c57c6dbc",children:"PdfTools_Sdk_AddFontDirectoryW"})]}),"\n",(0,r.jsxs)(s.li,{children:["C#: ",(0,r.jsx)(s.a,{href:"https://api-reference.pdf-tools.com/pdfsdk/1.16/dotnet/html/M_PdfTools_Sdk_AddFontDirectory.htm",children:"Sdk.AddFontDirectory"})]}),"\n",(0,r.jsxs)(s.li,{children:["Java: ",(0,r.jsx)(s.a,{href:"https://api-reference.pdf-tools.com/pdfsdk/1.16/javadoc/com/p

1dftools/Sdk.html#addFontDirectory(java.lang.String)",children:"Sdk.addFontDirectory"})]}),"\n",(0,r.jsxs)(s.li,{children:["Python: ",(0,r.jsx)(s.a,{href:"https://api-reference.pdf-tools.com/pdfsdk/1.16/pydocs/_autosummary/pdftools_sdk.sdk.html#pdftools_sdk.sdk.Sdk.add_font_directory",children:"sdk.add_font_directory"})]}),"\n"]}),"\n",(0,r.jsx)(s.h3,{id:"font-cache",children:"Font cache"}),"\n",(0,r.jsx)(s.p,{children:"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."}),"\n",(0,r.jsx)(s.p,{children:"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."}),"\n",(0,r.jsxs)(s.p,{children:["The font cache is created in the subdirectory ",(0,r.jsx)(s.code,{children:"<CacheDirectory>/Installed Fonts"})," of the cache directory."]}),"\n",(0,r.jsx)(s.h2,{id:"locate-color-profiles",children:"Locate color profiles"}),"\n",(0,r.jsx)(s.p,{children:"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 \u201CsRGB Color Space Profile.icm\u201D for device RGB colors, and \u201CUSWebCoatedSWOP.icc\u201D for device CMYK. It searches for these profiles in the specified directories:"}),"\n",(0,r.jsxs)(l(),{groupId:"operating-systems",children:[(0,r.jsx)(c(),{value:"win",label:"Windows",children:(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.code,{children:"%SystemRoot%\\System32\\spool\\drivers\\color"})}),"\n",(0,r.jsxs)(s.li,{children:["directory ",(0,r.jsx)(s.code,{children:"Icc"}),", which must be a direct sub-directory of where the ",(0,r.jsx)(s.code,{children:"PdfToolsSdkAPI.dll"})," resides."]}),"\n"]})}),(0,r.jsx)(c(),{value:"linux",label:"Linux",children:(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"$PDF_ICC_PATH"})," if the environment variable is defined"]}),"\n",(0,r.jsx)(s.li,{children:"the current working directory"}),"\n"]})}),(0,r.jsx)(c(),{value:"macos",label:"macOS",children:(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"$PDF_ICC_PATH"})," if the environment variable is defined"]}),"\n",(0,r.jsx)(s.li,{children:"the current working directory"}),"\n"]})})]}),"\n",(0,r.jsxs)(s.p,{children:["Most systems have pre-installed color profiles. For example, on Windows at ",(0,r.jsx)(s.code,{children:"%SystemRoot%\\system32\\spool\\drivers\\color\\"}),"."]}),"\n",(0,r.jsxs)(s.p,{children:["You can download color profiles from the links provided in the ",(0,r.jsx)(s.code,{children:"bin\\Icc\\"})," directory or from these websites:"]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.a,{href:"http://www.pdf-tools.com/public/downloads/resources/colorprofiles.zip",children:"Pdftools color profiles"})}),"\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.a,{href:"http://www.color.org/srgbprofiles.html",children:"ICC sRGB profiles"})}),"\n",(0,r.jsx)(s.li,{children:(0,r.jsx)(s.a,{href:"https://www.adobe.com/support/downloads/iccprofiles/iccprofiles_win.html",children:"Adobe ICC Profiles"})}),"\n"]}),"\n",(0,r.jsx)(s.h2,{id:"special-directories",children:"Special directories"}),"\n",(0,r.jsx)(s.p,{children:"The Pdftools SDK uses special directories during file processing. For optimal performance, the application should have write access to these directories."}),"\n",(0,r.jsx)(s.h3,{id:"temporary-files-directory",children:"Temporary files directory"}),"\n",(0,r.jsx)(s.p,{children:"The directory of temporary files is used for data specific to one instance of a program. The data isn\u2019t shared between different invocations and is deleted after the program is terminated."}),"\n",(0,r.jsx)(s.p,{children:"The SDK determines the directory as follows by checking for the existence of environment variables in the following order and using the first path foun

1d:"}),"\n",(0,r.jsxs)(l(),{groupId:"operating-systems",children:[(0,r.jsx)(c(),{value:"win",label:"Windows",default:!0,children:(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsxs)(s.li,{children:["The path specified by the ",(0,r.jsx)(s.code,{children:"%TMP%"})," environment variable."]}),"\n",(0,r.jsxs)(s.li,{children:["The path specified by the ",(0,r.jsx)(s.code,{children:"%TEMP%"})," environment variable."]}),"\n",(0,r.jsxs)(s.li,{children:["The path specified by the ",(0,r.jsx)(s.code,{children:"%USERPROFILE%"})," environment variable."]}),"\n",(0,r.jsx)(s.li,{children:"The Windows directory."}),"\n"]})}),(0,r.jsx)(c(),{value:"linux",label:"Linux",children:(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsxs)(s.li,{children:["The path specified by the ",(0,r.jsx)(s.code,{children:"$PDFTMPDIR"})," environment variable."]}),"\n",(0,r.jsxs)(s.li,{children:["The path specified by the ",(0,r.jsx)(s.code,{children:"$TMP"})," environment variable."]}),"\n",(0,r.jsxs)(s.li,{children:["The ",(0,r.jsx)(s.code,{children:"/tmp"})," directory."]}),"\n"]})}),(0,r.jsx)(c(),{value:"macos",label:"macOS",children:(0,r.jsxs)(s.ol,{children:["\n",(0,r.jsxs)(s.li,{children:["The path specified by the ",(0,r.jsx)(s.code,{children:"$PDFTMPDIR"})," environment variable."]}),"\n",(0,r.jsxs)(s.li,{children:["The path specified by the ",(0,r.jsx)(s.code,{children:"$TMP"})," environment variable."]}),"\n",(0,r.jsxs)(s.li,{children:["The ",(0,r.jsx)(s.code,{children:"/tmp"})," directory."]}),"\n"]})})]}),"\n",(0,r.jsx)(s.h3,{id:"cache-directory",children:"Cache directory"}),"\n",(0,r.jsx)(s.p,{children:"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."}),"\n",(0,r.jsx)(s.p,{children:"The application must be able to write to this directory. Otherwise, the SDK can\u2019t create or update caches, leading to significantly decreased performance."}),"\n",(0,r.jsxs)(l(),{groupId:"operating-systems",children:[(0,r.jsxs)(c(),{value:"win",label:"Windows",default:!0,children:[(0,r.jsx)(s.p,{children:"If the user has a profile:"}),(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"%LOCAL_APPDATA%\\PDF Tools AG\\Caches\n"})}),(0,r.jsx)(s.p,{children:"If the user has no profile:"}),(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"<TempDirectory>\\PDF Tools AG\\Caches\n"})})]}),(0,r.jsxs)(c(),{value:"linux",label:"Linux",children:[(0,r.jsx)(s.p,{children:"If the user has a home directory:"}),(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"~/.pdf-tools/Caches\n"})}),(0,r.jsx)(s.p,{children:"If the user has no home directory:"}),(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"<TempDirectory>/pdf-tools/Caches\n"})}),(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.code,{children:"<TempDirectory>"})," refers to the ",(0,r.jsx)(s.a,{href:"#temporary-files-directory",children:"directory for temporary files"}),"."]})]}),(0,r.jsxs)(c(),{value:"macos",label:"macOS",children:[(0,r.jsx)(s.p,{children:"If the user has a home directory:"}),(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"~/.pdf-tools/Caches\n"})}),(0,r.jsx)(s.p,{children:"If the user has no home directory:"}),(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{children:"<TempDirectory>/pdf-tools/Caches\n"})}),(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.code,{children:"<TempDirectory>"})," refers to the ",(0,r.jsx)(s.a,{href:"#temporary-files-directory",children:"directory for temporary files"}),"."]})]})]})]})}function x(e={}){let{wrapper:s}={...(0,i.R)(),...e.components};return s?(0,r.jsx)(s,{...e,children:(0,r.jsx)(u,{...e})}):u(e)}},617539(e,s,n){n.r(s),n.d(s,{default:()=>o});let o={tabList:"tabList_zI5C",tabItem:"tabItem_yeRP"}},327154(e,s,n){var o=this&&this.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(s,"__esModule",{value:!0}),s.default=function(e){let s=(0,t.default)(),n=(0,c.useTabsContextValue)(e);return r.default.createElement(c.TabsProvider,{value:n,key:String(s)},r.default.createElement(p,{className:e.className},(0,c.sanitizeTabsChildren)(e.children)))};

1let r=o(n(296540)),i=n(911988),t=o(n(19863)),l=o(n(571508)),d=n(892181),c=n(113042),a=o(n(617539));function h({className:e}){let{selectedValue:s,selectValue:n,tabValues:o,block:i}=(0,c.useTabs)(),t=[],{blockElementScrollPositionUntilNextRender:f}=(0,d.useScrollPositionBlocker)(),p=e=>{let r=e.currentTarget,i=o[t.indexOf(r)].value;i!==s&&(f(r),n(i))},u=e=>{let s=null;switch(e.key){case"Enter":p(e);break;case"ArrowRight":{let n=t.indexOf(e.currentTarget)+1;s=t[n]??t[0];break}case"ArrowLeft":{let n=t.indexOf(e.currentTarget)-1;s=t[n]??t[t.length-1]}}s?.focus()};return r.default.createElement("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,l.default)("tabs",{"tabs--block":i},e)},o.map(({value:e,label:n,attributes:o})=>r.default.createElement("li",{role:"tab",tabIndex:s===e?0:-1,"aria-selected":s===e,key:e,ref:e=>{t.push(e)},onKeyDown:u,onClick:p,...o,className:(0,l.default)("tabs__item",a.default.tabItem,o?.className,{"tabs__item--active":s===e})},n??e)))}function f({children:e}){return r.default.createElement("div",{className:"margin-top--md"},e)}function p({className:e,children:s}){return r.default.createElement("div",{className:(0,l.default)(i.ThemeClassNames.tabs.container,"tabs-container",a.default.tabList)},r.default.createElement(h,{className:e}),r.default.createElement(f,null,s))}}}]);